Censys Tags and Comments 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 Tags and Comments API
  version: 1.0.12
servers:
- description: Asset Graph API
  url: https://graph.data.censys.io
tags:
- description: Endpoints related to asset tagging and commenting
  name: Tags and Comments
paths:
  /v3/comments:
    get:
      description: Retrieve a paginated list of comments in your organization. Use query parameters to filter by asset, creator, or creation time.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-comments-list-comments
      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: Number of comments to return per page.
        explode: false
        in: query
        name: page_size
        schema:
          default: 100
          description: Number of comments to return per page.
          format: int32
          maximum: 1000
          minimum: 1
          type: integer
      - description: Pagination token from a previous response to retrieve the next page of results.
        explode: false
        in: query
        name: page_token
        schema:
          description: Pagination token from a previous response to retrieve the next page of results.
          type: string
      - description: 'Sort order. Supported values: create_time_asc, create_time_desc.'
        explode: false
        in: query
        name: order_by
        schema:
          default: create_time_desc
          description: 'Sort order. Supported values: create_time_asc, create_time_desc.'
          enum:
          - create_time_asc
          - create_time_desc
          type: string
      - description: Filter comments by asset identifier (host IP, certificate fingerprint, or web property hostname:port).
        explode: false
        in: query
        name: asset_id
        schema:
          description: Filter comments by asset identifier (host IP, certificate fingerprint, or web property hostname:port).
          type: string
      - description: Filter comments by the user ID of the user who created the comment.
        explode: false
        in: query
        name: created_by
        schema:
          description: Filter comments by the user ID of the user who created the comment.
          format: uuid
          type: string
      - description: Filter comments created before this RFC3339 timestamp.
        explode: false
        in: query
        name: created_before
        schema:
          description: Filter comments created before this RFC3339 timestamp.
          format: date-time
          type: string
      - description: Filter comments created after this RFC3339 timestamp.
        explode: false
        in: query
        name: created_after
        schema:
          description: Filter comments created after this RFC3339 timestamp.
          format: date-time
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeCommentsList'
          description: Comments retrieved successfully
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '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
        '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 List Comments
      tags:
      - Tags and Comments
      x-speakeasy-name-override: ListComments
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      description: Add a comment on an asset in your organization.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-comments-create-comment
      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/CreateCommentInputBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeComment'
          description: Comment created successfully
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '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
        '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 Comment
      tags:
      - Tags and Comments
      x-speakeasy-name-override: CreateComment
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/comments/{comment_id}:
    delete:
      description: Delete a comment. Only the comment's creator or an organization admin can delete a comment. This action is permanent and cannot be undone.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-comments-delete-comment
      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 ID of the comment to delete.
        in: path
        name: comment_id
        required: true
        schema:
          description: The ID of the comment to delete.
          format: uuid
          type: string
      responses:
        '204':
          description: Comment deleted successfully
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '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: Comment not 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 Delete a Comment
      tags:
      - Tags and Comments
      x-speakeasy-name-override: DeleteComment
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      description: Update the body of an existing comment. Only the comment's creator can update it.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-comments-update-comment
      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 ID of the comment to update.
        in: path
        name: comment_id
        required: true
        schema:
          description: The ID of the comment to update.
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCommentInputBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeComment'
          description: Comment updated successfully
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '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: Comment not 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 Update a Comment
      tags:
      - Tags and Comments
      x-speakeasy-name-override: UpdateComment
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/tags:
    get:
      description: Retrieve a paginated list of tags in your organization. Private tags created by other users are not included in the results unless your account is an organization admin.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-tags-list-tags
      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: Number of tags to return per page.
        explode: false
        in: query
        name: page_size
        schema:
          default: 100
          description: Number of tags to return per page.
          format: int32
          maximum: 1000
          minimum: 1
          type: integer
      - description: Pagination token from a previous response to retrieve the next page of results.
        explode: false
        in: query
        name: page_token
        schema:
          description: Pagination token from a previous response to retrieve the next page of results.
          type: string
      - description: 'Sort order. Supported values: name_asc, name_desc, created_at_asc, created_at_desc, updated_at_asc, updated_at_desc.'
        explode: false
        in: query
        name: order_by
        schema:
          default: name_asc
          description: 'Sort order. Supported values: name_asc, name_desc, created_at_asc, created_at_desc, updated_at_asc, updated_at_desc.'
          enum:
          - name_asc
          - name_desc
          - created_at_asc
          - created_at_desc
          - updated_at_asc
          - updated_at_desc
          type: string
      - description: Filter tags by name (exact match).
        explode: false
        in: query
        name: name
        schema:
          description: Filter tags by name (exact match).
          type: string
      - description: Filter tags by the user ID of the user who created the tag.
        explode: false
        in: query
        name: created_by
        schema:
          description: Filter tags by the user ID of the user who created the tag.
          format: uuid
          type: string
      - description: Filter tags by privacy setting.
        explode: false
        in: query
        name: privacy
        schema:
          description: Filter tags by privacy setting.
          enum:
          - private
          - shared
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeTagsList'
          description: Tags retrieved successfully
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '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
        '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 List Tags
      tags:
      - Tags and Comments
      x-speakeasy-name-override: ListTags
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      description: 'Create a new tag in your organization. Tags can be used to label and organize assets.<br><br>Specify a privacy setting to control visibility: `private` tags are only visible to you and organization admins, while `shared` tags are visible and manageable by all organization members.<br><br>Tag names must be unique within your organization.<br><br>This endpoint does not cost any credits to execute.'
      operationId: v3-tags-create-tag
      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/CreateTagInputBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelopeTag'
          description: Tag created successfully
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '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: Tag name already exists in this organization
        '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 Tag
      tags:
      - Tags and Comments
      x-speakeasy-name-override: CreateTag
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/tags/{tag_id}:
    delete:
      description: Delete a tag and all of its assignments from your organization. This action is permanent and cannot be undone.<br><br>Only the tag's creator or an organization admin can delete a `private` tag. Tags that are `shared` can be deleted by any organization member.<br><br>This endpoint does not cost any credits to execute.
      operationId: v3-tags-delete-tag
      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 ID of the tag to delete.
        in: path
        name: tag_id
        required: true
        schema:
          description: The ID of the tag to delete.
          format: uuid
          type: string
      responses:
        '204':
          description: Tag deleted successfully
          headers:
            Content-Type:
              schema:
                type: string
            X-Request-ID:
              schema:
                type: string
        '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

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