API Reference
Start typing to search…

Get Started with Censys APIs

The Censys Platform API provides programmatic access to the data available in the Censys Platform. The Platform API is organized around RESTful principles and follows a predictable, resource-oriented URL structure, supports application/JSON request bodies, returns JSON-encoded responses, and adheres to standard HTTP methods, authentication, and response codes.

API access is governed by the Censys Terms of Service and all scripted access should use this API. Your API rate limits are shown on the Censys Platform Personal Access Tokens page.

API endpoint and data access

  • The API is available to all users, but the endpoints you have access to varies based on your plan.
    • Free users only have access to host, web property, and certificate lookup (get a host, retrieve multiple hosts, get a certificate, retrieve multiple certificates, get a web property, and retrieve multiple web properties) endpoints.
    • Starter users have access to all Global Data and Collections endpoints except the Live Rescan endpoint.
    • Enterprise users have access to all Global Data and Collections endpoints.
    • Enterprise users with access to the Threat Hunting module have access to all Global Data, Collections, and Threat Hunting endpoints.
  • API calls consume credits. For more information about API credit consumption, see Censys Credits.
  • API usage aligns with the data access capacity of your tier. For example, the Starter tier can view one week of host history while the Enterprise tier can view at least one month of history. For more information, see Feature and Data Access Tiers.

Transition from Legacy Search API

To ensure a smooth transition from the Legacy Search API to the Platform API, please note the following:

  • Base URL: There is a new base URL for the Censys Platform API.
  • Access token: There is a new process to generate a Personal Access Token.
  • Review any downstream applications that receive data from the API.
  • See SDK section below. These differ from the Legacy Search SDKs.

SDKs

The following Platform SDKs are available:

API setup and usage

Follow the steps below to begin using the Censys API.

Step 1: API Access Role for Enterprise and Starter users

In order to use the API as a member of an organization on a Starter or Enterprise plan, you must be assigned the API Access Role. To learn more about roles, see Role-Based Access Control.

Free users do not need to have the API Access Role in order to use the API.

Step 2: Create a Personal Access Token

The Censys Platform API uses Personal Access Tokens to authenticate requests. Users can generate multiple PATs as needed.

  1. Go to Account Management > Personal Access Tokens.

  2. Click Create New Token.

  3. Name your PAT in the Token Name field (required) and add a description (optional).

  4. Click Create.

  5. A confirmation dialog appears when the token is successfully created. Click Copy to clipboard and store your token in a secure location for future use. The token value is found at the bottom of the dialog.

🚧

Warning

Your Personal Access Tokens grant significant access, so keep them secure. Never expose API keys in public areas like GitHub or client-side code.

Delete a Personal Access Token

Follow the steps below to delete a token:

  1. Go to My Account > Personal Access Tokens tab.
  2. Locate the token that you want to delete.
  3. Click the trash can icon on the token card.

Step 3: Find and use your organization ID (optional)

The Censys Platform API identifies the entitlements and billing details for your request based on the provided organization ID.

Starter users and Enterprise organizations have an organization ID. Free users do not have an organization ID.

If you do not include an organization ID in your API requests, then it will attempt to execute the API using the permissions associated with your Free account.

To find your organization ID:

  1. Go the the Censys Platform. Ensure that you have your Starter or Enterprise account selected.
  2. Your organization ID is provided in the URL after org=.
📘

Note

The organization ID can be set via query parameter or header. If values are provided for both, the query parameter takes precedence.

Header

After you identify your organization ID, you can include it in the header or as a query parameter.

--header 'X-Organization-ID: 12345678-91011-1213'

Query Parameter

organization_id=12345678-91011-1213

Step 4: Understand Headers

You can include the following headers when making requests to the Censys Platform API.

Personal Access Token (PAT) (Required)

You must include a valid PAT to make API requests. Use the format below to set your PAT in the header.

--header 'Authorization: Bearer censys_ex_token'

Organization ID (Optional)

You can set your organization ID in the header or in the query parameters. Use the format below to set your organization ID as a header.

--header 'X-Organization-ID: 12345678-91011-1213'

Accept (Optional)

The Accept header uses a vendor-specific content type, which specifies both the desired response format (JSON) and the version of the asset schema (host, certificate, web property) the client expects to receive. This allows users to explicitly request a compatible schema version, even as the API and data models evolve over time.

If you don't include this header, your call will return the most recent schema version. Currently, there is one schema version available.

Format

Use the format below to create a valid Accept header.

application/vnd.censys.api.{api_version}.{asset_name}.{asset_version}+json

The example below is the Accept header for the Asset / Host endpoint.

Accept: application/vnd.censys.api.v3.host.v1+json

Explanation

This example above requests the following:

  • API Version: v3
  • Asset Type: host
  • Schema Version: v1
  • Format: json

Step 5: Make API calls

After you create a PAT, you can start making API calls using cURL, Postman, or the Try It feature on the reference documentation page. The Censys Platform API typically follows standard HTTP response codes to indicate whether a request was successful or failed.

