{"openapi":"3.1.0","info":{"title":"Encoded Brands Agent Encoder","version":"2026-09-01","description":"A machine client can start a free Clerk-bound draft through a PKCE-protected browser identity handoff, use Encoded's evidence and question flow over MCP, and publish a basic signed public BCP after the owner approves the exact draft. Payment is not required for basic publication. Registry Certified is a separate optional upgrade."},"servers":[{"url":"https://encoder.encodedbrands.ai"}],"externalDocs":{"url":"https://encoder.encodedbrands.ai/.well-known/agent-commerce.json"},"paths":{"/api/agent/register":{"post":{"operationId":"registerAgent","summary":"Pay once to obtain an API key and included first encoding session","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationRequest"}}}},"responses":{"200":{"description":"Paid registration completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistrationResponse"}}}},"402":{"description":"Machine-readable payment challenge. Retry the same body with Authorization: Payment <spt_...>.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/api/agent/mcp":{"post":{"operationId":"callEncoderMcp","summary":"Create and publish a basic BCP with explicit owner approval, then optionally upgrade","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC result"},"401":{"description":"A tool invocation requires the API key returned by registration"}}}},"/api/agent/keys":{"delete":{"operationId":"revokeAgentCredential","summary":"Revoke the presented self-registered API credential","description":"A synthetic/self-registered principal can revoke only the same credential used to authorize this request. Revocation is immediate and irreversible.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Credential revoked, or already unavailable"},"401":{"description":"Invalid, missing, or already revoked credential"},"403":{"description":"A self-registered credential attempted to target another key"}}}},"/api/agent/registry-usage":{"get":{"operationId":"getRegistryUsage","summary":"Read Registry Certified privacy-safe usage analytics for an owned encoding session","description":"Returns asynchronous 30-day totals, daily trend, HTTP/MCP and file/tool breakdowns, coarse client family/major buckets, revision buckets, freshness, and privacy suppression metadata. Client buckets are not people or devices.","security":[{"bearerAuth":[]}],"parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Owner-scoped Registry usage report or not_published status"},"401":{"description":"Invalid or missing Encoded API key"},"404":{"description":"Session does not exist or belongs to another API-key owner"}}}},"/api/registry/claim":{"post":{"operationId":"claimRegistryBrand","summary":"Start or complete a free DNS-verified claim of an available Registry placeholder","description":"Requires an authenticated human workspace. Discover an available handle in the Registry directory, then use its human landing page when browser authentication or DNS access is required.","security":[{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegistryClaimRequest"}}}},"responses":{"200":{"description":"Challenge issued or verified claim completed"},"400":{"description":"Invalid request, attestation missing, or DNS proof not visible"},"401":{"description":"Human sign-in required"},"409":{"description":"Brand is no longer available to claim"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Encoded API key (eba_live_...)"},"cookieAuth":{"type":"apiKey","in":"cookie","name":"__session","description":"Authenticated Encoded Brands browser session"}},"schemas":{"RegistrationRequest":{"type":"object","additionalProperties":false,"properties":{"contact_email":{"type":"string","format":"email"},"domain":{"type":"string","example":"example.com"},"label":{"type":"string","maxLength":120}}},"RegistrationResponse":{"type":"object","required":["ok","api_key","session_id","price_charged_cents","payment_intent_id"],"properties":{"ok":{"const":true},"api_key":{"type":"string","description":"Shown once. Store securely."},"session_id":{"type":["string","null"],"format":"uuid"},"price_charged_cents":{"type":"integer","example":49900},"payment_intent_id":{"type":"string"}}},"PaymentRequired":{"type":"object","required":["type","title","status","detail","payment"],"properties":{"type":{"type":"string","format":"uri"},"title":{"const":"Payment Required"},"status":{"const":402},"detail":{"type":"string"},"payment":{"type":"object","properties":{"amount_cents":{"type":"integer","example":49900},"currency":{"const":"usd"},"methods":{"type":"array","items":{"const":"shared_payment_token"}}}}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","id","method"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","integer"]},"method":{"enum":["initialize","tools/list","tools/call"]},"params":{"type":"object"}}},"RegistryClaimRequest":{"type":"object","additionalProperties":false,"required":["action","customer_handle"],"properties":{"action":{"enum":["start","complete"]},"customer_handle":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,127}$"},"authority_confirmed":{"type":"boolean","description":"Required and true when action=start."},"terms_accepted":{"type":"boolean","description":"Required and true when action=start."}}}}},"x-encoded-brands-agent-commerce":{"schema_version":"2026-09-01","service":"Encoded Brands Encoder","canonical_url":"https://encoder.encodedbrands.ai/.well-known/agent-commerce.json","status":"live","description":"A machine client can start a free Clerk-bound draft through a PKCE-protected browser identity handoff, use Encoded's evidence and question flow over MCP, and publish a basic signed public BCP after the owner approves the exact draft. Payment is not required for basic publication. Registry Certified is a separate optional upgrade.","pricing_authority":"https://encodedbrands.ai/#pricing","terms_url":"https://encoder.encodedbrands.ai/terms","privacy_url":"https://encoder.encodedbrands.ai/privacy","refunds_url":"https://encoder.encodedbrands.ai/terms#refunds","openapi_url":"https://encoder.encodedbrands.ai/openapi.json","llms_txt_url":"https://encoder.encodedbrands.ai/llms.txt","offers":{"byo_ai_onboarding":{"price":"free","endpoint":"https://encoder.encodedbrands.ai/api/agent/mcp","tool":"begin_onboarding","identity":"Verified Clerk user and verified primary email","payment_required":false,"publication":"Basic signed public BCP after exact-draft owner approval and authority confirmation","durable_session_before_identity":false,"resume":{"protocol":"PKCE S256 plus single-use handoff code","status_tool":"get_onboarding_status","exchange_tool":"exchange_onboarding_code","access_token_ttl_seconds":3600}},"agent_registration":{"amount_cents":49900,"currency":"usd","interval":"one_time","includes":["one API key","one complete encoding session"],"endpoint":"https://encoder.encodedbrands.ai/api/agent/register","method":"POST","payment":{"protocol":"Stripe Shared Payment Token","challenge":"HTTP 402 application/problem+json","retry_header":"Authorization: Payment <spt_...>"}},"subsequent_encode":{"amount_cents":4900,"currency":"usd","interval":"per_use","endpoint":"https://encoder.encodedbrands.ai/api/agent/mcp","tool":"start_encode","idempotency":"Supply a UUID action_id and reuse it only for an exact retry."},"registry_certified":{"amount_cents":598800,"monthly_equivalent_cents":49900,"annual_charge_cents":598800,"currency":"usd","interval":"year","billing_interval":"annual","display_price":"$499 / month, charged annually.","lookup_key":"registry_certified_annual","endpoint":"https://encoder.encodedbrands.ai/api/agent/mcp","tool":"subscribe_certified","idempotency":"Supply a UUID action_id and reuse it only for an exact retry.","legal":{"terms_url":"https://encoder.encodedbrands.ai/terms","terms_version":"2026-07-11","required_request_fields":{"terms_accepted":true,"terms_version":"2026-07-11"}},"payment":{"methods":["shared_payment_token"],"shared_payment_token":{"supported":true,"field":"payment_token","protocol":"Stripe Shared Payment Token"},"hosted_checkout":{"supported":false,"reason":"Certified subscribe completes in MCP with payment_token. Human Stripe Checkout remains available in the Encoder GUI after Clerk sign-in."},"crypto":{"supported":false,"message":"On-chain USDC deposits are not available yet. Pay stablecoin through a Shared Payment Token and omit rail."},"not_now_supported":true},"includes":["named audit of authenticated gated access","owner controls for who can receive gated material","signed history, diffs, and restore for what was live","a visible certification mark and machine-readable service status for the active revision","unlimited teammates","up to 100 AI-assisted re-encodes per year","priority human support"],"boundary":"Payment does not certify a revision by itself. The mark records a paid service designation for the exact active revision. It does not certify that every statement is true. Public brand files stay public. Privacy-safe aggregate public-read analytics are not named-user audit records."}},"registry_claim":{"directory_url":"https://registry.brandcontextprotocol.dev/directory.json?status=available","human_landing_template":"https://registry.brandcontextprotocol.dev/brands/{customer_handle}","encoder_landing_template":"https://encoder.encodedbrands.ai/claim/{customer_handle}","endpoint":"https://encoder.encodedbrands.ai/api/registry/claim","method":"POST","price":"free","authorization":"Signed-in brand representative plus exact DNS TXT proof","actions":["start","complete"],"boundary":"No public ownership changes until DNS proof succeeds. Agents should hand the landing URL to an authorized human when browser authentication or DNS access is required."},"mcp":{"endpoint":"https://encoder.encodedbrands.ai/api/agent/mcp","transport":"Streamable HTTP JSON-RPC","protocol_version":"2025-06-18","authentication":"Authorization: Bearer <api_key>","credential_acquisition":"https://encoder.encodedbrands.ai/api/agent/register","human_identity_acquisition":{"tool":"begin_onboarding","instruction":"Call begin_onboarding without a bearer token, then complete its PKCE identity handoff."},"credential_revocation":"DELETE https://encoder.encodedbrands.ai/api/agent/keys with Authorization: Bearer <api_key>","public_methods":["initialize","tools/list"],"public_tools":["begin_onboarding","get_onboarding_status","exchange_onboarding_code"],"human_owned_draft_journey":["generate a PKCE code_verifier and S256 code_challenge","call begin_onboarding and show the returned continue_url to the human","the human signs in or verifies email with Clerk and accepts the public-publication notice","poll get_onboarding_status with the original code_verifier","exchange the single-use handoff_code for a one-hour token bound to that draft session","add sources and use the Encoded question flow; no payment card is requested during bootstrap","compile and show the exact draft_revision to the owner for review","after the owner approves that exact draft and confirms authority, call publish to create the basic signed public BCP without payment","return the Registry file URL, public MCP URL, trust state, next verification action, and optional Registry Certified offer","the owner may choose not now; the basic public BCP remains live","after a disconnect or token expiry, call begin_onboarding again with a new action_id, new PKCE challenge, and resume_session_id; the browser re-verifies the same Clerk owner"],"prepaid_machine_registration_journey":["POST registration without a payment credential and read the 402 challenge","create a Stripe Shared Payment Token and retry registration with the Payment authorization header","store the returned API key and use the included session_id","call add_source, research, list_confirmations, decide_confirmations, finalize_confirmations, answer_gaps, compile, and publish","to add Registry Certified, call subscribe_certified with terms_accepted, terms_version, and payment_token (spt_...); hosted Checkout is not used","fetch the returned Registry URL and verify its Ed25519 signature and trust metadata"]}}}