Censys Collections API

openapi: 3.1.0
info:
  contact:
    email: support@censys.io
    name: Censys Support
  description: '# Asset Graph API


    The Asset Graph API provides comprehensive visibility into your Internet-facing assets. Use this API to build and manage attack surfaces by creating asset graphs, configuring seeds and exclusions, running discovery executions, and retrieving discovered assets and risk metadata.


    ### Authentication


    All requests must include a valid Censys personal access token (PAT) in the `Authorization` header:


    ```

    Authorization: Bearer <your-api-token>

    ```


    An `X-Organization-ID` header must also be present on every request. This identifies the Censys organization that owns the resources being accessed.


    ```

    X-Organization-ID: <your-organization-id>

    ```


    ### Core Concepts


    - **Asset Graph**: The parent resource representing an attack surface. Each asset graph contains seeds, excluded assets, and executions.

    - **Seeds**: Persistent starting points used to discover additional assets. Supported types include IP addresses, domains, CIDRs, ASNs, certificates, and web properties.

    - **Excluded Assets**: Assets explicitly excluded from the graph. Excluded assets will not appear in execution results and will not be used to discover additional assets.

    - **Executions**: A discovery process that uses the graph''s configured seeds and excluded assets to generate a complete snapshot of the attack surface. Censys periodically runs executions in the background, or they can be triggered on-demand.

    - **Assets**: Internet-facing resources discovered during an execution, including hosts, domains, certificates, and web properties. Each asset includes discovery paths showing how it was found from your seeds.

    - **Risks**: Vulnerabilities, exposures, misconfigurations, and threats identified on discovered assets.


    ### Getting Started


    1. **Create an asset graph** to represent your attack surface.

    2. **Add seeds** — the known assets that Censys will use as starting points for discovery.

    3. **Optionally add excluded assets** to omit specific assets from results.

    4. **Create an execution** to trigger the discovery process, or wait for Censys to run one automatically.

    5. **List assets** from a completed execution to view your discovered attack surface.

    6. **Look up risk metadata** for any risk IDs found on your assets.

    '
  title: Asset Graph Account Management Collections API
  version: 1.0.12
servers:
- description: Asset Graph API
  url: https://graph.data.censys.io
tags:
- description: Endpoints related to the Collections product
  name: Collections
