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 Seeds API
  version: 1.0.12
servers:
- description: Asset Graph API
  url: https://graph.data.censys.io
tags:
- name: Seeds
paths:
  /api/v1/asset-graphs/{graph_id}/seeds:
    get:
      description: List all seeds configured for an asset graph.
      operationId: list-seeds
      parameters:
      - description: Censys organization ID
        in: header
        name: X-Organization-ID
        required: true
        schema:
          description: Censys organization ID
          format: uuid
          type: string
      - description: Asset graph ID
        in: path
        name: graph_id
        required: true
        schema:
          description: Asset graph ID
          format: uuid
          type: string
      - description: Pagination token from a previous response
        explode: false
        in: query
        name: page_token
        schema:
          description: Pagination token from a previous response
          type: string
      - description: Maximum number of results to return
        explode: false
        in: query
        name: page_size
        schema:
          description: Maximum number of results to return
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSeedsOutputBody'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - PersonalAccessToken: []
      summary: Censys List Seeds
      tags:
      - Seeds
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      description: 'Add a seed to an asset graph. Seeds are persistent starting points used to discover additional assets. Supported seed types include IP addresses, domains, CIDRs, ASNs, certificates, and web properties.


        Modifications to seeds take effect during the next execution of the graph.'
      operationId: create-seed
      parameters:
      - description: Censys organization ID
        in: header
        name: X-Organization-ID
        required: true
        schema:
          description: Censys organization ID
          format: uuid
          type: string
      - description: Asset graph ID
        in: path
        name: graph_id
        required: true
        schema:
          description: Asset graph ID
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetRef'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Seed'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - PersonalAccessToken: []
      summary: Censys Create a Seed
      tags:
      - Seeds
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v1/asset-graphs/{graph_id}/seeds/{seed_id}:
    delete:
      description: Remove a seed from an asset graph. The removal takes effect during the next execution of the graph.
      operationId: delete-seed
      parameters:
      - description: Censys organization ID
        in: header
        name: X-Organization-ID
        required: true
        schema:
          description: Censys organization ID
          format: uuid
          type: string
      - description: Asset graph ID
        in: path
        name: graph_id
        required: true
        schema:
          description: Asset graph ID
          format: uuid
          type: string
      - description: Seed identifier
        in: path
        name: seed_id
        required: true
        schema:
          description: Seed identifier
          type: string
      responses:
        '204':
          description: No Content
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
      - PersonalAccessToken: []
      summary: Censys Delete a Seed
      tags:
      - Seeds
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ListSeedsOutputBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://graph.data.censys.io/schemas/ListSeedsOutputBody.json
          format: uri
          readOnly: true
          type: string
        next_page_token:
          description: Token for the next page of results
          type: string
        seeds:
          description: List of seeds
          items:
            $ref: '#/components/schemas/Seed'
          type:
          - array
          - 'null'
      required:
      - seeds
      type: object
    AssetRef:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://graph.data.censys.io/schemas/AssetRef.json
          format: uri
          readOnly: true
          type: string
        autonomous_system:
          description: Autonomous system number (ASN)
          format: int32
          minimum: 0
          type: integer
        business_organization:
          description: Organization name
          type: string
        certificate:
          description: SHA-256 fingerprint of a certificate (hex-encoded)
          type: string
        domain:
          description: Domain name
          type: string
        host:
          description: IP address of a host
          type: string
        id:
          description: Asset id, matching the id returned by the get-asset endpoint. Populated on responses; ignored on input.
          type: string
        netblock:
          description: CIDR notation (e.g. 192.168.0.0/24)
          type: string
        registrant_email:
          description: Registrant email address
          type: string
        registrant_organization:
          description: Registrant organization name
          type: string
        web_property:
          $ref: '#/components/schemas/WebPropertyIdentifier'
          description: Web property (hostname and port)
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://graph.data.censys.io/schemas/ErrorModel.json
          format: uri
          readOnly: true
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
          - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
          - array
          - 'null'
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
          - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
          - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
          - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
          - https://example.com/errors/example
          format: uri
          type: string
      type: object
    WebPropertyIdentifier:
      additionalProperties: false
      properties:
        hostname:
          description: Hostname of the web property
          type: string
        port:
          description: Port of the web property
          format: int32
          minimum: 0
          type: integer
      required:
      - hostname
      - port
      type: object
    Seed:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
          - https://graph.data.censys.io/schemas/Seed.json
          format: uri
          readOnly: true
          type: string
        autonomous_system:
          description: Autonomous system number (ASN)
          format: int32
          minimum: 0
          type: integer
        business_organization:
          description: Organization name
          type: string
        certificate:
          description: SHA-256 fingerprint of a certificate (hex-encoded)
          type: string
        create_time:
          description: RFC3339 creation timestamp
          type: string
        domain:
          description: Domain name
          type: string
        host:
          description: IP address of a host
          type: string
        id:
          description: Unique identifier for the seed
          type: string
        netblock:
          description: CIDR notation (e.g. 192.168.0.0/24)
          type: string
        registrant_email:
          description: Registrant email address
          type: string
        registrant_organization:
          description: Registrant organization name
          type: string
        web_property:
          $ref: '#/components/schemas/WebPropertyIdentifier'
          description: Web property (hostname and port)
      required:
      - id
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
  securitySchemes:
    PersonalAccessToken:
      description: Your Censys personal access token.
      scheme: bearer
      type: http
x-speakeasy-globals:
  parameters:
  - in: header
    name: X-Organization-ID
    schema:
      type: string
    x-speakeasy-globals-hidden: true