> 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/log-lifecycle-search-and-export.md).

# Log lifecycle, search, and export

The original commitments and identifiers on an answer log are immutable. Create the log once, find it by stable identifiers, and append lifecycle events instead of rewriting history.

## Create idempotently

Use an idempotency key derived from the application request or message, not a random value generated on every retry.

```python
import rawctx

with rawctx.RawctxClient() as client:
    log = client.create_answer_log(
        application_key="support_assistant",
        environment="production",
        idempotency_key="support:req_123:message_456",
        question_text="What is the refund policy?",
        answer_text="Customers can request a refund within 30 days.",
        source_refs=[
            {
                "source_name": "support-policy@2026-06-12",
                "source_hash": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
            }
        ],
    )
```

The workspace derives its active SHA-256 or HMAC commitment from the submitted text. Text submission and text storage are separate policies. If policy prohibits submitting raw text, use the hash-only form only when the workspace explicitly permits caller-generated hashes.

Repeating the same idempotency key and equivalent payload returns the existing record. Reusing the key with a different payload is a conflict and should stop the retry loop.

## Search with review keys

```python
import rawctx

with rawctx.RawctxClient() as client:
    page = client.list_answer_logs(
        application_key="support_assistant",
        environment="production",
        status="recorded",
        external_trace_id="4f3c2b1a0f9e8d7c6b5a493827160504",
        created_after="2026-07-01T00:00:00Z",
        created_before="2026-08-01T00:00:00Z",
        page=1,
        size=100,
    )
```

Other filters include `mode`, `actor_id_hash`, `session_id_hash`, and stable external identifiers. Use a short UTC time window and an exact application key for repeatable audit queries.

## Append lifecycle events

| Event                 | Resulting status | Use                                                |
| --------------------- | ---------------- | -------------------------------------------------- |
| `correction_appended` | `corrected`      | Preserve a corrected commitment and reason         |
| `voided`              | `voided`         | Mark the record unusable without deleting it       |
| `redacted`            | `redacted`       | Remove stored text and tombstone selected evidence |
| `retention_extended`  | unchanged        | Record an approved retention action in the history |

```python
with rawctx.RawctxClient() as client:
    client.append_answer_log_event(
        "ANSWER_LOG_ID",
        event_type="redacted",
        reason="Data-subject deletion request DSAR-2026-184",
        payload={
            "reason_code": "data_subject_request",
            "redact_source_ref_ids": ["source-ref-7"],
        },
    )
```

Redaction clears stored question and answer text. Redacted evidence segments are returned as tombstones, and original asset retrieval can return HTTP 410. Commitments and the event history remain so reviewers can see that redaction occurred. `retention_extended` records an event; do not assume it mutates the workspace policy or `retention_until` without a separate approved operation.

## Export a bounded review set

Export requires tenant-manager privileges. A UI-issued API token can export only when it belongs to a tenant manager. Keep a manager-issued review/export token separate from the production runtime logging token.

```python
from pathlib import Path
import rawctx

with rawctx.RawctxClient() as client:
    jsonl = client.export_answer_logs(
        format="jsonl",
        application_key="support_assistant",
        environment="production",
        created_after="2026-07-01T00:00:00Z",
        created_before="2026-08-01T00:00:00Z",
    )

Path("answer-audit-2026-07.jsonl").write_text(jsonl, encoding="utf-8")
```

`format` is `jsonl` or `csv`. Depending on workspace policy, exports can contain stored text, metadata, identifiers, commitments, and references. Treat the file as sensitive. Encrypt it in transit and at rest, and apply a deletion schedule independent of the source workspace. The current endpoint does not paginate exports. It returns only the first page, capped at 200 matching records per request. Split larger audits into non-overlapping bounded time windows, verify each count, and record the windows used.

## Retry decisions

* Retry timeouts, connection failures, and selected 5xx responses with bounded exponential backoff while preserving the idempotency key.
* Reauthenticate on 401; do not blindly retry.
* On 403, correct the workspace, the issuing user's role, the credential type, or the endpoint authorization. Current UI-issued API tokens do not have per-operation scopes.
* Resolve idempotency or version conflicts on 409.
* Fix the request contract or workspace commitment mode on 422.


---

# 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/log-lifecycle-search-and-export.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.