# API reference

Available read-only resources for documentation, capability discovery and example data.

## Base URL and authentication

Requests use the same origin as this portal. No authentication is required for these public, fictional resources. Use the paths below on your current host. OpenAPI describes only implemented GET resources.

> Sandbox API: The saved sandbox has authenticated purchase, claim, decision and simulated-refund operations at https://sandbox.cleard.ai. Read its [API manifest](https://sandbox.cleard.ai/index.json). This OpenAPI file describes only the public documentation resources below; scoped agent credentials and a full versioned transaction contract remain unimplemented.

## Resource endpoints

| Method | Path | Response |
| --- | --- | --- |
| GET | `/portal/capabilities.json` | Capabilities and explicit unsupported operations. |
| GET | `/portal/examples/purchase.json` | Complete unsigned purchase fixture. |
| GET | `/portal/schemas/purchase.json` | JSON Schema for the purchase fixture. |
| GET | `/portal/openapi.json` | Machine-readable endpoint reference. |
| GET | `/portal/docs.md` | Complete documentation in Markdown. |
| GET | `/portal/llms.txt` | Compact documentation index for agents. |

## Try a read-only request

GET /portal/capabilities.json

The HTML page provides a read-only request runner for this resource.

## Example response

### GET /portal/capabilities.json

```json
{
  "version": "0.2.0",
  "mode": "simulation",
  "documentation": "/portal/docs.md",
  "openapi": "/portal/openapi.json",
  "schema": "/portal/schemas/purchase.json",
  "example": "/portal/examples/purchase.json",
  "authentication": "none for public fictional resources",
  "operations": [
    "read_documentation",
    "read_unsigned_example",
    "read_guided_walkthrough"
  ],
  "unsupported": [
    "real_payment",
    "real_merchant_identity",
    "scoped_agent_credentials",
    "BLISK_verification",
    "onchain_execution",
    "automatic_external_wallet_debit"
  ],
  "supported_networks": [],
  "supported_live_assets": [],
  "fictional_unit": "DEMO",
  "guarantee": false,
  "documentation_index": "/portal/llms.txt",
  "human_documentation": "/portal/",
  "markdown_pages": [
    "/portal/introduction.md",
    "/portal/quickstart.md",
    "/portal/sandbox.md",
    "/portal/concepts.md",
    "/portal/purchase.md",
    "/portal/claims.md",
    "/portal/funding.md",
    "/portal/api.md",
    "/portal/agents.md",
    "/portal/glossary.md"
  ],
  "sandbox": {
    "url": "https://sandbox.cleard.ai/",
    "workspace": "https://sandbox.cleard.ai/workspace.html",
    "manifest": "https://sandbox.cleard.ai/index.json",
    "walkthrough_data": "https://sandbox.cleard.ai/walkthrough.json",
    "authentication": "Walkthrough is public. Saved workspace requires sign-in.",
    "persistence": "Private records and simulated funds in the authenticated workspace only.",
    "signatures": "Ed25519 test signatures in saved records; not BLISK or legal merchant identity."
  }
}
```

## Errors and unsupported operations

Unknown documentation resource paths return HTTP 404. This host serves the listed read operations. The sandbox walkthrough sends no transaction requests; its signed-in workspace uses the authenticated API on the sandbox host. Do not infer SDK methods or API key provisioning from the examples.

Parse the `mode` and `unsupported` fields before choosing an action. A successful HTTP response means the file was fetched; it does not mean a purchase has been verified.