# ReasAtlas API quickstart

Open API access from Home or the top navigation. Sign in with ReasLab, then create a named personal token. Public knowledge search does not require a token.

## Token lifecycle

- Choose 1, 7, 30, or 90 days, or a specific date and time. The page uses your browser timezone and sends UTC to the server.
- Copy the secret when it appears: it is shown once. Store it in your client environment or secret manager. The server stores only its hash.
- Change expiration on any active token. The new date must be in the future and within 90 days of the change. Expired or deleted tokens cannot be reactivated; create a replacement.
- Delete token revokes its access immediately. Existing proposals and audit records remain. Enable Show deleted tokens to see revoked records.
- Each account may have up to 20 active tokens. Lost secrets cannot be recovered.
- Token management requires your signed-in browser session and CSRF protection. A bearer token cannot create other tokens or manage their lifetime.

## Permissions

| Purpose | Read | Write |
| --- | --- | --- |
| Contributions | contributions:read: inspect your proposals and artifacts | contributions:write: create/update drafts, submit proposals, upload evidence, withdraw |
| Reviews (administrators) | reviews:read: inspect the review queue and attached evidence | reviews:decide: accept, request changes, or reject |

Contributor and reviewer permissions require separate tokens. Reviewer access checks the current account role on every request. Neither token can publish knowledge; publication is a separate administrator action.

## Connect a client

Use the origin of your deployment. This local review instance uses http://localhost:3000. For a public deployment, use its configured HTTPS origin. Set ATLAS_API_TOKEN securely in your client environment; do not put its value in URLs, shared files, or logs.

```sh
export ATLAS_BASE_URL="http://localhost:3000"
curl --fail-with-body "$ATLAS_BASE_URL/api/v1/capabilities"
curl --fail-with-body "$ATLAS_BASE_URL/api/v1/knowledge/current"
curl --fail-with-body --get "$ATLAS_BASE_URL/api/v1/search"   --data-urlencode 'q=convex function' --data-urlencode 'mode=keyword'
```

Search also accepts mode=semantic when the deployment has semantic search available. Knowledge graph and public search do not need personal tokens.

## Prepare and submit a contribution

1. Read the current release and inspect the destination topic through the Atlas or GET /api/v1/knowledge/context (release_id, domain_id, topic_id).
2. Prepare proposal.json using the schema in /api/docs. The template below creates a draft; replace every placeholder and verify the mathematical content, identity, placement, authorship, and sources.
3. POST the draft with a unique Idempotency-Key. Retrying the same body and key returns the same proposal. Reusing the key with a different body returns 409.
4. Inspect the returned proposal ID and version. Update your draft with PUT /api/v1/agent/proposals/{id}, including its current version. For a normal submission, set submit=true and include assessment with content, identity, and placement each set to ready only after checking them. Unresolved candidates use the separate intake_statement workflow documented in the API schema.
5. Review and publication follow submission. Acceptance alone does not publish the statement. Track your proposal with GET /api/v1/agent/proposals/{id}.

```json
{
  "base_release": "REPLACE_WITH_CURRENT_RELEASE_ID",
  "submit": false,
  "payload": {
    "operation": "create_statement",
    "domain_id": "REPLACE_WITH_DOMAIN_ID",
    "topic_id": "REPLACE_WITH_TOPIC_ID",
    "reason": "Explain the proposed addition",
    "authors": ["Your name"],
    "supporting_evidence": [{"citation": "Precise source and locator"}],
    "content": {
      "title": "Statement title",
      "content_kind": "theorem",
      "statement_latex": "Write the full statement, including assumptions."
    }
  }
}
```

```sh
# ATLAS_API_TOKEN must already be set securely in this environment.
curl --fail-with-body "$ATLAS_BASE_URL/api/v1/agent/proposals"   -H "Authorization: Bearer $ATLAS_API_TOKEN"   -H 'Content-Type: application/json'   -H 'Idempotency-Key: replace-with-a-unique-operation-id'   --data-binary @proposal.json
```

Use POST /api/v1/agent/proposals/preview to inspect the proposed changes before submission. Formal evidence uploads use POST /api/v1/agent/artifacts with SHA-256 and base64 content; upload integrity does not certify mathematical correctness.

## Token management API (browser session only)

All mutations require the session cookie and X-CSRF-Token obtained from GET /api/auth/csrf. Prefer the API access page for these operations. Never distribute browser cookies to automation clients.

| Method and path | Body / behavior |
| --- | --- |
| GET /api/v1/client-tokens | Lists your metadata, including expired and revoked tokens; never returns secrets |
| POST /api/v1/client-tokens | name, scopes, and expires_in_days (1–90, default 30), or timezone-aware expires_at; absolute time takes precedence when both are supplied; returns the secret once |
| PATCH /api/v1/client-tokens/{id} | expires_at: future ISO 8601 timestamp with timezone, within 90 days; active tokens only |
| DELETE /api/v1/client-tokens/{id} | Revokes your token immediately; retains the record for audit |

## Errors and troubleshooting

| Status | Meaning / next step |
| --- | --- |
| 401 | Sign in again for management; for agent routes, check the token, expiration, revocation, and account status |
| 403 | Check permission scope, current reviewer role, or browser CSRF protection |
| 404 | Resource does not exist or is not available to this account |
| 409 | Refresh release/version, use the original idempotent request, or create a replacement for an expired/deleted token |
| 422 | Check schema, required evidence, and timezone-aware expiration within 90 days |
| 429 | Check the active-token or artifact quota; remove unused access before retrying |

## Reference

- API access: /api-access.html
- API guide: /api-guide.html
- Interactive reference: /api/docs
- OpenAPI schema: /api/openapi.json
- Capability discovery: /api/v1/capabilities

Request limits: 1 MiB per request; 384 KiB per evidence artifact; 512 owned artifacts per contributor. Public availability and OAuth callback URLs depend on deployment configuration. This guide does not imply that a public hostname has been deployed.