# SecurityTrails Developer Hub Documentation

> Documentation for SecurityTrails Developer Hub

## Guides
- [Overview](https://docs.securitytrails.com/docs/overview.md): Welcome to SecurityTrails! This page will help you get started. You'll be up and running in a jiffy!

## API Reference
- [Ping](https://docs.securitytrails.com/reference/ping-old-1.md): You can use this simple endpoint to test your authentication and access to the SecurityTrails API.
- [Get Domain](https://docs.securitytrails.com/reference/get-domain-old-1.md): Returns the current data about the given domain. In addition to the current data, you also get the current statistics associated with a particular record. For example, for a records you'll get how many other domains have the same IP.
- [Usage](https://docs.securitytrails.com/reference/usage-old-1.md)
- [Explore IPs](https://docs.securitytrails.com/reference/explore-ips-old-1.md): Returns the neighbors in any given IP level range and essentially allows you to explore closeby IP addresses.
- [Get WHOIS](https://docs.securitytrails.com/reference/get-whois-old-1.md): Returns the current WHOIS data about a given domain with the stats merged together
- [WHOIS history by domain](https://docs.securitytrails.com/reference/whois-history-by-domain-old-1.md): Returns historical WHOIS information about the given domain
- [Search Domain (filter)](https://docs.securitytrails.com/reference/search-old-1.md): Filter and search specific records using this endpoint.
- [List Subdomains](https://docs.securitytrails.com/reference/list-subdomains-old-1.md): Returns subdomains for a given hostname
- [Search statistics](https://docs.securitytrails.com/reference/search-count-old-1.md)
- [List Tags](https://docs.securitytrails.com/reference/list-tags-old-1.md): Returns tags for a given hostname
- [DNS history by record type](https://docs.securitytrails.com/reference/dns-history-by-record-type-old-1.md): Lists out specific historical information about the given hostname parameter
- [Find associated domains](https://docs.securitytrails.com/reference/find-associated-domains-old-1.md): Find all domains that are related to a domain you input
- [Search IPs (DSL)](https://docs.securitytrails.com/reference/search-ips-dsl-old-1.md)
- [IP Search statistics](https://docs.securitytrails.com/reference/ip-search-statistics-old-1.md)
- [Domains](https://docs.securitytrails.com/reference/domains-1-old-1.md): Fetch zone files including authoritative nameservers with ease
- [Scroll](https://docs.securitytrails.com/reference/scroll-old-1.md): A fast and easy way to fetch many results. Currently only available for the [DSL API](https://docs.securitytrails.com/reference#search-domain-dsl) endpoints.
- [Subdomains](https://docs.securitytrails.com/reference/subdomains-old-1.md)
- [Get Domain SSL](https://docs.securitytrails.com/reference/get-domain-ssl-data-old-1.md): Fetch current and historical certificate information for any domain or subdomain.
- [Get IP Whois](https://docs.securitytrails.com/reference/get-ip-whois-old-1.md): Fetch current IP information for a single IPv4 address.
- [Get Useragents](https://docs.securitytrails.com/reference/get-useragents-for-ip-old-1.md): Fetch user agents seen for a specific IPv4 address
- [Search Domain (DSL)](https://docs.securitytrails.com/reference/search-domain-dsl-2-1.md): Filter and search specific records using our DSL with this endpoint
- [Report Type](https://docs.securitytrails.com/reference/reports-report-type.md)
- [List Projects](https://docs.securitytrails.com/reference/project-list_projects-1.md): Retrieve the projects your user has access to
- [Search Assets](https://docs.securitytrails.com/reference/assets-search_assets-1.md): Search assets with optional filtering, pagination, and sorting.
- [Find Assets](https://docs.securitytrails.com/reference/assets-find_assets-1.md): Locate project assets through various filter criteria. Using this is an alternative to using the POST /_search endpoint, which allows for slightly more complex queries.  Some of the query parameters are not filter fields but control pagination and returns:  * `cursor`: Should be the value from a previous response's `meta.pagination.next_cursor` field * `limit`: The number of assets to return (default 50, max 1000) * `sort_by`: The field to sort by (default is exposure_score) * `additional_fields`: A list of additional fields to include in the response (default is custom_tags)   In some cases, you may specify a comma separated list of values which will be treated as an OR condition. To get AND functionality, use the POST search method.
- [Read Asset](https://docs.securitytrails.com/reference/assets-read_asset-1.md): Retrieve a specific asset by its ID within a project. Use the `additional_fields` to specify any extra information you want returned about the asset.
- [List Asset Exposures](https://docs.securitytrails.com/reference/assets-list_asset_exposures-1.md): Retrieve the detailed list of exposures for an asset, including the ports, signature details and any extracted data such as versions."
- [Get Filters](https://docs.securitytrails.com/reference/assets-get_filters-1.md): Retrieve the available filters for assets in the project.  The return values are unfiltered so represents a "top-level" set of filter values, with the default filters being: asset_type, custom_tags, ip_owner, severity, open_port_number and certificate_expires_at. A custom set of filter can be requested by passing a comma-separated list of filter fields in the query string.  The return values are intended to be usable by UI-type components that may render dropdowns, so each filter has a `name` which can be used as a label for a field. Additionally for each filter, there are `query` and `path` fields which represent the query string parameter and JSON dotted path to use for the filter.   NOTE: The "dotted path" is intended for the POST /_search endpoint and assists in knowing where to put the value. For example `exposure_properties.severity`, indicates you would send it in `{ "exposure_properties": {"severity": { "eq": "value" } } }`
- [Apply Tag To Asset](https://docs.securitytrails.com/reference/assets-apply_tag_to_asset-1.md): Apply a single user-defined tag to a specific asset.  As tagging is an asynchronous operation, the API will wait up to 2 seconds for the backend to complete but if it is still not complete in that time, the `task_ids` contained in the response can be used to continue to check status if the requested operation isn't reflected in later requests.  Even if the response includes `complete: true` there may still be a slight delay before requests allow for filtering or presentation of the tag on the asset.
- [Remove Tag From Asset](https://docs.securitytrails.com/reference/assets-remove_tag_from_asset-1.md): Remove a specific user-defined tag from an asset.  NOTE: If the tag is not on the asset, the request will be treated as successful.  As tagging is an asynchronous operation, the API will wait up to 2 seconds for the backend to complete but if it is still not complete in that time, the `task_ids` contained in the response can be used to continue to check status if the requested operation isn't reflected in later requests.  Even if the response includes `complete: true` there may still be a slight delay before requests allow for filtering or presentation of the tag on the asset.
- [Bulk Add Remove Asset Tags](https://docs.securitytrails.com/reference/assets-bulk_add_remove_asset_tags-1.md): Add and remove tags from the given asset.  As tagging is an asynchronous operation, the API will wait up to 2 seconds for the backend to complete but if it is still not complete in that time, the `task_ids` contained in the response can be used to continue to check status if the requested operation isn't reflected in later requests.  Even if the response includes `complete: true` there may still be a slight delay before requests allow for filtering or presentation of the tag on the asset.
- [Get Filters With Filter](https://docs.securitytrails.com/reference/assets-get_filters_with_filter.md): Retrieve available filters for assets in project similar to `GET` endpoint.  Include filter parameters in the request body to get filter values based on a filtered assets, similar to `/_search`.  The returned filters can be specified by including a list of filter fields in the request body. Otherwise the default filters will be returned: `asset_type`, `custom_tags`, `ip_owner`, `severity`, `open_port_number` and `certificate_expires_at`.
- [Get Tags](https://docs.securitytrails.com/reference/tagging-get_tags-1.md): Request the user-defined tags for the project.
- [Get Custom Tag Task Status](https://docs.securitytrails.com/reference/tagging-get_custom_tag_task_status-1.md): Get asset tagging status when it wasn't complete during first attempt  NOTE: Even if the response includes `complete: true` there may still be a slight delay before requests allow for filtering or presentation of the tag on the asset.
- [Bulk Add Remove Assets](https://docs.securitytrails.com/reference/tagging-bulk_add_remove_assets-1.md): Bulk tag assets within the project.  This method allows you, on an asset-by-asset, basis to add and remove tags which may be applied to them.  As tagging is an asynchronous operation, the API will wait up to 2 seconds for the backend to complete but if it is still not complete in that time, the `task_ids` contained in the response can be used to continue to check status if the requested operation isn't reflected in later requests.  Even if the response includes `complete: true` there may still be a slight delay before requests allow for filtering or presentation of the tag on the asset.
- [Add Tag](https://docs.securitytrails.com/reference/tagging-add_tag-1.md): Add a new user-defined tag to the project to be added to assets later.  If the tag already exists, it will be returned without error.
- [List Exposures](https://docs.securitytrails.com/reference/exposures-list_exposures-1.md)
- [Get Exposure Assets](https://docs.securitytrails.com/reference/exposures-get_exposure_assets-1.md)
- [Get Static Assets](https://docs.securitytrails.com/reference/rules-get_static_assets.md): Gets static assets for your project using the path parameter `project_id`. The response will include a list of static assets with their detail. The returned data can be filtered by `asset`, `static_type`, `membership_type`, `last_applied_before` and `last_applied_after`, if not provided, all assets will be returned.  In case the number of parameters exceeds the limit, default `100` and maximum `1000`, scrolling will be used to retrieve the next page of results. The `cursor` are returned in the `meta.pagination` field of the response, which can be used to retrieve the next page of results. If the `cursor` is `None`, there are no more pages available to scroll.
- [Add Static Assets](https://docs.securitytrails.com/reference/rules-add_static_assets.md): Allows you to perform bulk operations on static asset rules for your project. Rules can either be added or removed in bulk, with a maximum of 1000 rules per request.  To update a rule, applies for both add and remove operations, the asset name, membership and static type is required.  In case one or several static asset rules fail, those rules will be returned in the `errors` field of the response. The response will still be a `200 OK` response as long as the request was processed successfully.  NOTE: This is an asynchronous operation, and even if the request is handled successfully, the changes may not be immediately reflected in the system. You can check the status of the operation using the `get_static_assets` endpoint.
- [Get Associated IPs for Company Domain](https://docs.securitytrails.com/reference/get-company-associated-ips.md)

## Pages
- [SurfaceBrowser™ Changelog](https://docs.securitytrails.com/surfacebrowsertm-changelog.md)

## Changelog
- [Project API 1.7.0 Update](https://docs.securitytrails.com/changelog/project-api-170-update.md)
- [May 28th, 2020 update](https://docs.securitytrails.com/changelog/may-28th-2020-update.md)
- [May 14, 2020 update](https://docs.securitytrails.com/changelog/may-14-2020-update.md)
- [April 30, 2020 update](https://docs.securitytrails.com/changelog/april-30-2020-update.md)
- [April 13, 2020 update](https://docs.securitytrails.com/changelog/april-13-2020-update.md)