paths:
  /v3/collections:
    get:
      description: List all collections for an organization. Retrieved information includes collection ID, name, query, description, status, and asset count.<br><br>This endpoint does not cost credits to execute.
      operationId: v3-collections-crud-list
      parameters:
      - description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        explode: false
        in: query
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
        example: 11111111-2222-3333-4444-555555555555
        in: header
        name: X-Organization-ID
        schema:
          description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
        x-speakeasy-ignore: true
      - description: page token for the requested page of collection results
        explode: false
        in: query
        name: page_token
        schema:
          description: page token for the requested page of collection results
          type: string
      - description: amount of results to return per page
        example: 1
        explode: false
        in: query
        name: page_size
        schema:
          description: amount of results to return per page
          examples:
          - 1
          format: int64
          minimum: 0
          type: integer
      - description: statuses of collection for results to be filtered on.
        example:
        - populating
        - active
        explode: false
        in: query
        name: collection_statuses
        schema:
          description: statuses of collection for results to be filtered on.
          examples:
          - - populating
            - active
          items:
            enum:
            - populating
            - active
            - paused
            - archived
            type: string
          maxItems: 4
          type:
          - array
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeListCollectionsResponseV1'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys List Collections
      tags:
      - Collections
      x-speakeasy-name-override: List
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      description: Create a new collection.<br><br>This endpoint does not cost credits to execute.
      operationId: v3-collections-crud-create
      parameters:
      - description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        explode: false
        in: query
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
        example: 11111111-2222-3333-4444-555555555555
        in: header
        name: X-Organization-ID
        schema:
          description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
        x-speakeasy-ignore: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrudCreateInputBody'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeCollection'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '409':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Conflict
        '412':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Collection limit exceeded
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Invalid input
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys Create a Collection
      tags:
      - Collections
      x-speakeasy-name-override: Create
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/collections/{collection_uid}:
    delete:
      description: Delete a collection.<br><br>This endpoint does not cost credits to execute.
      operationId: v3-collections-crud-delete
      parameters:
      - description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        explode: false
        in: query
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
        example: 11111111-2222-3333-4444-555555555555
        in: header
        name: X-Organization-ID
        schema:
          description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
        x-speakeasy-ignore: true
      - description: The UID for the collection. Obtain the collection ID using the [list collections endpoint](https://docs.censys.com/reference/v3-collections-crud-list#/) or via the collection URL when using the web console.
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: collection_uid
        required: true
        schema:
          description: The UID for the collection. Obtain the collection ID using the [list collections endpoint](https://docs.censys.com/reference/v3-collections-crud-list#/) or via the collection URL when using the web console.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      responses:
        '204':
          description: Empty response body when the deletion is successful
          headers:
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: No collection found
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys Delete a Collection
      tags:
      - Collections
      x-speakeasy-name-override: Delete
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      description: Retrieve information about a collection. Retrieved information includes its name, query, description, status, and asset count.<br><br>This endpoint does not cost credits to execute.
      operationId: v3-collections-crud-get
      parameters:
      - description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        explode: false
        in: query
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
        example: 11111111-2222-3333-4444-555555555555
        in: header
        name: X-Organization-ID
        schema:
          description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
        x-speakeasy-ignore: true
      - description: The UID for the collection. Obtain the collection ID using the [list collections endpoint](https://docs.censys.com/reference/v3-collections-crud-list#/) or via the collection URL when using the web console.
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: collection_uid
        required: true
        schema:
          description: The UID for the collection. Obtain the collection ID using the [list collections endpoint](https://docs.censys.com/reference/v3-collections-crud-list#/) or via the collection URL when using the web console.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeCollection'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: No collection found
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys Get a Collection
      tags:
      - Collections
      x-speakeasy-name-override: Get
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      description: Update a collection's name, description, and/or query.<br><br>This endpoint does not cost credits to execute.
      operationId: v3-collections-crud-update
      parameters:
      - description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        explode: false
        in: query
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
        example: 11111111-2222-3333-4444-555555555555
        in: header
        name: X-Organization-ID
        schema:
          description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
        x-speakeasy-ignore: true
      - description: The UID for the collection
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: collection_uid
        required: true
        schema:
          description: The UID for the collection
          examples:
          - 11111111-2222-3333-4444-555555555555
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrudUpdateInputBody'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeCollection'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: No collection found
        '412':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Collection is paused or archived
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys Update a Collection
      tags:
      - Collections
      x-speakeasy-name-override: Update
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/collections/{collection_uid}/events:
    get:
      description: Retrieve the event history for a collection. This includes the addition or removal of assets as well as collection status changes.<br><br>This endpoint does not cost credits to execute.
      operationId: v3-collections-list-events
      parameters:
      - description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        explode: false
        in: query
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
        example: 11111111-2222-3333-4444-555555555555
        in: header
        name: X-Organization-ID
        schema:
          description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
        x-speakeasy-ignore: true
      - description: The UID for the collection. Obtain the collection ID using the [list collections endpoint](https://docs.censys.com/reference/v3-collections-crud-list#/) or via the collection URL when using the web console.
        example: 11111111-2222-3333-4444-555555555555
        in: path
        name: collection_uid
        required: true
        schema:
          description: The UID for the collection. Obtain the collection ID using the [list collections endpoint](https://docs.censys.com/reference/v3-collections-crud-list#/) or via the collection URL when using the web console.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: Amount of results to return per page.
        example: 1
        explode: false
        in: query
        name: page_size
        schema:
          description: Amount of results to return per page.
          examples:
          - 1
          format: int32
          minimum: 0
          type: integer
      - description: Page token for the requested page of collection results.
        explode: false
        in: query
        name: page_token
        schema:
          description: Page token for the requested page of collection results.
          type: string
      - description: Change types
        explode: false
        in: query
        name: change_types
        schema:
          description: Change types
          items:
            enum:
            - asset
            - status
            type: string
          type:
          - array
          - 'null'
      - description: Asset change types
        explode: false
        in: query
        name: asset_change_types
        schema:
          description: Asset change types
          items:
            enum:
            - added
            - removed
            type: string
          type:
          - array
          - 'null'
      - description: Status change types
        explode: false
        in: query
        name: status_change_types
        schema:
          description: Status change types
          items:
            enum:
            - active
            - archived
            - paused
            - populating
            type: string
          type:
          - array
          - 'null'
      - description: Start time of the host timeline
        example: '2025-01-01T00:00:00Z'
        explode: false
        in: query
        name: start_time
        schema:
          description: Start time of the host timeline
          examples:
          - '2025-01-01T00:00:00Z'
          format: date-time
          type: string
      - description: End time of the host timeline
        example: '2025-01-02T00:00:00Z'
        explode: false
        in: query
        name: end_time
        schema:
          description: End time of the host timeline
          examples:
          - '2025-01-02T00:00:00Z'
          format: date-time
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeCollectionEventsResponse'
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
          description: Request does not contain a valid Authorization token
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: User does not have permission to access this data
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: No collection found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Invalid input
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal server error
      security:
      - PersonalAccessToken: []
      summary: Censys Get a Collection's Events
      tags:
      - Collections
      x-speakeasy-name-override: ListEvents
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/collections/{collection_uid}/search/aggregate:
    post:
      description: Aggregate results for a Platform search query that targets a collection's assets. This functionality is equivalent to the [Report Builder](https://docs.censys.com/docs/platform-report-builder#/) in the Platform web UI.
      operationId: v3-collections-search-aggregate
      parameters:
      - description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
        example: 11111111-2222-3333-4444-555555555555
        explode: false
        in: query
        name: organization_id
        required: true
        schema:
          description: The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information.
          examples:
          - 11111111-2222-3333-4444-555555555555
          format: uuid
          type: string
      - description: 'The ID of a Censys organization to associate the request with. See the [Getting Started docs](https://docs.censys.com/reference/get-started#step-3-find-and-use-your-organization-id-optional) for more information. Note: The header parameter is supported for atypical use cases; we recommend always providing this field via the query parameter.'
        example: 11111111-2222-3333-4444-555555555555
        in: header
        name: X-Organization-ID
        schema:
          description: 'The ID of a C

# --- truncated at 32 KB (330 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/censys/refs/heads/main/openapi/censys-collections-api-openapi.yml