Get Started

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.

Before you begin: usage and data access

• The API is available for Starter and Enterprise tiers, but not for Free tier users.
• API calls consume credits, just like actions in the Platform UI. The number of credits used by an API request corresponds to the same actions performed in the UI, such as executing searches. For more information, 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 one month of history. For more information, see Data Access Tiers and Entitlements.

Transition from Legacy API

The Platform now includes a new API. To ensure a smooth transition, please update 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.

Quick start

Follow the steps below to begin using the Censys API.

Step 1: API Access Role

To use the Platform API, you must be assigned the API Access Role. To learn more about roles, see Role-Based Access Control.

Step 2: Authenticate with 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 My Account > Personal Access Tokens tab.

   

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.

   

4. The token is deleted.

Step 3: Set your Organization ID

The Censys Platform API identifies the entitlements and billing details for your request based on the provided Organization ID. To locate your Organization ID:

1. Go the the Censys Platform.
2. Click on My Account.
3. The Organization ID is located in the URL.

📘

Note

The Organization ID can be set via query parameter or header. If values are provided for both, the query parameter takes precedence. An Organization ID must be provided for each request to the API.

Header

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

--header 'X-Organization-ID: c486f89f-8e4d-4c7a-830d-8d1d5b822c20'

Query Parameter

organization_id=c486f89f-8e4d-4c7a-830d-8d1d5b822c20

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_1AW2vmJf_Q8849MHxQiQZwZEattrJK9wL'

Organization ID (Optional)

You can set your Organization ID in the header or in the query parameters, but it is required in one of these fields. Use the format below to set your Organization ID as a header.

--header 'X-Organization-ID: c486f89f-8e4d-4c7a-830d-8d1d5b822c20'

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=c486f89f-8e4d-4c7a-830d-8d1d5b822c20' \
     --header 'Accept: application/vnd.censys.api.v3.host.v1+json' \
     --header 'Authorization: Bearer censys_1AW2vmJf_Q8849MHxQiQZwZEattrJK9wL'

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: c486f89f-8e4d-4c7a-830d-8d1d5b822c20' \
     --header 'Accept: application/vnd.censys.api.v3.host.v1+json' \
     --header 'Authorization: Bearer censys_1AW2vmJf_Q8849MHxQiQZwZEattrJK9wL'

Example response

Click the header below to view an 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

Next steps

API rate limits

Rate limits are associated with your account tier.

Base URL

Before making requests, use the following Base URL for Global Data 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 API is:

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