> ## Documentation Index > Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Ingest cognition beats > The wrapped harness batch-ships Agent Cortex cognition beats here. Capture is off by default and is re-checked on the server: beats for an agent with capture off are counted in `dropped` and not stored. Beats are validated one by one, like decision telemetry. Raw content is encrypted at rest. Accepted batches return 202. ## OpenAPI ````yaml /api-reference/openapi.yaml post /allow/cognition openapi: 3.1.0 info: title: VisIQ Governance API version: 1.0.0 description: > The VisIQ platform API for governing agentic AI. One rule engine evaluates every governed agent event against your policies and returns a decision (permit, deny, approval-required, redact, mask, or escalate), records a cryptographically-verifiable audit trail, and governs agent-to-agent delegation. All requests are authenticated with a bearer API key presented as `Authorization: Bearer vq_prod_...`. Keys come in two audiences. Harness keys, minted under **Settings → Harness Keys**, are what your SDK or harness runs with; they reach only the operational surface (evaluate, rule bundles, telemetry, record ingestion). API keys for your own scripts and CI, minted under **Settings → API Keys**, reach the management API (rules, agents, settings, audit reads) through the permissions you grant each key. Dashboard sessions use your role's permissions. Decision vocabularies differ per facet. Action governance emits `permit | deny | approval_required | mask`. Retrieval governance emits `allow | deny | redact | escalate`. The unified `POST /evaluate` surface projects both into a single union vocabulary (`permit | deny | approval_required | redact | escalate | mask`). contact: name: VisIQ Labs url: https://docs.visiqlabs.com servers: - url: https://api.visiqlabs.com description: Production security: - bearerAuth: [] tags: - name: Evaluation description: Per-event governance decisions for action, retrieval, and delegation. - name: Action Rules description: Manage the rules that govern agent actions (writes/tool calls). - name: Retrieval Rules description: Manage the rules that govern retrieval and context exposure. - name: Unified Rules description: Operation-native rule management across both facets in one surface. - name: Rule Bundles description: Compiled, cacheable rule bundles the SDK runtime pulls per agent. - name: Agents description: Register and manage the agents whose events you govern. - name: Human-in-the-loop description: The approval queue for events that require a human decision. - name: Settings description: Per-account governance defaults. - name: Telemetry description: Decision and execution telemetry the SDK reports after evaluating locally. - name: Key lifecycle description: Operations an API key performs on itself. - name: Delegation description: Govern scoped agent-to-agent hand-offs with signed grant tokens. - name: Records description: Ingest, retrieve, finalize, and verify the tamper-evident audit trail. - name: Audit Log description: Versioned, paginated read APIs over recorded decisions and events. - name: Cognition description: >- Read captured Agent Cortex cognition sessions and beats (dedicated cognition:read scope). paths: /allow/cognition: post: tags: - Cognition summary: Ingest cognition beats description: > The wrapped harness batch-ships Agent Cortex cognition beats here. Capture is off by default and is re-checked on the server: beats for an agent with capture off are counted in `dropped` and not stored. Beats are validated one by one, like decision telemetry. Raw content is encrypted at rest. Accepted batches return 202. operationId: ingestCognition requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CognitionBatch' example: session: session_id: sess-42 root_agent_id: billing-copilot beats: - clientEventId: beat-1 agentId: billing-copilot sessionId: sess-42 seq: 0 ts: 1789560000000 kind: thought content: text: Checking the refund policy first. responses: '202': description: The batch was accepted. content: application/json: schema: $ref: '#/components/schemas/CognitionBatchResponse' example: received: 1 dropped: 0 rejected: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerAuth: [] components: schemas: CognitionBatch: type: object required: - beats properties: session: oneOf: - $ref: '#/components/schemas/CognitionSessionEnvelope' - type: 'null' beats: type: array minItems: 1 maxItems: 200 items: $ref: '#/components/schemas/CognitionBeatIngest' CognitionBatchResponse: type: object required: - received - dropped - rejected properties: received: type: integer dropped: type: integer description: Beats not stored because capture is off for the agent. rejected: type: array items: $ref: '#/components/schemas/RejectedItem' CognitionSessionEnvelope: type: object required: - session_id - root_agent_id properties: session_id: type: string minLength: 1 maxLength: 255 root_agent_id: type: string minLength: 1 maxLength: 255 agent_display_name: type: - string - 'null' maxLength: 255 framework: type: - string - 'null' maxLength: 64 sensorium: type: - object - 'null' additionalProperties: true CognitionBeatIngest: type: object required: - clientEventId - agentId - sessionId - seq - ts - kind additionalProperties: true description: > One cognition beat. Only the commonly used fields are listed; see the SDK for the tool, result, spawn, phase, cost and memory facets. properties: clientEventId: type: string minLength: 1 maxLength: 255 agentId: type: string minLength: 1 maxLength: 255 sessionId: type: string minLength: 1 maxLength: 255 threadId: type: - string - 'null' maxLength: 255 parentId: type: - string - 'null' maxLength: 255 seq: type: integer minimum: 0 ts: type: integer minimum: 0 description: Epoch milliseconds. durationMs: type: - integer - 'null' minimum: 0 kind: type: string enum: - thought - speech - action - observation - intervention - spawn - phase - handoff - lifecycle - error - memory visibility: type: - string - 'null' enum: - shown - hidden - null provenance: type: - string - 'null' enum: - signed - parsed - proxy - narration - null content: type: - object - 'null' additionalProperties: true properties: text: type: - string - 'null' model: type: - string - 'null' maxLength: 255 decisionId: type: - string - 'null' format: uuid RejectedItem: type: object required: - index - issues properties: index: type: integer minimum: 0 issues: type: array items: type: object additionalProperties: true Error: type: object required: - error - code description: > The standard error envelope. `code` is a stable, machine-readable snake_case identifier on every JSON error: the `error` value itself when that is already an identifier, otherwise a code derived from the HTTP status (see [REST conventions](/reference/rest-conventions)). `details` carries the validation issue list on 400s; authorization failures add fields such as `detail`, `requiredScopes`, or `requiredPermission`. properties: error: type: string code: type: string pattern: ^[a-z][a-z0-9_]*$ description: Stable machine-readable error code. Branch on this, not on `error`. detail: type: string details: type: array items: type: object additionalProperties: true additionalProperties: true responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid request body code: invalid_request details: - path: - agent_id message: Required Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized code: unauthenticated Forbidden: description: The key lacks the required permission or scope. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: insufficient_scope code: insufficient_scope detail: This API key is not authorized for the requested operation. ServiceUnavailable: description: > A dependency needed to serve the request is unavailable, for example the API-key rate limiter (`rate_limiter_unavailable`) or, for a request that sent an idempotency key, the idempotency store. The request was not processed; retry after the `Retry-After` delay. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 0 content: application/json: schema: $ref: '#/components/schemas/Error' example: error: rate_limiter_unavailable code: rate_limiter_unavailable detail: Rate limiter unavailable, please retry. securitySchemes: bearerAuth: type: http scheme: bearer description: > A VisIQ API key presented as `Authorization: Bearer vq_prod_...`. Mint harness keys under **Settings → Harness Keys** and API keys under **Settings → API Keys** in the dashboard. ````