> For the complete documentation index, see [llms.txt](https://rawctx.gitbook.io/rawctx-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rawctx.gitbook.io/rawctx-docs/documentation/answer-evidence/media-and-file-evidence.md).

# Media and file evidence

Keep original files, audio, and video in separately controlled evidence assets. An answer record should carry only the reference, commitment, and access-event bindings needed for review.

## Two evidence lanes

* **Reusable reference media** exists before the answer is created. Register it in the workspace vault, retrieve it with an application token, then bind the returned `source_ref` and `access_event_id` to the answer log.
* **Supplemental evidence** is attached to an existing answer later. It supports review or correction but must not be presented as the source used to produce the original answer.

## Controlled reference-media workflow

1. Confirm the workspace retention policy and who may retrieve the asset.
2. Request an upload or register an existing controlled asset.
3. Verify its checksum and metadata before attaching it to an answer record.
4. Retrieve it only through a purpose-bound request.
5. Bind the resulting access event to the answer when that retrieval informed the answer workflow.

Registration, listing, and manual download are tenant-manager actions. Runtime retrieval requires an application JWT with `answer_audit:evidence:read`; answer creation requires `answer_audit:create`. The token is bound to one `application_key`.

The SDK provides separate operations for answer-owned file assets and reusable media assets:

* `request_answer_evidence_asset_upload()`
* `register_answer_evidence_asset()`
* `request_answer_evidence_asset_download()`
* `register_media_evidence_asset()`
* `retrieve_media_evidence()`

## Register, retrieve, and bind

```python
import os
from pathlib import Path

import httpx
import rawctx

# Manager credential from `rawctx login`: register controlled media first.
media = rawctx.register_media_evidence_asset(
    filename="support-call.wav",
    mime_type="audio/wav",
    asset_type="audio",
    content=Path("support-call.wav").read_bytes(),
)

# Application JWT: retrieve at answer time.
registry = os.environ["RAWCTX_REGISTRY"].rstrip("/")
app_token = os.environ["RAWCTX_APPLICATION_TOKEN"]
with rawctx.RawctxClient(registry=registry, token=app_token) as runtime:
    retrieval = runtime.retrieve_media_evidence(
        media["evidence_asset_id"],
        purpose="answer_generation",
        external_trace_id="4f3c2b1a0f9e8d7c6b5a493827160504",
        external_message_id="msg_456",
    )

# Consume retrieval["stream_url"] before its expiry, then create the record.
# This request is text-only so a keyed workspace can derive tenant HMACs.
response = httpx.post(
    f"{registry}/api/answer-audit-logs",
    headers={"Authorization": f"Bearer {app_token}"},
    json={
        "application_key": "support_assistant",
        "environment": "production",
        "idempotency_key": "support:req_123:msg_456",
        "external_trace_id": "4f3c2b1a0f9e8d7c6b5a493827160504",
        "external_message_id": "msg_456",
        "question": {"text": "What did the customer request?"},
        "answer": {"text": "The customer requested a billing correction."},
        "source_refs": [retrieval["source_ref"]],
        "evidence_access_event_ids": [retrieval["access_event_id"]],
    },
    timeout=20,
)
response.raise_for_status()
log = response.json()
```

The application key embedded in the token must equal the answer log's `application_key`. The retrieved asset must appear in `source_refs`; its hash and modality must match registration. The returned stream URL is short-lived, purpose-bound, and is not stored in the ledger.

For manual auditor review, a tenant manager authorizes a separate download:

```python
download = rawctx.request_media_evidence_asset_download(
    media["evidence_asset_id"],
    purpose="audit-case-2026-184",
)
```

## Supplemental evidence

For evidence created after the answer, use this log-scoped upload flow:

1. `request_answer_evidence_asset_upload()`
2. upload bytes to the returned object URL
3. `register_answer_evidence_asset()`
4. `list_answer_evidence_assets()` for sanitized metadata
5. `request_answer_evidence_asset_download()` for manager review

The Hub UI accepts text, audio, and video files up to 5 MB. API deployment limits may differ; check the returned upload policy rather than assuming the browser limit applies everywhere.

## Common failures

* 403: runtime retrieval used a user token, lacks `answer_audit:evidence:read`, or the token is bound to another application.
* 422: the reference hash/modality does not match, the access event is absent from `source_refs`, or the event belongs to another `application_key`.
* Download unavailable: the upload is pending or the asset uses an external URI that rawctx does not presign.
* HTTP 410: the answer log or selected evidence was redacted.

## Do not embed originals

Do not place raw media bytes, recordings, customer files, private storage keys, or long-lived download URLs in `source_refs`, answer metadata, OTel attributes, or public proof material. Do not retrieve an original merely to compute a reference when an existing commitment is sufficient.

An asset hash and access event establish a submitted evidence chain. They do not prove that the media is true or that the model actually used its contents.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://rawctx.gitbook.io/rawctx-docs/documentation/answer-evidence/media-and-file-evidence.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.