> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyberis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Intelligence flow

> Inspect account-scoped feed contributions by transport, agent, and self-reported skill.

Requires `read:intel`. The account comes from your authenticated credentials.
`window_days` defaults to 30 and accepts 1–90. Optional `feed_id` restricts both
contributions and unique recorded answers to that feed. `since` is inclusive;
`until` is exclusive.

## Counts and coverage

Each `paths` entry describes a feed, transport, agent identity, and optional skill.
`contributions` counts one response once per contributing feed. A response supported
by two feeds contributes twice across the full flow. `unique_answers` counts recorded
response IDs; it is not a count of investigations, agent-written reports, or confirmed
detections. Responses without recorded feeds appear in `answers_without_feeds`.
These records cover captured attribution, not necessarily all account activity.

`transport` is `mcp`, `rest`, or `unknown`. Historical missing metadata and unverified
transport both appear as `unknown`; the dashboard labels this combined category
**API/MCP**, without claiming which transport was used. Skill IDs and versions are
self-reported. Missing skill metadata stays null.

## Agent identity and API-key fallback

Explicit agent IDs, connection identities, and caller-reported agent names take
precedence. When a record only identifies a principal or has no agent identity,
the flow can recover the API key from the matching account-scoped usage request:

* `agent_key_type: "api_key"` means `agent_key` is the immutable API key ID.
* `api_key_name` is the key's current display name, or null when unavailable.
* `api_key_revoked` is true when the recovered key ID has no matching key row,
  false when the row exists, and null for identities that are not API-key fallbacks.
* Renaming a key changes the name displayed for historical activity. This field
  is not a snapshot of its name at request time.
* Duplicate names remain separate because grouping uses key IDs. A shared key
  identifies a credential, not necessarily one agent.
* Missing usage records or null key IDs cannot be used to recover a key. Raw
  principal IDs can remain in the API response; the dashboard displays
  **Agent not identified** instead.

For an existing key with no label, display its key ID. When `api_key_revoked` is
true, display **Revoked API key** and reveal the key ID on hover. Missing key names
alone do not establish revocation. Keep IDs accessible to disambiguate duplicate
labels. Both key metadata fields are additive; tolerate them being absent on
earlier API versions without treating an absent revocation flag as proof of revocation.

## Partial results

At most 5,000 paths are returned. If `complete` is false, use
`displayed_contributions` for rendered path totals and report `omitted_contributions`.
`total_contributions` covers the complete selection. A feed filter recomputes the
selection rather than merely hiding other paths.

`unknown_transport_contributions` and `unreported_skill_contributions` describe
metadata coverage. Database failures return unavailable responses rather than
successful zero counts.


## OpenAPI

````yaml GET /v2/attribution/flow
openapi: 3.1.0
info:
  description: Deterministic, evidence-backed threat assessment API for machine consumers.
  title: Threat Investigator API v2
  version: 0.1.0
servers: []
security: []
paths:
  /v2/attribution/flow:
    get:
      tags:
        - Attribution
      summary: >-
        Account-scoped feed contribution paths with transport and self-reported
        skills
      operationId: attribution_flow_v2_attribution_flow_get
      parameters:
        - in: query
          name: window_days
          required: false
          schema:
            default: 30
            maximum: 90
            minimum: 1
            title: Window Days
            type: integer
        - in: query
          name: feed_id
          required: false
          schema:
            anyOf:
              - maxLength: 64
                minLength: 1
                type: string
              - type: 'null'
            title: Feed Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributionFlowResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AttributionFlowResponse:
      properties:
        answers_without_feeds:
          title: Answers Without Feeds
          type: integer
        complete:
          title: Complete
          type: boolean
        displayed_contributions:
          title: Displayed Contributions
          type: integer
        feed_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Feed Id
        omitted_contributions:
          title: Omitted Contributions
          type: integer
        paths:
          items:
            $ref: '#/components/schemas/AttributionFlowPath'
          title: Paths
          type: array
        since:
          title: Since
          type: string
        status:
          enum:
            - ok
            - no_results
          title: Status
          type: string
        total_contributions:
          title: Total Contributions
          type: integer
        unique_answers:
          title: Unique Answers
          type: integer
        unit:
          const: feed_contributions
          title: Unit
          type: string
        unknown_transport_contributions:
          title: Unknown Transport Contributions
          type: integer
        unreported_skill_contributions:
          title: Unreported Skill Contributions
          type: integer
        until:
          title: Until
          type: string
      required:
        - status
        - unit
        - since
        - until
        - feed_id
        - unique_answers
        - answers_without_feeds
        - total_contributions
        - displayed_contributions
        - omitted_contributions
        - complete
        - unknown_transport_contributions
        - unreported_skill_contributions
        - paths
      title: AttributionFlowResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    AttributionFlowPath:
      properties:
        api_key_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Api Key Name
        api_key_revoked:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Api Key Revoked
        feed_id:
          title: Feed Id
          type: string
        transport:
          type: string
          enum:
            - rest
            - mcp
            - unknown
          title: Transport
        agent_key:
          title: Agent Key
          type: string
        agent_key_type:
          type: string
          title: Agent Key Type
        skill_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Skill Id
        skill_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Skill Version
        contributions:
          type: integer
          title: Contributions
      type: object
      required:
        - feed_id
        - transport
        - agent_key
        - agent_key_type
        - skill_id
        - skill_version
        - contributions
      title: AttributionFlowPath
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: ApiKey <key_id>:<secret>
      in: header
      name: Authorization
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.