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

# Import citation evidence

> Retain bounded customer-measured citation answer envelopes with verified content hashes.

`ingest_citation_evidence`

Retain bounded customer-measured citation answer envelopes with verified content hashes. Import is idempotent and costs no answer checks. Screenshots remain local; recorded engine provenance is a customer claim.

<Note>Available in the deployed MCP and HTTP bundle. Confirm access and inputs with your connected catalog. Workspace scopes and enabled providers still apply.</Note>

| Access          | Behavior              |
| --------------- | --------------------- |
| `watches:write` | Writes or admits work |

This operation changes saved state. Review its inputs and retry behavior before calling.

## Example request

Connect through [MCP](/guides/connect-mcp), [CLI](/guides/connect-cli), or [HTTP](/guides/connect-http). Replace example identifiers with records from your workspace.

<CodeGroup>
  ```json MCP theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ingest_citation_evidence",
      "arguments": {
        "projectId": "project_example",
        "records": [
          {
            "envelopeJson": "{\"schema_version\":1,\"epoch_id\":\"epoch_example\",\"cell_id\":\"mock:builtin|prompt_example|d:example.com\",\"run_index\":0,\"prompt\":\"Which resources explain this topic?\",\"engine_identity\":\"mock:builtin\",\"provider_model_version\":\"fixture-v1\",\"answer\":\"Example answer.\",\"citations\":[],\"fan_out\":[],\"usage\":{\"input_tokens\":0,\"output_tokens\":0},\"cost_estimate_usd\":0,\"at\":\"2026-09-20T00:00:00.000Z\"}",
            "sha256": "771a4a6afc3bb5b9637c8698caf894dfc9a081dd5bc13e41d75374ab13e9e39c",
            "cliVersion": "0.6.2"
          }
        ]
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call ingest_citation_evidence --args '{"projectId":"project_example","records":[{"envelopeJson":"{\"schema_version\":1,\"epoch_id\":\"epoch_example\",\"cell_id\":\"mock:builtin|prompt_example|d:example.com\",\"run_index\":0,\"prompt\":\"Which resources explain this topic?\",\"engine_identity\":\"mock:builtin\",\"provider_model_version\":\"fixture-v1\",\"answer\":\"Example answer.\",\"citations\":[],\"fan_out\":[],\"usage\":{\"input_tokens\":0,\"output_tokens\":0},\"cost_estimate_usd\":0,\"at\":\"2026-09-20T00:00:00.000Z\"}","sha256":"771a4a6afc3bb5b9637c8698caf894dfc9a081dd5bc13e41d75374ab13e9e39c","cliVersion":"0.6.2"}]}'
  ```

  ```bash HTTP theme={null}
  curl "$AGENTLINKOPS_API_URL/v1/commands/ingest_citation_evidence" \
    -H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{"projectId":"project_example","records":[{"envelopeJson":"{\"schema_version\":1,\"epoch_id\":\"epoch_example\",\"cell_id\":\"mock:builtin|prompt_example|d:example.com\",\"run_index\":0,\"prompt\":\"Which resources explain this topic?\",\"engine_identity\":\"mock:builtin\",\"provider_model_version\":\"fixture-v1\",\"answer\":\"Example answer.\",\"citations\":[],\"fan_out\":[],\"usage\":{\"input_tokens\":0,\"output_tokens\":0},\"cost_estimate_usd\":0,\"at\":\"2026-09-20T00:00:00.000Z\"}","sha256":"771a4a6afc3bb5b9637c8698caf894dfc9a081dd5bc13e41d75374ab13e9e39c","cliVersion":"0.6.2"}]}'
  ```
</CodeGroup>

## Returned result

Illustrative data validated against the documented response schema. IDs and dates are examples, not a live account capture. MCP returns this data in `structuredContent` and in a text content block; generic HTTP and CLI return the JSON result directly.

