> 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/get-started.md).

# Get started

This path records one answer under the workspace's commitment and retention policy, then verifies its proof separately.

## Prerequisites

* Python 3.10 or newer
* A rawctx workspace for authenticated write operations
* A stable application key and idempotency key from your application

## 1. Install and sign in

```bash
python -m pip install rawctx
rawctx login
```

`rawctx login` opens a browser when possible and stores the resulting API token in the local rawctx configuration. This login flow is for developers and operators working interactively. For a production server, create a dedicated token from the workspace Hub under **Settings > Access & team > API tokens**, store it in the deployment platform's secret manager, and inject `RAWCTX_REGISTRY` and `RAWCTX_TOKEN`. Do not run `rawctx login` in the server or container, and do not commit tokens to source control.

## 2. Choose the commitment path

Many production workspaces require platform-managed keyed hashing. In that mode, submit `question_text` and `answer_text` so the authenticated API can derive tenant-scoped HMAC commitments. Text submission does not imply text storage: the server persists text only when the workspace's separate storage settings enable it.

The request below is deliberately text-only. Set the workspace API host and a token authorized to create answer evidence in the environment, then call the workspace endpoint directly:

```python
import os
import httpx

registry = os.environ["RAWCTX_REGISTRY"].rstrip("/")
token = os.environ["RAWCTX_TOKEN"]

response = httpx.post(
    f"{registry}/api/answer-audit-logs",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "application_key": "support_assistant",
        "environment": "production",
        "idempotency_key": "support_assistant:req_123:msg_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",
            }
        ],
    },
    timeout=20,
)
response.raise_for_status()
log = response.json()
print(log["id"], log["question_hash"], log["answer_hash"])
```

Current UI-issued API tokens are scoped to a workspace and user, not to one `application_key`. Create a separate token for each production deployment, and rotate or revoke it from the workspace UI.

The current `rawctx.log_answer()` and `RawctxClient.create_answer_log()` text convenience path also supplies a caller-generated SHA-256 hash. Do not use that path when the workspace requires an active tenant HMAC; use the text-only API request above.

If policy prohibits sending raw text, stop and confirm the workspace configuration. A workspace that explicitly accepts caller-generated hashes can use the following hash-only form, but this request is rejected when platform-managed keyed hashing is required:

```python
import rawctx

log = rawctx.log_answer(
    application_key="support_assistant",
    environment="production",
    idempotency_key="support_assistant:req_123:msg_456",
    question_hash="sha256:235d0f0faf774748394fbb5dec9c41c51ac23b1cc6c344bc06864e7d34442516",
    answer_hash="sha256:f564d7fd469050a37898846611c9a6031be9bad19907812ec0d605b3e614b6f8",
    source_refs=[
        {
            "source_name": "support-policy@2026-06-12",
            "source_hash": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
        }
    ],
)

print(log["id"])
```

The API returns the tenant-scoped answer record with its identifiers, stored or derived commitments, references, lifecycle status, and retention fields. Answer creation does not return a proof-verification result.

## 3. Fetch and verify the proof separately

```bash
rawctx trust proof answer ANSWER_LOG_ID --output proof.json
rawctx trust verify proof.json --json
```

Use `--online` only when supported public anchor and witness checks are needed.

## 4. Review the boundary

The answer record shows what you submitted. The separate verification result shows which proof bindings passed, failed, were skipped, or did not apply. Neither establishes answer accuracy, delivery, or actual source use.

For personal data, secrets, or predictable sensitive text, a public SHA-256 hash can still be guessable. A tenant HMAC commitment avoids that dictionary oracle, but it does not make unrestricted raw-text submission or storage safe.

## 5. Continue with your use case

* Attach an existing trace: OpenTelemetry trace references
* Query, export, or redact: Log lifecycle, search, and export
* Register controlled media: Media and file evidence
* Detect missing logs: Independent reconciliation
* Verify a receipt: Trust and verification
* Automate with Python: Python SDK

## Common first-run failures

* `AuthRequiredError`: sign in or set `RAWCTX_TOKEN` in the current environment.
* `RegistryError`: confirm the registry URL and network path.
* `UsageError`: check required identifiers. In the convenience `log_answer()` call, do not combine positional question/answer arguments with their keyword text or hash counterparts.
* Duplicate idempotency key: reuse the original record or issue a genuinely new key.
* HTTP 403: confirm whether the credential is a user token or application token, then check the application scope and bound `application_key`.
* HTTP 422 on a keyed workspace: send text without a caller-generated SHA-256 hash so the service can derive the active tenant HMAC.


---

# 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/get-started.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.