Example cURL API call

The example cURL request below is for Asset / Host endpoint. This call includes the organization ID as a query parameter.

curl --request GET \
     --url 'https://api.platform.censys.io/v3/global/asset/host/47.33.210.14?organization_id=12345678-91011-1213' \
     --header 'Accept: application/vnd.censys.api.v3.host.v1+json' \
     --header 'Authorization: Bearer censys_ex_token'

The cURL request below includes the Organization ID in the header.

curl --request GET \
     --url 'https://api.platform.censys.io/v3/global/asset/host/47.33.210.14' \
     --header 'X-Organization-ID: 12345678-91011-1213' \
     --header 'Accept: application/vnd.censys.api.v3.host.v1+json' \
     --header 'Authorization: Bearer censys_ex_token'

Example response

Click the header below to view an example response.

Example Response
{
"result": {
  "resource": {
    "ip": "27.33.219.14",
    "location": {
      "continent": "North America",
      "country": "United States",
      "country_code": "US",
      "city": "Mount Pleasant",
      "postal_code": "48858",
      "timezone": "America/Detroit",
      "province": "Michigan",
      "coordinates": {
        "latitude": 43.59781,
        "longitude": -84.76751
      }
    },
    "autonomous_system": {
      "asn": 20115,
      "description": "ACME-20115",
      "bgp_prefix": "47.33.192.0/19",
      "name": "ACME-20115",
      "country_code": "US"
    },
    "whois": {
      "network": {
        "handle": "AC04",
        "name": "Acme",
        "cidrs": [
          "47.32.0.0/12",
          "47.48.0.0/14"
        ],
        "created": "2014-12-23T00:00:00Z",
        "updated": "2014-12-23T00:00:00Z",
        "allocation_type": "ALLOCATION"
      },
      "organization": {
        "handle": "CC04",
        "name": "Acme",
        "street": "6175 S. Willow Dr",
        "city": "Greenwood Village",
        "state": "CO",
        "postal_code": "80111",
        "country": "US",
        "abuse_contacts": [
          {
            "handle": "ABUSE19-ARIN",
            "name": "Abuse",
            "email": "[email protected]"
          }
        ],
        "admin_contacts": [
          {
            "handle": "IPADD1-VRIN",
            "name": "IPAddressing",
            "email": "[email protected]"
          }
        ],
        "tech_contacts": [
          {
            "handle": "IPADD1-VRIN",
            "name": "IPAddressing",
            "email": "[email protected]"
          }
        ]
      }
    },
    "services": [
      {
        "port": 7547,
        "protocol": "CWMP",
        "transport_protocol": "tcp",
        "ip": "47.24.210.14",
        "scan_time": "2025-03-06T19:03:55Z",
        "banner_hash_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "cwmp": {
          "auth": [
            "Digest realm=\"Sagemcom TR-069\", qop=\"auth,auth-int\", nonce=<REDACTED>, opaque=\"ddb504c1\""
          ],
          "server": "gSOAP/2.7"
        }
      }
    ],
    "service_count": 1,
    "dns": {
      "reverse_dns": {
        "resolve_time": "2025-02-13T14:02:41Z",
        "names": [
          "syn-047-033-210-014.res.acme.com"
        ]
      },
      "names": [
        "syn-047-033-210-014.res.spectrum.com"
      ],
      "forward_dns": {
        "syn-047-033-210-014.res.acme.com": {
          "resolve_time": "2025-02-27T20:21:52Z",
          "name": "syn-047-033-210-014.res.acme.com",
          "record_type": "a"
        }
      }
    }
  },
  "extensions": {}
}
}

Step 6: Handle HTTP response codes

Error Code

Description

Resolution

200

OK - Your call was successful.

Success

401

Your request doesn't contain a valid Authorization token.

Verify whether you used the correct PAT or generate a new PAT.

403

User does not have permission to access this data.

Ask your admin to grant you API Access Role. Verify that your user tier offers the data requested.

404

Not Found

Insufficient permissions for the resource; it could be a resource from a different org, etc.

422

Unprocessable Entity

Misconfigured or incorrect value. Some examples: incompatible search filters, malformed query string, invalid pagination parameters etc.

422

Missing Organization ID

Enter a valid organization ID as a query parameter or in the header.

422

Unprocessable Entity

Enter a valid query parameter.

500

Internal Server

General issue, try again later.

Next steps

API rate limits

Rate limits are associated with your account tier.

TierConcurrent Actions
Free1 concurrent action
Starter1 concurrent action
Enterprise10 concurrent actions

Base URL

Before making requests, use the following Base URL for Global Data API endpoints:

https://api.platform.censys.io/v3/global/

All API requests to Global Data endpoints must be sent to this base URL, with the appropriate endpoint appended.

The base URL for Collections APIs is:

https://api.platform.censys.io/v3/collections/

The base URL for Threat Hunting APIs is:

https://api.platform.censys.io/v3/collections/