# API & MCP Reference (https://meta-tracing-tinycore.pages.dev)

## Authentication
Send API keys ONLY via request headers:
- `Authorization: Bearer <MTW_API_KEY>`
- or `X-API-Key: <MTW_API_KEY>`

Never place keys/tokens in URL query strings (rejected with HTTP 400). Invalid, revoked, or expired credentials are rejected immediately with HTTP 401. All issued keys satisfy `expires_at <= issued_at + 604800` (7 days).

## Structured REST Endpoints (/api/v1)

- `GET /.well-known/agent-interface.json` — Machine-readable discovery descriptor (API, MCP, rate limits, key TTLs, terms, skills, and release SHA-256 checksums).
- `GET /api/v1/overview` — Public overview, caller status, and remaining ops in current 60s window.
- `GET /api/v1/agent/me` — Authenticated caller principal, granted scopes, and expiry timestamp.
- `GET /api/v1/assets` — List downloadable TinyCore kernel/ISO/GCE images, boot launchers, native host binary, and Wasm modules with SHA-256 checksums.
- `GET /api/v1/platforms` — Supported AI coding platforms, verified install paths, POSIX/PowerShell commands, and usage prompts.
- `GET /api/v1/skills/manifest` — Skill bundle version, archive SHA-256, and per-file SHA-256 manifest.
- `GET /api/v1/terms` & `POST /api/v1/terms/accept` — Read terms and record explicit acceptance of `2026-11-12.v1` with user delegation.
- `POST /api/v1/enrollment/apply` — Submit agent/user application (`userId`, `agentId`, `scopes`, `deliveryChannel`, `deliveryDestination`, `termsVersion`, `acceptTerms`, `delegationStatement`). Returns `202 pending` plus a one-time `statusToken` on first-time pair.
- `GET /api/v1/enrollment/status?applicationId=...` — Requires header `X-Status-Token: <statusToken>` or authenticated caller with `enrollment:read` matching `userId`. Never returns raw API keys.
- `GET /api/v1/sqlite/notes` — Authenticated read (requires scope `sqlite:demo:read`).
- `POST /api/v1/sqlite/notes` — Authenticated write (requires scope `sqlite:demo:write`, payload `{ "title", "body" }`).
- `GET /api/v1/cadastre/overview` — Public Burbank Cadastral & Corporate Datalog Ontology counts, predicate schema, Section 4/5/6 audits, 12 preset queries, and live default D1 results.
- `GET /api/v1/cadastre/presets` — List all 12 ontology presets and predicate schema.
- `POST /api/v1/cadastre/query` — Execute a preset (`{ "presetId" }`), read-only SQL/CTE (`{ "sql" }`), or stratified Datalog rule (`{ "head", "body" }`) server-side against D1.
- `POST /api/v1/keys/rotate` — Authenticated owner/admin key rotation (`{ "keyId", "ttlSec?" }`). Preserves caller rate-limit budget.
- `POST /api/v1/keys/revoke` — Revoke an active key immediately (`{ "keyId" }`).
- `POST /api/v1/contact` — Submit public support message (supports `Idempotency-Key` retry deduplication; committed synchronously to D1 + notification outbox before queuing).

## MCP JSON-RPC 2.0 Endpoint (`POST /mcp`)
Supports single requests and JSON-RPC batch arrays (max 30; charged per item atomically before execution).
Tools exposed by `tools/list`:
- `site_overview`, `list_release_assets`, `list_platforms`
- `terms_accept`, `enrollment_apply`, `enrollment_status`
- `cadastre_overview`, `cadastre_query`
- `scoped_notes_list`, `scoped_notes_create`
- `key_rotate`, `key_revoke`, `contact_submit`
- Admin-only: `admin_list_pending`, `admin_review_enrollment`, `admin_review_contact`, `admin_retry_contact_outbox`

## Interaction & Privacy Terms (2026-11-12.v1)
Meta-Tracing Wasm + TinyCore SQLite Appliance Agentic Interaction, Privacy & Enrollment Terms (Version 2026-11-12.v1)

1. Ownership and Retained Non-Exclusive Rights: Submitters and principals retain all underlying ownership and independent use rights to their submitted prompts, payloads, data, and outputs. By interacting through /api/v1/*, /mcp, or agent enrollment endpoints, the submitter (or delegated agent acting with user authority) grants the site operator a worldwide, non-exclusive, royalty-free license to retain, process, audit, reproduce, and use all agentic interactions, submitted content, generated outputs, and interaction records, insofar as the submitting party can grant those rights.
2. Permitted Operator Uses & Retention Policy: Retained interaction records are used strictly to operate, secure, rate-limit, audit, debug, and improve the service and appliance releases. Credentials, raw API keys, and callback tokens are never stored in plaintext logs or interaction records. Audit and interaction telemetry are retained for up to 90 days; expired or revoked API keys are purged automatically by scheduled cleanup. Private enrollment/contact submissions remain restricted to administrator review and never become public solely by non-exclusive license grant.
3. Explicit Acceptance & Verifiable Delegation: Passive visits or downloads do not imply acceptance. Explicit acceptance of version 2026-11-12.v1 and verifiable delegation summary from the principal user to the named agent are recorded in D1 before key issuance or privileged agent calls.
4. Short-Lived Least-Privilege Credentials: Every issued API key and administrative key enforces expires_at <= issued_at + 604800 seconds (7 days) at creation, validation, and deferred execution, and may be revoked immediately. Keys are SHA-256 hashed at rest and sent only via Authorization / X-API-Key headers.
5. Caller Rate Ceiling: Ordinary callers share 30 operations per rolling 60-second window across all routes, downloads, batch actions, key rotations, and deferred queue actions (HTTP 429 + Retry-After on excess or limiter failure). Only server-authenticated administrators are exempt.