Censys Platform — Tags and Comments

naftiko: 1.0.0-alpha2
info:
  label: Censys Platform — Tags and Comments
  description: 'Censys Platform — Tags and Comments. 12 operation(s). Lead operation: Censys List Comments. Self-contained Naftiko capability covering one Censys business surface.'
  tags:
    - Censys
    - Platform
    - Tags and Comments
  created: '2026-05-29'
  modified: '2026-05-29'
binds:
  - namespace: env
    keys:
      CENSYS_PERSONAL_ACCESS_TOKEN: CENSYS_PERSONAL_ACCESS_TOKEN
capability:
  consumes:
    - type: http
      namespace: platform-tags-and-comments
      baseUri: https://api.platform.censys.io
      description: Censys Platform — Tags and Comments business capability. Self-contained, no shared references.
      authentication:
        type: bearer
        token: '{{env.CENSYS_PERSONAL_ACCESS_TOKEN}}'
      resources:
        - name: v3-comments
          path: /v3/comments
          operations:
            - name: v3-comments-list-comments
              method: GET
              description: Censys List Comments
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Number of comments to return per page.
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Pagination token from a previous response to retrieve the next page of results.
                - name: order_by
                  in: query
                  type: string
                  required: false
                  description: "Sort order. Supported values: create_time_asc, create_time_desc."
                - name: asset_id
                  in: query
                  type: string
                  required: false
                  description: Filter comments by asset identifier (host IP, certificate fingerprint, or web property hostname:port).
                - name: created_by
                  in: query
                  type: string
                  required: false
                  description: Filter comments by the user ID of the user who created the comment.
                - name: created_before
                  in: query
                  type: string
                  required: false
                  description: Filter comments created before this RFC3339 timestamp.
                - name: created_after
                  in: query
                  type: string
                  required: false
                  description: Filter comments created after this RFC3339 timestamp.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: v3-comments-create-comment
              method: POST
              description: Censys Create a Comment
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-comments-comment-id
          path: /v3/comments/{comment_id}
          operations:
            - name: v3-comments-delete-comment
              method: DELETE
              description: Censys Delete a Comment
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: comment_id
                  in: path
                  type: string
                  required: true
                  description: The ID of the comment to delete.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: v3-comments-update-comment
              method: PUT
              description: Censys Update a Comment
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: comment_id
                  in: path
                  type: string
                  required: true
                  description: The ID of the comment to update.
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-tags
          path: /v3/tags
          operations:
            - name: v3-tags-list-tags
              method: GET
              description: Censys List Tags
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Number of tags to return per page.
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Pagination token from a previous response to retrieve the next page of results.
                - name: order_by
                  in: query
                  type: string
                  required: false
                  description: "Sort order. Supported values: name_asc, name_desc, created_at_asc, created_at_desc, updated_at_asc, updated_at_desc."
                - name: name
                  in: query
                  type: string
                  required: false
                  description: Filter tags by name (exact match).
                - name: created_by
                  in: query
                  type: string
                  required: false
                  description: Filter tags by the user ID of the user who created the tag.
                - name: privacy
                  in: query
                  type: string
                  required: false
                  description: Filter tags by privacy setting.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: v3-tags-create-tag
              method: POST
              description: Censys Create a Tag
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-tags-tag-id
          path: /v3/tags/{tag_id}
          operations:
            - name: v3-tags-delete-tag
              method: DELETE
              description: Censys Delete a Tag
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: tag_id
                  in: path
                  type: string
                  required: true
                  description: The ID of the tag to delete.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: v3-tags-get-tag
              method: GET
              description: Censys Get a Tag
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: tag_id
                  in: path
                  type: string
                  required: true
                  description: The ID or name of the tag to retrieve.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: v3-tags-update-tag
              method: PUT
              description: Censys Update a Tag
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: tag_id
                  in: path
                  type: string
                  required: true
                  description: The ID of the tag to update.
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-tags-tag-id-assignments
          path: /v3/tags/{tag_id}/assignments
          operations:
            - name: v3-tags-list-assignments
              method: GET
              description: Censys List Tag Assignments
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: tag_id
                  in: path
                  type: string
                  required: true
                  description: The ID of the tag whose assignments to list.
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Number of assignments to return per page.
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Pagination token from a previous response to retrieve the next page of results.
                - name: order_by
                  in: query
                  type: string
                  required: false
                  description: "Sort order. Supported values: create_time_asc, create_time_desc."
                - name: asset_id
                  in: query
                  type: string
                  required: false
                  description: The identifier of the asset (host IP, certificate SHA-256 fingerprint, or web property hostname:port).
                - name: created_before
                  in: query
                  type: string
                  required: false
                  description: RFC3339 timestamp. Only return assignments created before this time.
                - name: created_after
                  in: query
                  type: string
                  required: false
                  description: RFC3339 timestamp. Only return assignments created after this time.
                - name: created_by
                  in: query
                  type: string
                  required: false
                  description: Filter by the user ID of the user who created the assignment.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: v3-tags-create-assignment
              method: POST
              description: Censys Create a Tag Assignment
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: tag_id
                  in: path
                  type: string
                  required: true
                  description: The ID of the tag to assign.
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-tags-tag-id-assignments-assignment-id
          path: /v3/tags/{tag_id}/assignments/{assignment_id}
          operations:
            - name: v3-tags-delete-assignment
              method: DELETE
              description: Censys Delete a Tag Assignment
              inputParameters:
                - name: organization_id
                  in: query
                  type: string
                  required: true
                  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.
                - name: X-Organization-ID
                  in: header
                  type: string
                  required: false
                  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."
                - name: tag_id
                  in: path
                  type: string
                  required: true
                  description: The ID of the tag.
                - name: assignment_id
                  in: path
                  type: string
                  required: true
                  description: The ID of the assignment to delete.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
  exposes:
    - type: rest
      namespace: platform-tags-and-comments-rest
      port: 8080
      description: REST adapter for Censys Platform — Tags and Comments. One Spectral-compliant resource per consumed operation, prefixed with /v1.
      resources:
        - path: /v1/comments
          name: comments
          description: REST surface for comments.
          operations:
            - method: GET
              name: v3-comments-list-comments
              description: Censys List Comments
              call: platform-tags-and-comments.v3-comments-list-comments
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                page_size: rest.page_size
                page_token: rest.page_token
                order_by: rest.order_by
                asset_id: rest.asset_id
                created_by: rest.created_by
                created_before: rest.created_before
                created_after: rest.created_after
              outputParameters:
                - type: object
                  mapping: $.
            - method: POST
              name: v3-comments-create-comment
              description: Censys Create a Comment
              call: platform-tags-and-comments.v3-comments-create-comment
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/comments/{comment_id}
          name: comments-comment-id
          description: REST surface for comments-comment-id.
          operations:
            - method: DELETE
              name: v3-comments-delete-comment
              description: Censys Delete a Comment
              call: platform-tags-and-comments.v3-comments-delete-comment
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                comment_id: rest.comment_id
              outputParameters:
                - type: object
                  mapping: $.
            - method: PUT
              name: v3-comments-update-comment
              description: Censys Update a Comment
              call: platform-tags-and-comments.v3-comments-update-comment
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                comment_id: rest.comment_id
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/tags
          name: tags
          description: REST surface for tags.
          operations:
            - method: GET
              name: v3-tags-list-tags
              description: Censys List Tags
              call: platform-tags-and-comments.v3-tags-list-tags
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                page_size: rest.page_size
                page_token: rest.page_token
                order_by: rest.order_by
                name: rest.name
                created_by: rest.created_by
                privacy: rest.privacy
              outputParameters:
                - type: object
                  mapping: $.
            - method: POST
              name: v3-tags-create-tag
              description: Censys Create a Tag
              call: platform-tags-and-comments.v3-tags-create-tag
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/tags/{tag_id}
          name: tags-tag-id
          description: REST surface for tags-tag-id.
          operations:
            - method: DELETE
              name: v3-tags-delete-tag
              description: Censys Delete a Tag
              call: platform-tags-and-comments.v3-tags-delete-tag
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                tag_id: rest.tag_id
              outputParameters:
                - type: object
                  mapping: $.
            - method: GET
              name: v3-tags-get-tag
              description: Censys Get a Tag
              call: platform-tags-and-comments.v3-tags-get-tag
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                tag_id: rest.tag_id
              outputParameters:
                - type: object
                  mapping: $.
            - method: PUT
              name: v3-tags-update-tag
              description: Censys Update a Tag
              call: platform-tags-and-comments.v3-tags-update-tag
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                tag_id: rest.tag_id
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/tags/{tag_id}/assignments
          name: tags-tag-id-assignments
          description: REST surface for tags-tag-id-assignments.
          operations:
            - method: GET
              name: v3-tags-list-assignments
              description: Censys List Tag Assignments
              call: platform-tags-and-comments.v3-tags-list-assignments
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                tag_id: rest.tag_id
                page_size: rest.page_size
                page_token: rest.page_token
                order_by: rest.order_by
                asset_id: rest.asset_id
                created_before: rest.created_before
                created_after: rest.created_after
                created_by: rest.created_by
              outputParameters:
                - type: object
                  mapping: $.
            - method: POST
              name: v3-tags-create-assignment
              description: Censys Create a Tag Assignment
              call: platform-tags-and-comments.v3-tags-create-assignment
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                tag_id: rest.tag_id
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/tags/{tag_id}/assignments/{assignment_id}
          name: tags-tag-id-assignments-assignment-id
          description: REST surface for tags-tag-id-assignments-assignment-id.
          operations:
            - method: DELETE
              name: v3-tags-delete-assignment
              description: Censys Delete a Tag Assignment
              call: platform-tags-and-comments.v3-tags-delete-assignment
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                tag_id: rest.tag_id
                assignment_id: rest.assignment_id
              outputParameters:
                - type: object
                  mapping: $.
    - type: mcp
      namespace: platform-tags-and-comments-mcp
      port: 9090
      transport: http
      description: MCP adapter for Censys Platform — Tags and Comments. One tool per consumed operation, routed inline through this capability's consumes block.
      tools:
        - name: censys-list-comments
          description: Censys List Comments
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: platform-tags-and-comments.v3-comments-list-comments
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            page_size: tools.page_size
            page_token: tools.page_token
            order_by: tools.order_by
            asset_id: tools.asset_id
            created_by: tools.created_by
            created_before: tools.created_before
            created_after: tools.created_after
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-create-comment
          description: Censys Create a Comment
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: platform-tags-and-comments.v3-comments-create-comment
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            body: tools.body
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-delete-comment
          description: Censys Delete a Comment
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: platform-tags-and-comments.v3-comments-delete-comment
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            comment_id: tools.comment_id
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-update-comment
          description: Censys Update a Comment
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: platform-tags-and-comments.v3-comments-update-comment
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            comment_id: tools.

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/censys/refs/heads/main/capabilities/platform-tags-and-comments.yaml