{ "openapi": "3.1.0", "info": { "title": "Etch public API", "description": "Signed audit chain for AI agent decisions, offline-verifiable against pinned public keys. Every event is signed with a hybrid Ed25519 + FIPS 205 SLH-DSA-SHA2-128f envelope, Merkle-chained into an epoch, and epoch-anchored on Sigstore Rekor + Bitcoin OpenTimestamps. This document covers only the unauthenticated integration surface; the admin API requires bearer authentication and is not published.", "version": "0.2.0", "license": { "name": "BUSL-1.1", "url": "https://spdx.org/licenses/BUSL-1.1.html" }, "contact": { "name": "Etch", "url": "https://etch.systems", "email": "support@etch.systems" } }, "servers": [ { "url": "https://etch.systems", "description": "Production" } ], "paths": { "/v1/your-project": { "post": { "summary": "Mint an anonymous project + bearer token (free tier, 500 events, 14 days)", "description": "Zero-signup path. Returns a bearer token, a project_id, and an mcp_endpoint URL. Use the token as Authorization: Bearer on every subsequent request to /mcp.", "operationId": "mintAnonymousProject", "tags": [ "Onboarding" ], "responses": { "200": { "description": "Anonymous project minted", "content": { "application/json": { "schema": { "type": "object", "required": [ "project_id", "token", "mcp_endpoint" ], "properties": { "project_id": { "type": "string", "example": "anon-abc123" }, "token": { "type": "string", "description": "Bearer token with mcp:read + mcp:write scopes" }, "mcp_endpoint": { "type": "string", "format": "uri", "example": "https://etch.systems/mcp" } } } } } } } } }, "/v1/identity/session": { "post": { "summary": "Idempotent-per-identity mint or attach; portable-identity clients bind to a project", "description": "The client signs a session challenge with the identity's Ed25519 key; the server either reuses the identity's existing project or mints a fresh one. Bearer returned in the response has mcp:read + mcp:write scopes.", "operationId": "identitySession", "tags": [ "Portable identity" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "external_identity" ], "properties": { "external_identity": { "type": "object" }, "use_identity_memory": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "/v1/identity/rotate": { "post": { "summary": "Rotate a portable identity's keypair; the OLD key's signature IS the authorization", "operationId": "identityRotate", "tags": [ "Portable identity" ], "responses": { "200": { "description": "OK" } } } }, "/v1/identity/grant": { "post": { "summary": "Delegate authority to another identity; grantor signature IS the authorization", "operationId": "identityGrant", "tags": [ "Portable identity" ], "responses": { "200": { "description": "OK" } } } }, "/v1/identity/revoke-grant": { "post": { "summary": "Revoke a delegation grant; grantor signature IS the authorization; idempotent", "operationId": "identityRevokeGrant", "tags": [ "Portable identity" ], "responses": { "200": { "description": "OK" } } } }, "/v1/identity/delegated-write": { "post": { "summary": "Append a chain row on behalf of a grantor; grantee signature verifies; grant enforced", "operationId": "identityDelegatedWrite", "tags": [ "Portable identity" ], "responses": { "200": { "description": "OK" } } } }, "/auditor/{slug}/oss-manifest.json": { "get": { "summary": "Stream the OSS etch-verify manifest for a project's chain (offline verify path)", "operationId": "auditorOssManifest", "tags": [ "Auditor" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } } ], "responses": { "200": { "description": "OSS v1 manifest; consume with etch-verify (`pip install world-model-mcp && etch-verify manifest.json`)" } } } }, "/auditor/{slug}/chain-check.json": { "get": { "summary": "Return recent hash-chain entries for the browser-side integrity widget", "operationId": "auditorChainCheck", "tags": [ "Auditor" ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } } ], "responses": { "200": { "description": "OK" } } } }, "/projects/{project_id}/audit-log/public-keys": { "get": { "summary": "Pinnable public keys for offline verification (Ed25519 + SLH-DSA)", "operationId": "auditLogPublicKeys", "tags": [ "Auditor" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/projects/{project_id}/audit-log/dump/manifest": { "get": { "summary": "Signed manifest header for the sealed audit-log SQLite dump", "operationId": "auditLogDumpManifest", "tags": [ "Auditor" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" } } } }, "/.well-known/mcp/server-card.json": { "get": { "summary": "SEP-1649 MCP Server Card; discoverable endpoint + version for aggregators", "operationId": "wellKnownMcpServerCard", "tags": [ "Discovery" ], "responses": { "200": { "description": "OK" } } } }, "/.well-known/oauth-protected-resource": { "get": { "summary": "RFC 9728 Protected Resource Metadata; declares bearer-only (no OAuth flow)", "operationId": "wellKnownOauthProtectedResource", "tags": [ "Discovery" ], "responses": { "200": { "description": "OK" } } } } }, "tags": [ { "name": "Onboarding", "description": "Zero-signup path to a signed audit chain." }, { "name": "Portable identity", "description": "Track B v1.0+v1.1 portable per-agent identity: mint, session, rotate, grant/revoke, delegated write." }, { "name": "Auditor", "description": "Public verification surface: pinnable public keys, OSS-format manifest, browser chain-integrity endpoint." }, { "name": "Discovery", "description": "Well-known metadata endpoints for aggregators and MCP clients." } ], "externalDocs": { "description": "Full documentation", "url": "https://etch.systems/docs" } }