```json theme={null}
{
  "imported": 1,
  "deduplicated": 0,
  "total": 1,
  "charged_units": 0,
  "observations": [
    {
      "id": "cio_example",
      "created": true,
      "evidence_status": "retained",
      "sha256": "771a4a6afc3bb5b9637c8698caf894dfc9a081dd5bc13e41d75374ab13e9e39c",
      "expires_at": "2026-10-20T00:00:00.000Z"
    }
  ]
}
```

## Input fields

Omit optional fields when you do not want to supply them. Null is accepted only where listed. Unknown input properties are rejected.

| Field                            | Type          | Presence | Meaning and constraints                                                                             |
| -------------------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `projectId`                      | string        | Required | Identifier of the project returned by its create or list operation. minLength: 1; maxLength: 200    |
| `records`                        | array         | Required | The records value; allowed values and bounds are specified in this schema. minItems: 1; maxItems: 5 |
| `records[].envelopeJson`         | string        | Required | minLength: 2; maxLength: 65536                                                                      |
| `records[].sha256`               | string        | Required | pattern: "^\[a-f0-9]\{64}\$"                                                                        |
| `records[].cliVersion`           | string        | Required | minLength: 1; maxLength: 100                                                                        |
| `records[].localEvidenceSha256`  | string        | Optional | pattern: "^\[a-f0-9]\{64}\$"                                                                        |
| `records[].screenshot`           | object        | Optional | additional fields rejected                                                                          |
| `records[].screenshot.reference` | string        | Required | minLength: 1; maxLength: 120; pattern: "^\[A-Za-z0-9\_.-]+\$"                                       |
| `records[].screenshot.sha256`    | string / null | Optional |                                                                                                     |

### Validation and omitted values

Imports up to five envelopes per request; each UTF-8 envelope is at most64KiB and the serialized arguments at most192KiB. Project storage is bounded. Importing already-measured evidence charges no answer checks.

Exact bytes and hashes are retained for30days. Identical replays do not extend expiry; changed evidence for an existing observation conflicts. Screenshot metadata can be recorded, but image bytes remain local.

Engine and observation timestamps are customer-supplied provenance. Content hashes prove byte integrity, not provider authenticity or an independently witnessed time.

## Output fields

Fields inside optional or nullable parents apply only when that parent exists. [Common schema conventions](/reference/schemas) explain evidence states, empty lists and extensions.

| Field                            | Type    | Presence | Meaning and constraints                                                              |
| -------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------ |
| `imported`                       | integer | Required | minimum: 0; maximum: 9007199254740991                                                |
| `deduplicated`                   | integer | Required | minimum: 0; maximum: 9007199254740991                                                |
| `total`                          | integer | Required | maximum: 9007199254740991; exclusiveMinimum: 0                                       |
| `charged_units`                  | number  | Required | must equal 0                                                                         |
| `observations`                   | array   | Required |                                                                                      |
| `observations[].id`              | string  | Required | Resource identifier returned by the operation. minLength: 1; maxLength: 200          |
| `observations[].created`         | boolean | Required | True when this request created the record; false when an existing record was reused. |
| `observations[].evidence_status` | string  | Required | values: "retained", "expired"                                                        |
| `observations[].sha256`          | string  | Required | pattern: "^\[a-f0-9]\{64}\$"                                                         |
| `observations[].expires_at`      | string  | Required |                                                                                      |

[Download input schema](/schemas/ingest_citation_evidence.input.json) · [Download output schema](/schemas/ingest_citation_evidence.output.json)

## Errors and retries

The command is annotated idempotent. Reuse an accepted idempotency key when the input provides one; changing the payload under a reused key can conflict.

See [error recovery](/reference/errors) for status, scope, cooldown, cursor and retry handling. Unknown observations are result data and do not establish loss.

## HTTP resource routes

This operation has no separate resource alias. Use its generic command route in a matching environment.

## Continue

[list\_citation\_observations](/reference/commands/list_citation_observations) · [get\_citation\_evidence](/reference/commands/get_citation_evidence)

Follow the [related workflow](/guides/monitor-changes), inspect [capability status](/capability-status), or return to the [command index](/reference/index).