naftiko: 1.0.0-alpha2
info:
  label: Censys Platform — Collections
  description: 'Censys Platform — Collections. 8 operation(s). Lead operation: Censys List Collections. Self-contained Naftiko capability covering one Censys business surface.'
  tags:
    - Censys
    - Platform
    - Collections
  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-collections
      baseUri: https://api.platform.censys.io
      description: Censys Platform — Collections business capability. Self-contained, no shared references.
      authentication:
        type: bearer
        token: '{{env.CENSYS_PERSONAL_ACCESS_TOKEN}}'
      resources:
        - name: v3-collections
          path: /v3/collections
          operations:
            - name: v3-collections-crud-list
              method: GET
              description: Censys List Collections
              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_token
                  in: query
                  type: string
                  required: false
                  description: page token for the requested page of collection results
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: amount of results to return per page
                - name: collection_statuses
                  in: query
                  type:
                    - array
                    - "null"
                  required: false
                  description: statuses of collection for results to be filtered on.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: v3-collections-crud-create
              method: POST
              description: Censys Create a Collection
              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-collections-collection-uid
          path: /v3/collections/{collection_uid}
          operations:
            - name: v3-collections-crud-delete
              method: DELETE
              description: Censys Delete a Collection
              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: collection_uid
                  in: path
                  type: string
                  required: 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.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: v3-collections-crud-get
              method: GET
              description: Censys Get a Collection
              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: collection_uid
                  in: path
                  type: string
                  required: 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.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
            - name: v3-collections-crud-update
              method: PUT
              description: Censys Update a Collection
              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: collection_uid
                  in: path
                  type: string
                  required: true
                  description: The UID for the collection
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-collections-collection-uid-events
          path: /v3/collections/{collection_uid}/events
          operations:
            - name: v3-collections-list-events
              method: GET
              description: Censys Get a Collection's Events
              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: collection_uid
                  in: path
                  type: string
                  required: 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.
                - name: page_size
                  in: query
                  type: integer
                  required: false
                  description: Amount of results to return per page.
                - name: page_token
                  in: query
                  type: string
                  required: false
                  description: Page token for the requested page of collection results.
                - name: change_types
                  in: query
                  type:
                    - array
                    - "null"
                  required: false
                  description: Change types
                - name: asset_change_types
                  in: query
                  type:
                    - array
                    - "null"
                  required: false
                  description: Asset change types
                - name: status_change_types
                  in: query
                  type:
                    - array
                    - "null"
                  required: false
                  description: Status change types
                - name: start_time
                  in: query
                  type: string
                  required: false
                  description: Start time of the host timeline
                - name: end_time
                  in: query
                  type: string
                  required: false
                  description: End time of the host timeline
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-collections-collection-uid-search-aggregate
          path: /v3/collections/{collection_uid}/search/aggregate
          operations:
            - name: v3-collections-search-aggregate
              method: POST
              description: Censys Aggregate Results for a Search Query Within a Collection
              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: collection_uid
                  in: path
                  type: string
                  required: 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.
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
        - name: v3-collections-collection-uid-search-query
          path: /v3/collections/{collection_uid}/search/query
          operations:
            - name: v3-collections-search-query
              method: POST
              description: Censys Run a Search Query Within a Collection
              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: collection_uid
                  in: path
                  type: string
                  required: true
                  description: The UID for the collection
                - name: body
                  in: body
                  type: object
                  required: true
                  description: Request body.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
  exposes:
    - type: rest
      namespace: platform-collections-rest
      port: 8080
      description: REST adapter for Censys Platform — Collections. One Spectral-compliant resource per consumed operation, prefixed with /v1.
      resources:
        - path: /v1/collections
          name: collections
          description: REST surface for collections.
          operations:
            - method: GET
              name: v3-collections-crud-list
              description: Censys List Collections
              call: platform-collections.v3-collections-crud-list
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                page_token: rest.page_token
                page_size: rest.page_size
                collection_statuses: rest.collection_statuses
              outputParameters:
                - type: object
                  mapping: $.
            - method: POST
              name: v3-collections-crud-create
              description: Censys Create a Collection
              call: platform-collections.v3-collections-crud-create
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/collections/{collection_uid}
          name: collections-collection-uid
          description: REST surface for collections-collection-uid.
          operations:
            - method: DELETE
              name: v3-collections-crud-delete
              description: Censys Delete a Collection
              call: platform-collections.v3-collections-crud-delete
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                collection_uid: rest.collection_uid
              outputParameters:
                - type: object
                  mapping: $.
            - method: GET
              name: v3-collections-crud-get
              description: Censys Get a Collection
              call: platform-collections.v3-collections-crud-get
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                collection_uid: rest.collection_uid
              outputParameters:
                - type: object
                  mapping: $.
            - method: PUT
              name: v3-collections-crud-update
              description: Censys Update a Collection
              call: platform-collections.v3-collections-crud-update
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                collection_uid: rest.collection_uid
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/collections/{collection_uid}/events
          name: collections-collection-uid-events
          description: REST surface for collections-collection-uid-events.
          operations:
            - method: GET
              name: v3-collections-list-events
              description: Censys Get a Collection's Events
              call: platform-collections.v3-collections-list-events
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                collection_uid: rest.collection_uid
                page_size: rest.page_size
                page_token: rest.page_token
                change_types: rest.change_types
                asset_change_types: rest.asset_change_types
                status_change_types: rest.status_change_types
                start_time: rest.start_time
                end_time: rest.end_time
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/collections/{collection_uid}/search/aggregate
          name: collections-collection-uid-search-aggregate
          description: REST surface for collections-collection-uid-search-aggregate.
          operations:
            - method: POST
              name: v3-collections-search-aggregate
              description: Censys Aggregate Results for a Search Query Within a Collection
              call: platform-collections.v3-collections-search-aggregate
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                collection_uid: rest.collection_uid
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
        - path: /v1/collections/{collection_uid}/search/query
          name: collections-collection-uid-search-query
          description: REST surface for collections-collection-uid-search-query.
          operations:
            - method: POST
              name: v3-collections-search-query
              description: Censys Run a Search Query Within a Collection
              call: platform-collections.v3-collections-search-query
              with:
                organization_id: rest.organization_id
                X-Organization-ID: rest.X-Organization-ID
                collection_uid: rest.collection_uid
                body: rest.body
              outputParameters:
                - type: object
                  mapping: $.
    - type: mcp
      namespace: platform-collections-mcp
      port: 9090
      transport: http
      description: MCP adapter for Censys Platform — Collections. One tool per consumed operation, routed inline through this capability's consumes block.
      tools:
        - name: censys-list-collections
          description: Censys List Collections
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: platform-collections.v3-collections-crud-list
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            page_token: tools.page_token
            page_size: tools.page_size
            collection_statuses: tools.collection_statuses
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-create-collection
          description: Censys Create a Collection
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: platform-collections.v3-collections-crud-create
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            body: tools.body
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-delete-collection
          description: Censys Delete a Collection
          hints:
            readOnly: false
            destructive: true
            idempotent: true
          call: platform-collections.v3-collections-crud-delete
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            collection_uid: tools.collection_uid
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-get-collection
          description: Censys Get a Collection
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: platform-collections.v3-collections-crud-get
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            collection_uid: tools.collection_uid
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-update-collection
          description: Censys Update a Collection
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: platform-collections.v3-collections-crud-update
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            collection_uid: tools.collection_uid
            body: tools.body
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-get-collection-s-events
          description: Censys Get a Collection's Events
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: platform-collections.v3-collections-list-events
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            collection_uid: tools.collection_uid
            page_size: tools.page_size
            page_token: tools.page_token
            change_types: tools.change_types
            asset_change_types: tools.asset_change_types
            status_change_types: tools.status_change_types
            start_time: tools.start_time
            end_time: tools.end_time
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-aggregate-results-search-query
          description: Censys Aggregate Results for a Search Query Within a Collection
          hints:
            readOnly: true
            destructive: false
            idempotent: false
          call: platform-collections.v3-collections-search-aggregate
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            collection_uid: tools.collection_uid
            body: tools.body
          outputParameters:
            - type: object
              mapping: $.
        - name: censys-run-search-query-within
          description: Censys Run a Search Query Within a Collection
          hints:
            readOnly: true
            destructive: false
            idempotent: false
          call: platform-collections.v3-collections-search-query
          with:
            organization_id: tools.organization_id
            X-Organization-ID: tools.X-Organization-ID
            collection_uid: tools.collection_uid
            body: tools.body
          outputParameters:
            - type: object
              mapping: $.