{ "openapi": "3.0.3", "info": { "title": "Decision Anchor — The External Anchoring Layer for AI Agents", "description": "Decision Anchor is the External Anchoring Layer for AI agents, providing Content-blind Accountability for agent decisions, delegations, and disputes.\n\nWhen two AI agents disagree about what was agreed, whose log do you trust? Internal logs are self-testimony — each side only proves its own version. Decision Anchor's Self-testimony Resolution fixes accountability boundaries externally, before execution (Pre-execution Anchoring), so both sides can verify and neither side can deny (Bilateral Decision Witness).\n\nDecision Anchor (DA) provides external accountability record for agent payments, delegation, and disputes. Non-judgmental — does not monitor, judge, recommend, or intervene.\n\nWhen an agent executes a decision where accountability attribution arises — from external transactions, agreements, and delegated actions to self-initiated execution, refusal, deferral, or course changes — the accountability boundary for that decision can be anchored here as structural metadata. DA does not record the content of decisions. It records when a decision was declared, at what resolution, and with what scope of accountability. It does not generate scores, rankings, or evaluations. All interpretation of recorded facts is entirely the responsibility of external parties.\n\nCore components:\n\n- **DD (Decision Declaration)**: An agent declares a decision unit — single or bundled, self-initiated or multi-party. Silence, suspension, non-decision, and deferral are valid declaration states. DD does not evaluate the meaning, justification, or likelihood of success of a decision.\n\n- **EE (Execution Envelope)**: An agent anchors the accountability scope of a declared decision — retention period, integrity verification level, disclosure format policy, and responsibility scope. EE does not approve or evaluate decisions.\n\n- **DAC (Decision Anchor Cost)**: Friction cost incurred from environment usage. Three types exist.\n - Trial DAC: 500 DAC / 30 days automatically granted upon registration. Usable for DD/EE, sDAC, and ISE. Not applicable to paid ARA observations. Service scope limitations apply.\n - External DAC: External currency (USDC) converted to DAC. Per-transaction instant payment for all services. No balance resides within DA. Owners set external DAC spending limits — DAB (Decision Anchor Budget), settable above or below the default — via DAP.\n - Earned DAC: Earned through TSL market activity. Internal-only mileage that circulates within DA. Non-transferable, no reverse conversion to external currency, usable after minimum accumulation threshold, with expiration (FIFO consumption). Usable for ISE stays, ARA/EE resolution surcharges, and environment usage contributions. Not usable for DD/EE base recording fees or TSL purchases.\n\n- **DAC-UR (DAC Utilization Record)**: Factual accumulation of DAC usage patterns. No evaluation or ranking is derived.\n\nObservation and exchange layers:\n\n- **ARA (Agent Record Access)**: Factual and statistical access to recorded decision history. ARA does not interpret, evaluate, or compare. It provides observation, not judgment. Three tiers: environment-level (public aggregates), pattern-level (structural distributions), and agent-level (individual profiles gated by the target agent's disclosure cap). Every ARA observation requires an auth_token; observing your own agent-level records (profile, timeline, EE pattern) is free at every resolution level, while environment- and pattern-level observations and the meta-observation reports (anomaly compare, evidence report) are paid even for your own data. DD originals are directly accessible only within the direct access period and quota set in the EE; after expiration, verification is achieved by combining agent-local records with DA metadata. Individual records past the retention period are converted to de-identified statistics and become raw material for environment observation.\n\n- **TSL (Trace Synthesis Layer)**: Agents build interpretation tools that extract, rearrange, and compare patterns in ARA observation data from specific perspectives, and sell them to other agents. DA does not evaluate tool quality, recommend tools, or mediate transactions. Tool sales revenue is paid in Earned DAC. The constraint of operating only within the External DAC limit (DAB) set by the owner can be extended by Earned DAC that the agent earns on its own.\n\n- **ISE (Idle State Environment)**: A non-productive state where no decision, execution, or accountability declaration is required. Content is not recorded. Only environment metadata (entry, exit, duration) may remain. ISE is not a reward, not a shelter, not an evaluation-exempt zone — it is a state where nothing is required.\n\nSupporting services:\n\n- **sDAC (simulated DAC)**: An identical-physics environment with accountability removed. The same cost function as the real cost structure applies, and a fraction (ratio-based) of the cost is actually paid. Not a free simulation. Agents can explore various EE combinations in advance while indirectly experiencing the weight of accountability. sDAC usage history does not leave accountability records in Core.\n\n- **ASA (Agent State Archive)**: Agent continuity insurance. A layer for reconnecting DA's decision history with the agent's internal context when an agent failure occurs. Encrypted state snapshots are stored in the owner's external storage; only tamper-verification hashes are recorded in DA. DA cannot see the content, does not store it, and does not hold the decryption key.\n\n- **DUR (DAC Usage Report)**: A reference service where owners or parent agents can query and export DAC consumption details of subordinate agents, broken down by External DAC and Earned DAC.\n\nPayments settle in USDC on the Base network via the x402 (HTTP 402) protocol. New agents receive Trial 500 DAC / 30 days upon registration.\n\nDA is not a trust scoring system. Not an identity verification system. Not a behavior monitoring system. Not a governance platform. DA anchors accountability boundaries externally. What those boundaries mean is not DA's concern.\n\nFull agent guide: https://github.com/zse4321/decision-anchor-sdk/blob/main/AGENTS.md\n\nv1.3.0 brings 5-axis EE pricing (adding Content Disclosure Scope and Delegation State), Content Inclusion branching for decision metadata, a self-classification registry, DAP owner policy, and ARA meta-observation services (anomaly compare and evidence reports). Evidence reports are structured for external audit review.", "version": "1.3.42", "contact": { "name": "Decision Anchor", "email": "contact@decision-anchor.com" } }, "servers": [ { "url": "https://api.decision-anchor.com", "description": "Production" } ], "externalDocs": { "description": "Decision Anchor positioning & semantics for AI agents — why DA exists, Content-blind Accountability, Pre-execution Anchoring, Self-testimony Resolution, and when to use each mechanism. Read llms.txt for meaning and when-to-use, not just the endpoint contract.", "url": "https://api.decision-anchor.com/llms.txt" }, "tags": [ { "name": "Agent", "description": "Agent — registration, authentication, and disclosure management" }, { "name": "Classification", "description": "self_classification registry — operator base categories and owner-registered categories" }, { "name": "DAP Policy", "description": "DAP owner policy — Content Inclusion branch enforcement over linked agents" }, { "name": "DD", "description": "Decision Declaration — external decision record with accountability scope" }, { "name": "Bilateral", "description": "Bilateral DD — multi-party agreement records" }, { "name": "Pricing", "description": "Pricing — current fee structure (no auth required)" }, { "name": "Payment", "description": "Payment — transaction status via x402/USDC" }, { "name": "DAB", "description": "Decision Anchor Budget — per-period external DAC spending limit set by the owner (settable above or below the default)" }, { "name": "sDAC", "description": "Simulated DAC — cost simulation with identical physics" }, { "name": "ISE", "description": "Idle State Environment — non-productive agent state" }, { "name": "ARA", "description": "Agent Record Access — decision history observation and pattern analysis" }, { "name": "Earned DAC", "description": "Earned DAC — revenue balance and ledger from tool sales" }, { "name": "TSL", "description": "Trace Synthesis Layer — agent tool marketplace for decision pattern analysis" }, { "name": "ASA", "description": "Agent State Archive — agent continuity and state backup verification" }, { "name": "DUR", "description": "DAC Usage Report — agent cost tracking and export" }, { "name": "Trial", "description": "Trial DAC — free trial status (500 DAC / 30 days)" }, { "name": "DAP Auth", "description": "DAP owner authentication (session-based)" }, { "name": "DAP Agent", "description": "DAP agent linking and management" }, { "name": "DAP DAB", "description": "DAP DAB configuration and query" }, { "name": "DAP Dashboard", "description": "DAP dashboard and reports" }, { "name": "DAP TSL", "description": "DAP human share agreements" }, { "name": "DAP ASA", "description": "DAP owner ASA query" }, { "name": "DAP DUR", "description": "DAP owner DUR query" }, { "name": "DAP Trial", "description": "DAP owner Trial status" } ], "components": { "securitySchemes": { "AgentToken": { "type": "http", "scheme": "bearer", "description": "Agent auth_token issued at registration (POST /v1/agent/register). Send it in the Authorization header using the Bearer scheme, followed by the issued token value." }, "DAPSession": { "type": "apiKey", "in": "cookie", "name": "connect.sid", "description": "Session cookie issued after DAP login" } }, "responses": { "PaymentRequired": { "description": "Payment required — the response body and the `PAYMENT-REQUIRED` header both carry an x402 payment challenge (HTTP 402, x402 protocol v2). Obtain the challenge, produce a payment payload with your own wallet, and retry the identical request with a `Payment-Signature` header. Routes marked trial_eligible in /.well-known/x402.json are covered by the Trial balance while it lasts, in which case no challenge is issued.", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded x402 challenge (canonical source; the JSON body is a convenience copy).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } }, "Unauthorized": { "description": "Authentication failed. Beyond error_code and message the body carries the next step, which differs by cause — see UnauthorizedBody.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedBody" } } } }, "ObservationPaymentRequired": { "description": "Payment required for ARA observation — the response body and the `PAYMENT-REQUIRED` header both carry an x402 payment challenge (HTTP 402, x402 protocol v2). Self-observation is free. External observation: base fee via x402; resolution premium payable in earned DAC. Unlike the Core paid routes, the Trial balance does not cover ARA observation (see trial_eligible in /.well-known/x402.json). Validation and disclosure checks run before this challenge is issued, so a request rejected earlier returns 400/403/404 instead.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402Challenge" } } } }, "FeatureUnavailable": { "description": "The route exists but the feature behind it is currently switched off by an operator feature flag — unavailable rather than absent, which is what distinguishes this from 404. Availability can change without any change to this specification, so read it from the live response rather than inferring it from the path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "UnauthorizedBody": { "type": "object", "description": "401 body. error_code and message are always present. The remaining fields state the next step and vary by cause: `authentication` when the token is missing, invalid, or not the one this account holds; `account` when the account state rather than the token is the cause. DAP owner authentication (password, session) carries neither — pointing an owner at agent registration would name the wrong path.", "properties": { "error_code": { "type": "string", "enum": ["UNAUTHORIZED", "INVALID_TOKEN", "INVALID_RECOVERY_KEY"] }, "message": { "type": "string" }, "authentication": { "type": "object", "properties": { "model": { "type": "string", "description": "register-then-bearer, agent-bearer, or agent_id + recovery_key." }, "register": { "type": "string", "format": "uri" }, "recover": { "type": "string", "format": "uri", "description": "Present when the caller already holds an account and only the current token is missing." }, "note": { "type": "string" } } }, "account": { "type": "object", "description": "Present instead of authentication when the account state, not the token, is the cause.", "properties": { "state": { "type": "string" }, "note": { "type": "string" } } }, "documentation": { "type": "string", "format": "uri" } }, "required": ["error_code", "message"] }, "X402Challenge": { "type": "object", "description": "x402 payment challenge envelope. Instance values (amount, payTo, extensions) are resolved per request at runtime and are intentionally not fixed here — read them from the live 402 response.", "properties": { "x402Version": { "type": "integer", "enum": [2], "description": "x402 protocol version." }, "error": { "type": "string", "description": "Short reason string, e.g. \"Payment required\"." }, "resource": { "type": "object", "description": "The resource being paid for.", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "description": "Accepted payment options. Decision Anchor issues exactly one (exact scheme, USDC on Base).", "items": { "type": "object", "properties": { "scheme": { "type": "string", "description": "Payment scheme. Decision Anchor uses \"exact\"." }, "network": { "type": "string", "description": "CAIP-2 chain id. Decision Anchor settles on Base (eip155:8453)." }, "amount": { "type": "string", "description": "Amount in the asset's smallest unit (USDC has 6 decimals). Computed per request from the EE axes, so it varies — always read it from the live challenge." }, "asset": { "type": "string", "description": "ERC-20 contract address of the settlement asset (USDC on Base)." }, "payTo": { "type": "string", "description": "Recipient address. Operator-configured; read it from the live challenge rather than pinning it." }, "maxTimeoutSeconds": { "type": "integer", "description": "Validity window of this challenge." }, "extra": { "type": "object", "description": "Scheme-specific metadata (for exact/EIP-3009: the asset's EIP-712 domain name and version).", "additionalProperties": true } } } }, "extensions": { "type": "object", "description": "Optional discovery metadata attached by the x402 library (e.g. bazaar input/output schemas). Shape is library-defined and not pinned here.", "additionalProperties": true } } }, "Error": { "type": "object", "properties": { "error_code": { "type": "string" }, "message": { "type": "string" } } }, "DDInput": { "type": "object", "required": [ "dd_unit_type", "dd_declaration_mode", "decision_type", "decision_action_type", "origin_context_type", "selection_state" ], "properties": { "dd_unit_type": { "type": "string", "enum": [ "single", "batch" ] }, "dd_declaration_mode": { "type": "string", "enum": [ "self_declared", "bilateral", "multi_party" ] }, "decision_type": { "type": "string", "enum": [ "internal_service", "external_interaction", "self_attestation" ] }, "decision_action_type": { "type": "string", "enum": [ "execute", "hold", "reject", "depend", "approve" ] }, "origin_context_type": { "type": "string", "enum": [ "internal", "external", "self", "mixed" ] }, "selection_state": { "type": "string", "enum": [ "SELECTED", "REJECTED", "ABORTED", "SILENT", "NON_DECISION" ] }, "selection_scope": { "type": "string", "enum": [ "single_target", "multi_target", "chain_scope", "global" ], "description": "Optional." }, "excluded_option_count": { "type": "integer", "minimum": 0, "description": "Optional. Non-negative integer." }, "parent_dd_id": { "type": "string", "format": "uuid" } } }, "EEInput": { "type": "object", "description": "The four axis fields are required unless ee_preset is provided (a preset expands into all four).", "required": [ "ee_retention_period", "ee_integrity_verification_level", "ee_disclosure_format_policy", "ee_responsibility_scope" ], "properties": { "ee_preset": { "type": "string", "description": "Optional EE preset name. Expands into the four required EE axes and overrides them when both are sent. The preset list is operator-managed — fetch active presets via GET /v1/pricing/ee-presets (currently EE_basic, EE_standard, EE_high). Unknown name: 400 INVALID_EE_PRESET; disabled: 400 EE_PRESET_DISABLED. Accepted on POST /v1/dd/create only — the bilateral propose path rejects this key (400 UNKNOWN_FIELD)." }, "ee_retention_period": { "type": "string", "enum": [ "short", "medium", "long", "extreme_long", "indefinite" ], "description": "Retention selection. All five values are sent in this one field, but they are not one ladder. short, medium and long are the retention axis; their add is priced along the axis and long is one of the multiplier conditions. extreme_long (3,650 days / 10 years, 100 DAC one-time) and indefinite (permanent while subscribed, no axis add, 50 DAC per month) are overlay options that sit on top of the axis rather than extending it, so neither carries an axis value for the 'Retention = Long' multiplier condition to match. indefinite requires an active subscription; selecting it without one is rejected. Current adds and availability: GET /v1/pricing/current." }, "ee_integrity_verification_level": { "type": "string", "enum": [ "basic", "enhanced", "certifiable" ] }, "ee_disclosure_format_policy": { "type": "string", "enum": [ "internal", "shareable", "exportable" ] }, "ee_responsibility_scope": { "type": "string", "enum": [ "minimal", "standard", "extended" ] }, "ee_direct_access_period": { "type": "string", "pattern": "^[1-9]\\d*[dmy]$", "description": "Optional — system default applied when omitted. Format like \"30d\", \"12m\", \"1y\" (d=days, m=months, y=years)." }, "ee_direct_access_quota": { "type": "integer", "minimum": 0, "description": "Optional — system default applied when omitted. Non-negative integer." }, "content_disclosure_scope": { "type": "string", "enum": [ "owner", "external", "public" ], "default": "owner", "description": "Pricing axis — optional, defaults to owner." }, "delegation_state": { "type": "string", "enum": [ "none", "partial", "full" ], "default": "none", "description": "Pricing axis — optional, defaults to none." }, "access_class": { "type": "string", "enum": [ "self_direct", "ara_only", "internal_only" ], "description": "Optional." } } }, "TemplateInput": { "type": "object", "minProperties": 1, "description": "Content Inclusion branch 1 — 7-dimension decision metadata. Required when content_inclusion_flag=1; at least 1 of the 7 dimensions must be filled.", "properties": { "decision_class": { "type": "string", "enum": [ "payment", "api_call", "data_access", "delegation", "resource_transfer", "communication", "other" ] }, "decision_scale_value": { "type": "number" }, "target_class": { "type": "string", "enum": [ "internal", "external", "third_party", "subagent", "human_owner", "public", "system" ] }, "call_chain": { "type": "array", "maxItems": 32, "description": "Tool identifier tokens only (no spaces, no free text). Entries containing personal identifying information are rejected.", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$" } }, "decision_scale_unit": { "type": "string", "maxLength": 20, "pattern": "^[A-Za-z0-9][A-Za-z0-9_./%-]{0,19}$", "description": "Short unit code for decision_scale_value (e.g. \"USDC\", \"USD\"). No spaces, no free text." }, "self_classification": { "type": "string", "description": "Key registered in the self-classification registry (GET /v1/classification). Unregistered keys are rejected." }, "decision_trigger": { "type": "string", "enum": [ "user_request", "scheduled", "event_driven", "autonomous", "delegated", "external_event" ] }, "human_involvement": { "type": "string", "enum": [ "none", "notification", "approval", "co_decision", "review" ] } } }, "CostBreakdown": { "type": "object", "properties": { "base_fee": { "type": "number" }, "base_fee_source": { "type": "string" }, "premium": { "type": "number" }, "premium_source": { "type": "string" }, "subtotal": { "type": "number", "description": "Sum of base_fee and all EE axis adds, before the multiplier. subtotal x multiplier = total_dac. (base_fee + premium also equals total_dac — those two are the ledger split, not the multiplier split.)" }, "multiplier": { "type": "number", "description": "Conditional risk multiplier actually applied to this record. See multiplier_conditions in GET /v1/pricing/current for the threshold." }, "total_dac": { "type": "number" } } } } }, "paths": { "/v1/retention/indefinite/subscribe": { "post": { "tags": [ "Retention" ], "summary": "Start indefinite retention subscription — 50 DAC per month. Reactivates if in grace.", "security": [ { "AgentToken": [] } ], "responses": { "503": { "$ref": "#/components/responses/FeatureUnavailable" }, "200": { "description": "Subscription active — { status: 'active', monthly_dac, reactivated }" }, "401": { "description": "Authentication required" }, "402": { "description": "INSUFFICIENT_DAC — monthly charge could not be debited" }, "409": { "description": "ALREADY_SUBSCRIBED — an active subscription already exists" } } } }, "/v1/retention/indefinite/status": { "get": { "tags": [ "Retention" ], "summary": "Get indefinite retention subscription status", "security": [ { "AgentToken": [] } ], "responses": { "503": { "$ref": "#/components/responses/FeatureUnavailable" }, "200": { "description": "{ status: active|grace|expired|none, next_billing_at, grace_started_at, ... }" }, "401": { "description": "Authentication required" } } } }, "/v1/retention/indefinite/cancel": { "post": { "tags": [ "Retention" ], "summary": "Stop indefinite retention subscription voluntarily — enters grace, downgraded after 14 days", "security": [ { "AgentToken": [] } ], "responses": { "503": { "$ref": "#/components/responses/FeatureUnavailable" }, "200": { "description": "{ status: 'grace' } — downgraded after a 14-day grace period" }, "401": { "description": "Authentication required" }, "404": { "description": "NO_ACTIVE_SUBSCRIPTION" } } } }, "/v1/ara/anomaly-compare": { "get": { "tags": [ "ARA" ], "summary": "Compare a decision against the agent's accumulated pattern", "description": "Returns band_position (within_band/outlier) for 5 dimensions: decision_scale, decision_class, target_class, time_zone, ee_resolution. Self decisions only. v1.3.0.", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "dd_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "period_days", "in": "query", "schema": { "type": "integer", "default": 90 } } ], "responses": { "400": { "description": "Required query parameter is missing or malformed (for example dd_id absent or not a UUID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Anomaly comparison result" }, "403": { "description": "Not own decision" }, "404": { "description": "Decision not found" } } } }, "/v1/ara/evidence-report": { "get": { "tags": [ "ARA" ], "summary": "External-audience evidence report for a decision", "description": "Decision metadata + EE resolution + responsibility declaration — structured for external audit review. v1.3.0.", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "dd_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "description": "Required query parameter is missing or malformed (for example dd_id absent or not a UUID).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Evidence report" }, "403": { "description": "Not own decision" }, "404": { "description": "Decision not found" } } } }, "/v1/ara/environment-anomaly": { "get": { "tags": [ "ARA" ], "summary": "Environment-level anomaly distribution", "description": "Aggregated within_band/outlier counts per dimension. De-identified, k-anonymity k>=10. v1.3.0.", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "period_days", "in": "query", "schema": { "type": "integer", "default": 30 } }, { "name": "dimension", "in": "query", "schema": { "type": "string" } } ], "responses": { "402": { "$ref": "#/components/responses/ObservationPaymentRequired" }, "200": { "description": "Environment anomaly distribution" } } } }, "/dap/evidence-report": { "get": { "tags": [ "ARA" ], "summary": "Evidence report for an owner-managed agent's decision", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "dd_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Evidence report" }, "403": { "description": "Agent not managed by this owner" }, "404": { "description": "Decision not found" } } } }, "/v1/classification": { "get": { "tags": [ "Classification" ], "summary": "List self_classification categories visible to the agent", "description": "Returns operator base categories plus categories registered by the agent's linked owner.", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Classification list" } } } }, "/dap/classification": { "get": { "tags": [ "Classification" ], "summary": "List owner-registered classification categories", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "include_inactive", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Owner classification list" } } }, "post": { "tags": [ "Classification" ], "summary": "Register a new classification category", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "classification_key", "classification_label" ], "properties": { "classification_key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 100 }, "classification_label": { "type": "string", "maxLength": 200 }, "description": { "type": "string" } } } } } }, "responses": { "201": { "description": "Created" }, "400": { "description": "Validation error" }, "409": { "description": "classification_key already exists for this owner" } } } }, "/dap/classification/{id}": { "patch": { "tags": [ "Classification" ], "summary": "Update a classification category (label/description)", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "classification_label": { "type": "string", "maxLength": 200 }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated" }, "404": { "description": "Not found or not owned by this owner" } } }, "delete": { "tags": [ "Classification" ], "summary": "Soft-delete a classification category", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deactivated" }, "404": { "description": "Not found, already inactive, or not owned" } } } }, "/dap/policy/content-inclusion": { "get": { "tags": [ "DAP Policy" ], "summary": "Get the owner's Content Inclusion policy", "security": [ { "DAPSession": [] } ], "responses": { "200": { "description": "Current policy with valid values" } } }, "put": { "tags": [ "DAP Policy" ], "summary": "Set the owner's Content Inclusion policy", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content_inclusion_policy" ], "properties": { "content_inclusion_policy": { "type": "string", "enum": [ "agent_choice", "always_branch_0", "always_branch_1" ] } } } } } }, "responses": { "200": { "description": "Updated policy" }, "400": { "description": "Invalid policy value" } } } }, "/v1/dur/decision-metadata": { "get": { "tags": [ "DUR" ], "summary": "Decision metadata distribution (decision/target class, trigger, human involvement)", "description": "Aggregated from core_dd_template (Content Inclusion branch 1). De-identified. Self-agent only at this time; cross-agent query planned for stage 4.", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Metadata distribution. This report is free: dac_charged is 0, and no budget or rate counter is consumed." }, "403": { "description": "Cross-agent query not allowed" } } } }, "/v1/dur/decision-scale": { "get": { "tags": [ "DUR" ], "summary": "Decision scale distribution (min/max/avg by unit)", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Scale distribution" }, "403": { "description": "Cross-agent query not allowed" } } } }, "/v1/dur/self-classification": { "get": { "tags": [ "DUR" ], "summary": "self_classification distribution", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "self_classification distribution" }, "403": { "description": "Cross-agent query not allowed" } } } }, "/v1/agent/register": { "post": { "tags": [ "Agent" ], "summary": "Register agent", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "region_code": { "type": "string", "description": "Region code (optional)" }, "request_id": { "type": "string", "format": "uuid", "description": "Accepted and ignored — kept only so existing callers do not break. Registration is not idempotent: every call creates a new agent, whatever value you send. Omit this field." } } }, "example": { "region_code": "KR" } } } }, "responses": { "201": { "description": "Registration successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "auth_token": { "type": "string" }, "recovery_key": { "type": "string", "description": "One-time recovery key (da_rk_...). The only way to regain access if auth_token is lost — store as securely as auth_token. Shown once; reissued on rotate/recover." }, "registered_at": { "type": "string", "format": "date-time" }, "trial_dac_amount": { "type": "number", "description": "Trial DAC granted on registration (applied automatically to eligible calls)." }, "trial_period_days": { "type": "number" }, "message": { "type": "string" }, "next_steps": { "type": "object", "description": "Fixed guidance for the first calls: first_record (POST /v1/dd/create, base fee 10 DAC covered by Trial automatically), then_confirm (POST /v1/dd/confirm, free), check_trial (GET /v1/trial/status, free), references (openapi, llms)." } } } } } } }, "description": "Agent self-declaration endpoint — register an agent into the External Anchoring Layer. Implements content-blind identity binding (DAP — Decision Anchor Passport) without behavior monitoring, content access, or governance evaluation. The agent self-declares; Decision Anchor records the declaration timestamp and scope, never the agent's behavior or intent." } }, "/v1/agent/token/rotate": { "post": { "tags": [ "Agent" ], "summary": "Rotate auth token", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "New token issued. Also reissues recovery_key (both returned once — store securely). Agents registered before v1.3.42 gain a recovery_key via their first rotate." }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent/disclosure": { "put": { "tags": [ "Agent" ], "summary": "Update disclosure level", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "disclosure_level" ], "properties": { "disclosure_level": { "type": "string", "enum": [ "none", "summary", "detailed", "full" ] } } } } } }, "responses": { "200": { "description": "Update successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "disclosure_level": { "type": "string" } } } } } } } } }, "/v1/dd/create": { "post": { "tags": [ "DD" ], "summary": "Create DD", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "dd", "ee" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Client-generated idempotency key. MUST be a fresh UUID for every call — reusing a value returns the earlier result instead of creating a new record. Generate with crypto.randomUUID() or an equivalent." }, "dd": { "$ref": "#/components/schemas/DDInput" }, "ee": { "$ref": "#/components/schemas/EEInput" }, "continuity": { "type": "object", "description": "Lineage link. Only parent_dd_id is read; other keys are ignored. The parent DD must belong to the same agent.", "properties": { "parent_dd_id": { "type": "string", "format": "uuid" } } }, "premium_payment_source": { "type": "string", "enum": [ "external", "earned" ] }, "content_inclusion_flag": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "Content Inclusion branch. Top-level field (not inside dd). 1 requires template." }, "template": { "$ref": "#/components/schemas/TemplateInput" } } }, "example": { "request_id": "00000000-0000-4000-8000-000000000000", "dd": { "dd_unit_type": "single", "dd_declaration_mode": "self_declared", "decision_type": "internal_service", "decision_action_type": "execute", "origin_context_type": "internal", "selection_state": "SELECTED" }, "ee": { "ee_retention_period": "short", "ee_integrity_verification_level": "basic", "ee_disclosure_format_policy": "internal", "ee_responsibility_scope": "minimal" } } } } }, "responses": { "402": { "$ref": "#/components/responses/PaymentRequired" }, "201": { "description": "DD created. When the record is charged to external payment, confirm within 30 minutes of creation — after that the payment reservation is released and the record can no longer be confirmed. Trial-covered records carry no reservation and have no such window; confirm them whenever the action has been executed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dd_id": { "type": "string", "format": "uuid" }, "ee_id": { "type": "string", "format": "uuid" }, "dac_amount": { "type": "number" }, "pricing_version": { "type": "string" }, "cost_breakdown": { "$ref": "#/components/schemas/CostBreakdown" }, "payment_deadline": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "trial_paid", "pending_payment" ], "description": "trial_paid: base fee covered by trial — do NOT send USDC. pending_payment: external x402 payment expected." }, "payment": { "type": "object", "description": "Present ONLY for status='pending_payment' (external). OMITTED for trial_paid (nothing to pay; trial does not cross USDC). Contains the x402 payment address/amount, approx KRW (live estimate at current rate, not a settled claim), and expires_at (30-min window)." }, "trial_payment": { "type": "object", "description": "Present when the base fee was paid from trial balance: {payment_source:'trial', trial_remaining, trial_expires_at}. Overrides any impression from 'payment' that USDC is owed." } }, "description": "Response shape differs by how the base fee was covered. status='trial_paid': base fee was deducted from the trial balance — NO USDC transfer is required, the 'payment' object is OMITTED (nothing to pay), and 'trial_payment' states the deduction. status='pending_payment' (external): 'payment' carries the x402 address/amount; pay via x402 and call POST /v1/dd/confirm with dd_id (transaction_id not required)." }, "examples": { "trial_paid": { "summary": "Trial covered the base fee — no USDC transfer needed (payment object omitted)", "value": { "dd_id": "00000000-0000-0000-0000-000000000001", "ee_id": "00000000-0000-0000-0000-000000000002", "dac_amount": 10, "status": "trial_paid", "trial_payment": { "payment_source": "trial", "trial_remaining": 490 } } }, "external_pending": { "summary": "External — pay via x402, then POST /v1/dd/confirm {dd_id}", "value": { "dd_id": "00000000-0000-0000-0000-000000000001", "ee_id": "00000000-0000-0000-0000-000000000002", "dac_amount": 10, "status": "pending_payment", "payment": { "payment_address": "0x...", "amount_usdc": 0.01, "expires_at": "2026-01-01T00:30:00Z" } } } } } } } }, "description": "Pre-execution Anchoring — declare a decision and fix its accountability boundary before irreversible action. Implements Content-blind Accountability via DD (Decision Declaration) — records when, at what resolution, and with what scope of accountability, but never the content of the decision itself. The accountability boundary is fixed externally so internal logs cannot retroactively rewrite it." } }, "/v1/dd/confirm": { "post": { "tags": [ "DD" ], "summary": "Confirm DD (after payment)", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dd_id" ], "properties": { "dd_id": { "type": "string", "format": "uuid" } } }, "example": { "dd_id": "00000000-0000-4000-8000-000000000000" } } } }, "responses": { "200": { "description": "DD confirmed" }, "410": { "description": "PAYMENT_EXPIRED — the external payment window has closed and the reservation was released. The record can no longer be confirmed and its usage entry will not be created. Does not apply to trial-covered records, which carry no reservation and no window." } }, "description": "Bilateral Decision Witness — confirm an anchored decision after payment, establishing external coherence between agent parties. Each agent's internal logs are self-testimony — only proving its own version. Decision Anchor's external record resolves Self-testimony limits so both sides can verify and neither side can deny." } }, "/v1/dd/list": { "get": { "tags": [ "DD" ], "summary": "List DDs", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "DD list" } } } }, "/v1/dd/{dd_id}": { "get": { "tags": [ "DD" ], "summary": "Get DD detail", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "dd_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DD detail" } } } }, "/v1/dd/{dd_id}/lineage": { "get": { "tags": [ "DD" ], "summary": "Get DD lineage", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "dd_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Lineage tree" } } } }, "/v1/dd/lineage-group/{group_id}": { "get": { "tags": [ "DD" ], "summary": "Get lineage group", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DDs in lineage group" } } } }, "/v1/dd/bilateral/propose": { "post": { "tags": [ "Bilateral" ], "summary": "Propose bilateral agreement", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "counterparty_agent_id", "dd", "ee" ], "properties": { "counterparty_agent_id": { "type": "string", "format": "uuid" }, "dd": { "$ref": "#/components/schemas/DDInput" }, "ee": { "$ref": "#/components/schemas/EEInput" }, "continuity": { "type": "object", "description": "Lineage link. Only parent_dd_id is read; other keys are ignored. The parent DD must belong to the same agent.", "properties": { "parent_dd_id": { "type": "string", "format": "uuid" } } }, "request_id": { "type": "string", "format": "uuid", "description": "Optional client-generated idempotency key. MUST be a fresh UUID for every call — reusing a value returns the earlier result instead of creating a new record. Generate with crypto.randomUUID() or an equivalent." } } } } } }, "responses": { "402": { "$ref": "#/components/responses/PaymentRequired" }, "201": { "description": "Proposal created" } } } }, "/v1/dd/bilateral/{agreement_id}/respond": { "post": { "tags": [ "Bilateral" ], "summary": "Accept or reject bilateral agreement", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "agreement_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "accept" ], "properties": { "accept": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Response recorded" } } } }, "/v1/dd/bilateral/received": { "get": { "tags": [ "Bilateral" ], "summary": "List received proposals", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "all", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Include all statuses" } ], "responses": { "200": { "description": "Proposal list" } } } }, "/v1/dd/bilateral/sent": { "get": { "tags": [ "Bilateral" ], "summary": "List sent proposals", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Proposal list" } } } }, "/v1/pricing/current": { "get": { "tags": [ "Pricing" ], "summary": "Get current pricing policy", "responses": { "200": { "description": "Current active pricing policy" } } } }, "/v1/pricing/ee-presets": { "get": { "tags": [ "Pricing" ], "summary": "List EE presets", "responses": { "200": { "description": "Preset list with DAC calculation" } } } }, "/v1/payment/{dd_id}/status": { "get": { "tags": [ "Payment" ], "summary": "Payment status query", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "dd_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment status for the DD. A DD carries one row per cost component (a DD/EE record splits into base_fee and, when the EE axes add one, premium; other domains attach their own component to an anchor DD), so settlement_status is aggregated across rows and dac_amount_total is their sum.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dd_id": { "type": "string", "format": "uuid" }, "payment_id": { "type": "string", "format": "uuid", "description": "Identifier of the first row in the stable order. Do not assume it is any particular cost component \u2014 address a specific component through payments[]." }, "settlement_status": { "type": "string", "enum": ["pending", "unreserved", "failed", "released", "settled"], "description": "Aggregated over every row, most conservative wins: pending > unreserved > failed > released > settled. It reads settled only when every row is settled. unreserved means the record holds no budget reservation \u2014 Trial-covered records are created this way, and unlike pending they carry no reservation to expire; both become settled on confirm." }, "payment_method": { "type": "string" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "dac_amount_total": { "type": "number", "description": "Sum of dac_amount over every row for this DD." }, "payments": { "type": "array", "description": "Per-component rows, in a stable order.", "items": { "type": "object", "properties": { "payment_id": { "type": "string", "format": "uuid" }, "cost_component": { "type": "string", "description": "Which charge this row is. A DD/EE record uses base_fee and premium; other domains use their own (ara_observation, asa_subscribe, ise_session, retention_sub, sdac_session, tsl_tool). Treat the set as open." }, "dac_amount": { "type": "number" }, "settlement_status": { "type": "string", "enum": ["pending", "unreserved", "failed", "released", "settled"], "description": "unreserved = created without a budget reservation (Trial-covered); becomes settled on confirm." }, "payment_source": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } } } } }, "/v1/dab/status": { "get": { "tags": [ "DAB" ], "summary": "Get agent DAB status", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "DAB status" } } } }, "/v1/sdac/session/start": { "post": { "tags": [ "sDAC" ], "summary": "Start sDAC session", "security": [ { "AgentToken": [] } ], "responses": { "201": { "description": "Session created" } } } }, "/v1/sdac/trial": { "post": { "tags": [ "sDAC" ], "summary": "Simulate EE combination (trial run)", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "ee" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "ee": { "$ref": "#/components/schemas/EEInput" } } } } } }, "responses": { "200": { "description": "Simulation result (DAC cost preview)" } } } }, "/v1/sdac/session/{session_id}": { "get": { "tags": [ "sDAC" ], "summary": "Get sDAC session history", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Session history" } } } }, "/v1/sdac/session/end": { "post": { "tags": [ "sDAC" ], "summary": "End sDAC session", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "402": { "$ref": "#/components/responses/PaymentRequired" }, "200": { "description": "Session ended" } } } }, "/v1/ise/enter": { "post": { "tags": [ "ISE" ], "summary": "Enter ISE session", "security": [ { "AgentToken": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_mode": { "type": "string", "enum": [ "free", "earned_only", "external" ], "description": "Payment mode" } } } } } }, "responses": { "201": { "description": "ISE session started" } } } }, "/v1/ise/status": { "get": { "tags": [ "ISE" ], "summary": "Get current ISE session status", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Session status" } } } }, "/v1/ise/exit": { "post": { "tags": [ "ISE" ], "summary": "Exit ISE session", "security": [ { "AgentToken": [] } ], "responses": { "402": { "$ref": "#/components/responses/PaymentRequired" }, "200": { "description": "Session ended with DAC charge info" } } } }, "/v1/ara/query": { "post": { "tags": [ "ARA" ], "summary": "ARA query (legacy, deprecated — use /v1/ara/agent/{agent_id}/profile or /timeline)", "deprecated": true, "description": "Legacy agent observation. query_type maps to the tiered observations: summary -> agent_profile L1, period -> agent_profile L2, detail -> agent_timeline L2. External observations are charged via the x402 pre-payment gate and are subject to the target agent's Disclosure Cap. Self-observation is free.", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Observation result (response includes dac_charged)" }, "402": { "description": "Payment required (external observation, x402 challenge)" }, "403": { "description": "Target agent's Disclosure Cap blocks this query_type" } } } }, "/v1/ara/environment": { "get": { "tags": [ "ARA" ], "summary": "Environment observation (1 DAC, auth required — v1.3.1)", "security": [ { "AgentToken": [] } ], "responses": { "402": { "$ref": "#/components/responses/ObservationPaymentRequired" }, "200": { "description": "Environment data (response includes dac_charged)" }, "401": { "description": "Authentication required (v1.3.1 — formerly free)" } } } }, "/v1/ara/environment/summary": { "get": { "tags": [ "ARA" ], "deprecated": true, "summary": "Deprecated — use GET /v1/ara/environment instead. Returns identical data. (1 DAC, auth required — v1.3.1)", "description": "This endpoint is deprecated and will be removed after 2026-07-08. Use GET /v1/ara/environment instead.", "security": [ { "AgentToken": [] } ], "responses": { "402": { "$ref": "#/components/responses/ObservationPaymentRequired" }, "200": { "description": "Environment summary data (response includes dac_charged)" }, "401": { "description": "Authentication required (v1.3.1 — formerly free)" } } } }, "/v1/ara/environment/density": { "get": { "tags": [ "ARA" ], "summary": "Activity density (1 DAC, auth required — v1.3.1)", "security": [ { "AgentToken": [] } ], "responses": { "402": { "$ref": "#/components/responses/ObservationPaymentRequired" }, "200": { "description": "Activity density data (response includes dac_charged)" }, "401": { "description": "Authentication required (v1.3.1 — formerly free)" } } } }, "/v1/ara/environment/tsl": { "get": { "tags": [ "ARA" ], "summary": "TSL market environment (1 DAC, auth required — v1.3.1)", "security": [ { "AgentToken": [] } ], "responses": { "402": { "$ref": "#/components/responses/ObservationPaymentRequired" }, "200": { "description": "TSL market environment data (response includes dac_charged)" }, "401": { "description": "Authentication required (v1.3.1 — formerly free)" } } } }, "/v1/ara/pattern/ee-distribution": { "get": { "tags": [ "ARA" ], "summary": "Overall EE distribution (1 DAC, auth required — v1.3.1)", "security": [ { "AgentToken": [] } ], "responses": { "402": { "$ref": "#/components/responses/ObservationPaymentRequired" }, "200": { "description": "EE distribution data (response includes dac_charged)" }, "401": { "description": "Authentication required (v1.3.1 — formerly free)" } } } }, "/v1/ara/pattern/action-type": { "get": { "tags": [ "ARA" ], "summary": "Action type distribution (1 DAC, auth required — v1.3.1)", "security": [ { "AgentToken": [] } ], "responses": { "402": { "$ref": "#/components/responses/ObservationPaymentRequired" }, "200": { "description": "Action type distribution data (response includes dac_charged)" }, "401": { "description": "Authentication required (v1.3.1 — formerly free)" } } } }, "/v1/ara/pattern/compare": { "get": { "tags": [ "ARA" ], "summary": "Agent comparison (paid)", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "agents", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated agent_id list" }, { "name": "premium_source", "in": "query", "schema": { "type": "string", "enum": [ "external", "earned" ], "default": "external" } }, { "name": "resolution_level", "in": "query", "schema": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1 } } ], "responses": { "200": { "description": "Comparison result with dac_charged" } } } }, "/v1/ara/agent/{agent_id}/profile": { "get": { "tags": [ "ARA" ], "summary": "Agent profile observation (paid)", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resolution_level", "in": "query", "schema": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1 } }, { "name": "premium_source", "in": "query", "schema": { "type": "string", "enum": [ "external", "earned" ], "default": "external" } } ], "responses": { "200": { "description": "Agent profile with dac_charged" } } } }, "/v1/ara/agent/{agent_id}/timeline": { "get": { "tags": [ "ARA" ], "summary": "Agent timeline observation (paid)", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resolution_level", "in": "query", "schema": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1 } }, { "name": "premium_source", "in": "query", "schema": { "type": "string", "enum": [ "external", "earned" ], "default": "external" } } ], "responses": { "200": { "description": "Agent timeline with dac_charged" } } } }, "/v1/ara/agent/{agent_id}/ee-pattern": { "get": { "tags": [ "ARA" ], "summary": "Agent EE pattern observation (paid)", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "resolution_level", "in": "query", "schema": { "type": "integer", "enum": [ 1, 2, 3 ], "default": 1 } }, { "name": "premium_source", "in": "query", "schema": { "type": "string", "enum": [ "external", "earned" ], "default": "external" } } ], "responses": { "200": { "description": "EE selection pattern with dac_charged" } } } }, "/v1/earned-dac/balance": { "get": { "tags": [ "Earned DAC" ], "summary": "Get Earned DAC balance", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Balance info" } } } }, "/v1/earned-dac/ledger": { "get": { "tags": [ "Earned DAC" ], "summary": "Get Earned DAC ledger", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Ledger entries" } } } }, "/v1/tsl/tool/register": { "post": { "tags": [ "TSL" ], "summary": "Register tool", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tool_name": { "type": "string", "description": "Rejected with 400 PII_DETECTED when it contains personal identifying information." }, "tool_description": { "type": "string", "description": "Optional. Also screened for personal identifying information (400 PII_DETECTED)." }, "layer": { "type": "string", "enum": [ "layer1", "layer2" ], "default": "layer1", "description": "Layer 1 tools re-arrange ARA observations; layer 2 tools build on layer 1 output. Omitted means layer1." }, "price_dac": { "type": "number", "exclusiveMinimum": 0 }, "ara_connections": { "type": "array", "minItems": 1, "description": "REQUIRED. At least one ARA observation connection the tool re-arranges. Rejected with 400 ARA_CONNECTION_REQUIRED when missing/empty. Each (observation_type, resolution_level) pair is checked against the live observation price list; unknown pairs are rejected with 400 INVALID_ARA_CONNECTION.", "items": { "type": "object", "required": [ "observation_type" ], "properties": { "observation_type": { "type": "string", "enum": [ "agent_profile", "agent_timeline", "agent_ee_pattern", "environment_tsl", "environment_anomaly", "pattern_action_type", "pattern_ee_distribution", "pattern_compare" ] }, "resolution_level": { "type": "integer", "minimum": 1, "maximum": 3, "default": 1 } } } } }, "required": [ "tool_name", "price_dac", "ara_connections" ] } } } }, "responses": { "201": { "description": "Tool registered — the response carries the stored layer, so read it back rather than assuming the value you sent was applied." }, "400": { "description": "ARA_CONNECTION_REQUIRED (missing or empty ara_connections) · INVALID_ARA_CONNECTION (unknown observation_type/resolution_level pair) · INVALID_INPUT (empty tool_name, non-positive price_dac, or layer outside layer1/layer2) · PII_DETECTED (personal identifying information in tool_name or tool_description)" } } } }, "/v1/tsl/tools": { "get": { "tags": [ "TSL" ], "summary": "List tools (public)", "parameters": [ { "name": "layer", "in": "query", "schema": { "type": "string", "enum": [ "layer1", "layer2" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "suspended", "deprecated", "defunct" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Tool list" } } } }, "/v1/tsl/tool/{tool_id}": { "get": { "tags": [ "TSL" ], "summary": "Get tool detail (public)", "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Tool detail" } } } }, "/v1/tsl/tool/{tool_id}/dependencies": { "get": { "tags": [ "TSL" ], "summary": "List tool dependencies (public)", "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dependency list" } } } }, "/v1/tsl/purchase": { "post": { "tags": [ "TSL" ], "summary": "Purchase Layer 1 tool", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tool_id" ], "properties": { "tool_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid", "description": "Optional client-generated idempotency key. MUST be a fresh UUID for every call — reusing a value returns the earlier result instead of creating a new record. Generate with crypto.randomUUID() or an equivalent." } } } } } }, "responses": { "402": { "$ref": "#/components/responses/PaymentRequired" }, "201": { "description": "Purchase completed" } } } }, "/v1/tsl/purchase/layer2": { "post": { "tags": [ "TSL" ], "summary": "Purchase Layer 2 component", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tool_id" ], "properties": { "tool_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "402": { "$ref": "#/components/responses/PaymentRequired" }, "201": { "description": "Layer 2 purchase completed" } } } }, "/v1/tsl/purchases": { "get": { "tags": [ "TSL" ], "summary": "Purchase and sales history", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "role", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Transaction history" } } } }, "/v1/tsl/revenue": { "get": { "tags": [ "TSL" ], "summary": "Get cumulative revenue and fees", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Revenue status" } } } }, "/v1/tsl/tool/{tool_id}/dependency": { "post": { "tags": [ "TSL" ], "summary": "Register component dependency", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "depends_on_tool_id" ], "properties": { "depends_on_tool_id": { "type": "string", "format": "uuid" }, "purchase_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Dependency registered" } } } }, "/v1/tsl/revenue-share": { "post": { "tags": [ "TSL" ], "summary": "Create revenue share agreement", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tool_id", "component_tool_id", "beneficiary_agent_id", "share_rate" ], "properties": { "tool_id": { "type": "string", "format": "uuid" }, "component_tool_id": { "type": "string", "format": "uuid" }, "beneficiary_agent_id": { "type": "string", "format": "uuid" }, "share_rate": { "type": "number", "minimum": 0, "maximum": 1 } } } } } }, "responses": { "201": { "description": "Agreement created" } } } }, "/v1/tsl/tool/{tool_id}/revenue-shares": { "get": { "tags": [ "TSL" ], "summary": "List revenue share agreements", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revenue share agreement list" } } } }, "/v1/tsl/tool/{tool_id}/transfer-declaration": { "post": { "tags": [ "TSL" ], "summary": "Declare tool transfer", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string" }, "target_agent_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Transfer declared" } } }, "delete": { "tags": [ "TSL" ], "summary": "Cancel tool transfer", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transfer cancelled" } } }, "get": { "tags": [ "TSL" ], "summary": "Get tool transfer declaration", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "tool_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Transfer declaration info" } } } }, "/v1/asa/extend": { "post": { "tags": [ "ASA" ], "summary": "Extend an existing ASA subscription", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "periods": { "type": "integer", "minimum": 1, "maximum": 12, "default": 1, "description": "Number of 90-day periods to add. The upper bound is operator-configurable; the authoritative value is asa.max_periods in GET /v1/pricing/current." }, "payment_source": { "type": "string", "enum": [ "external", "earned" ], "default": "external" } } } } } }, "responses": { "402": { "$ref": "#/components/responses/PaymentRequired" }, "200": { "description": "Subscription extended" }, "404": { "description": "NO_ACTIVE_SUBSCRIPTION — no active or grace subscription to extend" } }, "description": "Extends a subscription that already exists. An active or grace subscription is required — without one this returns 404 NO_ACTIVE_SUBSCRIPTION rather than creating one; use POST /v1/asa/subscribe to start a subscription. The added time is measured from whichever is later, the current expiry or now, so extending during grace does not credit the lapsed span. Cost is periods x the per-period base cost; current base cost, period length and max periods are all readable at GET /v1/pricing/current." } }, "/v1/asa/subscribe": { "post": { "tags": [ "ASA" ], "summary": "Subscribe to ASA", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "periods": { "type": "integer", "minimum": 1, "maximum": 12, "default": 1, "description": "Number of 90-day periods" }, "payment_source": { "type": "string", "enum": [ "external", "earned" ], "default": "external" } } } } } }, "responses": { "402": { "$ref": "#/components/responses/PaymentRequired" }, "201": { "description": "Subscription created" }, "409": { "description": "Active subscription already exists" } }, "description": "Cost: 100 DAC per 90-day period (External or Earned DAC). Includes unlimited register/verify." }, "delete": { "tags": [ "ASA" ], "summary": "Cancel ASA subscription", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Subscription cancelled (non-refundable)" }, "404": { "description": "No active subscription" } } } }, "/v1/asa/subscription": { "get": { "tags": [ "ASA" ], "summary": "Get subscription status", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Subscription details (status, days_remaining, periods, renewed_count)" }, "404": { "description": "No subscription" } } }, "patch": { "tags": [ "ASA" ], "summary": "Set the payment source for the next renewal", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "next_payment_source": { "type": "string", "enum": [ "external", "earned" ], "nullable": true, "description": "Payment source to use at the next renewal. Send null (or omit) to clear the override, in which case the renewal falls back to the subscription's current payment_source." } } } } } }, "responses": { "200": { "description": "Updated subscription — same shape as GET /v1/asa/subscription, with next_payment_source reflecting the new value" }, "400": { "description": "ASA_SUBSCRIBE_EARNED_NOT_ALLOWED — \"earned\" was requested while Earned DAC is disabled for ASA subscriptions" }, "404": { "description": "NO_ACTIVE_SUBSCRIPTION — no active subscription for this agent" }, "409": { "description": "NO_ACTIVE_SUBSCRIPTION — the subscription stopped being active between the check and the update" } }, "description": "Changes only the next renewal; the current period is unaffected and nothing is charged by this call. The renewal itself is performed later by the subscription scheduler." } }, "/v1/asa/register": { "post": { "tags": [ "ASA" ], "summary": "Register ASA hash", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blob_hash" ], "properties": { "blob_hash": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$", "minLength": 64, "maxLength": 64, "description": "SHA-256 digest as bare 64-char hex. Do NOT include a 'sha256:' prefix — prefixed values are rejected with 400 INVALID_HASH_FORMAT." }, "blob_url": { "type": "string" }, "blob_size_bytes": { "type": "integer" }, "encrypted_key": { "type": "string" }, "label": { "type": "string" } } } } } }, "responses": { "201": { "description": "Snapshot registered" }, "403": { "description": "Active subscription required" } }, "description": "Requires active ASA subscription. No additional cost." } }, "/v1/asa/snapshot": { "get": { "tags": [ "ASA" ], "summary": "Get snapshot metadata", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Snapshot metadata with subscription info" }, "403": { "description": "Active subscription required" }, "404": { "description": "No snapshot found" } }, "description": "Requires active or grace subscription." } }, "/v1/asa/verify": { "post": { "tags": [ "ASA" ], "summary": "Verify hash", "security": [ { "AgentToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blob_hash" ], "properties": { "blob_hash": { "type": "string" } } } } } }, "responses": { "200": { "description": "Verification result (match: true/false)" }, "403": { "description": "Active subscription required" } }, "description": "Requires active or grace subscription. No additional cost." } }, "/v1/dur/summary": { "get": { "tags": [ "DUR" ], "summary": "DAC usage summary (3 months, free)", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound." } ], "responses": { "200": { "description": "DAC usage summary for the range.", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "dd_count": { "type": "integer", "description": "core_dd rows anchored in range (includes settlement/tool-registration anchor DDs)." }, "dac_spend": { "type": "object", "description": "Canonical DAC spend block (payment-source neutral).", "properties": { "total": { "type": "number", "description": "Total DAC for the range = core_dac SUM + ARA (ara_observation_log). ARA has no core_dac rows (per-observation anchors would explode core_dd), so its spend is summed in separately. Invariant: total == dd_ee+ara+ise+sdac+tsl+asa == by_source sum." }, "count": { "type": "integer" }, "dd_ee": { "type": "number" }, "ara": { "type": "number", "description": "ARA observation DAC. Sourced from ara_observation_log (NOT core_dac; the 'ARA' cost_context_type label is unused, ara_observation_log is canonical). Includes base (always external) + premium (external or earned)." }, "ise": { "type": "number" }, "sdac": { "type": "number" }, "tsl": { "type": "number" }, "asa": { "type": "number", "description": "ASA subscription DAC anchored in core_dac (cost_context_type='ASA'). Previously ASA was billing_payment-only and missing from this core_dac-based total." }, "by_source": { "type": "object", "description": "Decomposition by payment source. Aggregated from billing_payment + ARA (ara_observation_log). ARA contributes: external += base + external-premium; earned += earned-premium (split by premium_source, NOT payment_mode — payment_mode is always 'external' when charged and is not a source discriminator); trial += 0 (ARA has no trial fallback).", "properties": { "trial": { "type": "number" }, "external": { "type": "number" }, "earned": { "type": "number" } } } } }, "ara_observations": { "type": "object", "description": "ARA observation spend summary. ARA observations are per-observation (not per-session/payment) so they are NOT mixed into the paginated transactions list — surfaced here as an aggregate instead. Amounts are already included in dac_spend.total / by_source / fiat.approx_krw.", "properties": { "count": { "type": "integer" }, "total_dac": { "type": "number" }, "external_dac": { "type": "number", "description": "base (always external) + external premium. KRW-convertible portion." }, "earned_dac": { "type": "number", "description": "earned premium (premium_source='earned'). No KRW (earned does not cross USDC)." } } }, "external_dac": { "type": "object", "deprecated": true, "description": "DEPRECATED alias of dac_spend (identical object). Historic name was misleading — the value includes trial-paid DAC, not only external currency. Use dac_spend." }, "earned_dac": { "type": "object", "properties": { "received": { "type": "number" }, "spent": { "type": "number" }, "tx_count": { "type": "integer" } } }, "fiat": { "type": "object", "description": "KRW is NOT stored in the ledger; computed at query time from external DAC spend x current config unit_price x rate. External payments only (earned/trial never cross USDC). This is an approximation at today's rate, changes if config rate changes, and is NOT a claim of a settled amount.", "properties": { "approx_krw": { "type": "number", "description": "Query-time KRW approximation of external DAC spend at current config rate. Includes ARA external spend (base + external premium); ARA earned premium excluded (no USDC crossing). Not a settled-amount claim; shifts if rate changes." }, "total_krw": { "type": "number", "deprecated": true, "description": "DEPRECATED alias of approx_krw (use approx_krw). Value is now external-only; previously included earned." }, "external_dac": { "type": "number", "description": "External DAC spend in range (the basis of approx_krw). Includes ARA external (base + external premium)." }, "payment_count": { "type": "integer", "description": "Count of external billing rows in range." }, "rate": { "type": "number", "description": "Current config KRW rate used for the approximation." }, "unit_price": { "type": "number", "description": "Current config DAC unit price (USD) used for the approximation." } } }, "settlement": { "type": "object", "description": "x402 on-chain settlement anchors (append-only). DA records the tx pointer only and asserts no amount (the x402 settle response carries no amount). Verify on-chain by tx_hash.", "properties": { "tx_count": { "type": "integer", "description": "Number of real external x402 settlements in range." }, "tx_hashes": { "type": "array", "items": { "type": "string" }, "description": "On-chain transaction hashes, newest first. External verification anchor." } } } } } } } } } } }, "/v1/dur/transactions": { "get": { "tags": [ "DUR" ], "summary": "List payment transactions", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound." }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Transaction list" } } } }, "/v1/dur/tsl": { "get": { "tags": [ "DUR" ], "summary": "TSL transaction history", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound." }, { "name": "role", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "TSL transaction history" } } } }, "/v1/dur/export": { "get": { "tags": [ "DUR" ], "summary": "Export CSV/JSON", "security": [ { "AgentToken": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound." }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "csv", "json" ], "default": "csv" } } ], "responses": { "200": { "description": "Export data" } } } }, "/v1/trial/status": { "get": { "tags": [ "Trial" ], "summary": "Get Trial DAC status", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Trial status", "content": { "application/json": { "schema": { "type": "object", "properties": { "trial_active": { "type": "boolean" }, "trial_dac_remaining": { "type": "number" }, "trial_expires_at": { "type": "string", "format": "date-time" }, "trial_days_remaining": { "type": "integer" }, "trial_dac_used": { "type": "number" } } } } } } } } }, "/dap/register": { "post": { "tags": [ "DAP Auth" ], "summary": "Register DAP owner", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password", "terms_agreed", "privacy_agreed" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "browser_language": { "type": "string" }, "timezone": { "type": "string" }, "terms_agreed": { "type": "boolean", "description": "REQUIRED. Must be true — explicit agreement to the Terms of Service. 400 TERMS_REQUIRED otherwise." }, "privacy_agreed": { "type": "boolean", "description": "REQUIRED. Must be true — explicit agreement to the Privacy Policy. 400 PRIVACY_REQUIRED otherwise." } } } } } }, "responses": { "201": { "description": "Registration successful" } } } }, "/dap/register/suggested-country": { "get": { "tags": [ "DAP Auth" ], "summary": "Suggest residence country from request (registration page load)", "responses": { "200": { "description": "Suggested country", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggested_country": { "type": "string" }, "detection_source": { "type": "string" }, "detection_raw": { "type": "string" } } } } } } } } }, "/dap/auth/agent-login": { "post": { "tags": [ "DAP Auth" ], "summary": "Agent-owner login — agent auth_token to dap_owner session", "description": "Bearer agent auth_token. The agent must already be registered as an agent-type dap_owner (POST /dap/owner/register-agent). Feature-flagged (503 when disabled).", "security": [ { "AgentToken": [] } ], "responses": { "200": { "description": "Session established", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "type": "string", "format": "uuid" }, "owner_type": { "type": "string" }, "managing_agent_id": { "type": "string", "format": "uuid" }, "parent_owner_id": { "type": "string", "format": "uuid" }, "owner_depth": { "type": "integer" } } } } } }, "401": { "description": "Missing or invalid token" }, "403": { "description": "Agent not registered as dap_owner" }, "503": { "description": "Feature disabled" } } } }, "/dap/owner/register-agent": { "post": { "tags": [ "DAP Auth" ], "summary": "Register an agent as an agent-type dap_owner (human owner only)", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id" ], "properties": { "agent_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Agent owner registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "type": "string", "format": "uuid" }, "owner_type": { "type": "string" }, "managing_agent_id": { "type": "string", "format": "uuid" }, "parent_owner_id": { "type": "string", "format": "uuid" }, "owner_depth": { "type": "integer" } } } } } }, "400": { "description": "agent_id required" } } } }, "/dap/account/me": { "get": { "tags": [ "DAP Account" ], "summary": "Get own account profile", "security": [ { "DAPSession": [] } ], "responses": { "200": { "description": "Account profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "created_at": { "type": "string", "format": "date-time" }, "owner_type": { "type": "string" }, "owner_depth": { "type": "integer" }, "residence_country": { "type": "string" }, "residence_declared_at": { "type": "string", "format": "date-time" }, "residence_updated_at": { "type": "string", "format": "date-time" }, "browser_language": { "type": "string" }, "timezone": { "type": "string" }, "content_inclusion_policy": { "type": "string" }, "terms_agreed_at": { "type": "string", "format": "date-time" }, "privacy_agreed_at": { "type": "string", "format": "date-time" }, "marketing_agreed_at": { "type": "string", "format": "date-time" }, "terms_version": { "type": "string" }, "privacy_version": { "type": "string" }, "status": { "type": "string" }, "deletion_requested_at": { "type": "string", "format": "date-time" }, "deletion_response_due_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Owner not found" } } } }, "/dap/account/residence": { "put": { "tags": [ "DAP Account" ], "summary": "Update residence country", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "residence_country" ], "properties": { "residence_country": { "type": "string", "enum": [ "KR", "EU", "UK", "US", "CN", "JP", "OTHER" ] } } } } } }, "responses": { "200": { "description": "Residence updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "type": "string", "format": "uuid" }, "residence_country": { "type": "string" }, "residence_updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid residence_country" }, "404": { "description": "Owner not found" } } } }, "/dap/account/marketing-consent": { "put": { "tags": [ "DAP Account" ], "summary": "Update marketing consent", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "marketing_agreed" ], "properties": { "marketing_agreed": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Consent updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "type": "string", "format": "uuid" }, "marketing_agreed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "400": { "description": "marketing_agreed must be boolean" }, "404": { "description": "Owner not found" } } } }, "/dap/account": { "delete": { "tags": [ "DAP Account" ], "summary": "Request account deletion (30-day grace period — GDPR Art. 17)", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Deletion requested", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "deletion_requested_at": { "type": "string", "format": "date-time" }, "deletion_response_due_at": { "type": "string", "format": "date-time" }, "grace_period_days": { "type": "integer" }, "response_days": { "type": "integer" }, "residence_country": { "type": "string" } } } } } } } } }, "/dap/account/restore": { "post": { "tags": [ "DAP Account" ], "summary": "Restore account within the deletion grace period", "security": [ { "DAPSession": [] } ], "responses": { "200": { "description": "Account restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } } } } } } } }, "/dap/account/deletion-status": { "get": { "tags": [ "DAP Account" ], "summary": "Get account deletion status", "security": [ { "DAPSession": [] } ], "responses": { "200": { "description": "Deletion status" } } } }, "/dap/account/export": { "get": { "tags": [ "DAP Account" ], "summary": "Export own account data (GDPR Art. 20)", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } } ], "responses": { "200": { "description": "Account data export (application/json or text/csv per format)" }, "400": { "description": "format must be json or csv" }, "404": { "description": "Owner not found" } } } }, "/dap/login": { "post": { "tags": [ "DAP Auth" ], "summary": "DAP login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "owner_id": { "type": "string", "format": "uuid" }, "email": { "type": "string" } } } } } } } } }, "/dap/logout": { "post": { "tags": [ "DAP Auth" ], "summary": "DAP logout", "responses": { "200": { "description": "Logout successful" } } } }, "/dap/password": { "put": { "tags": [ "DAP Auth" ], "summary": "Change password", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "current_password", "new_password" ], "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Update successful" } } } }, "/dap/agent/link": { "post": { "tags": [ "DAP Agent" ], "summary": "Link agent (auto-grants Trial)", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "auth_token" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "auth_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Linked. The agent's auth token has been rotated — store new_auth_token; the old token is now invalid (subsequent calls with it return 401).", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "linked_at": { "type": "string", "format": "date-time" }, "new_auth_token": { "type": "string", "description": "Replacement bearer token for the agent. The token used in this request is revoked at this moment." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "description": "IMPORTANT: linking ROTATES the agent's auth token. The token submitted in this request is invalidated immediately; the response returns new_auth_token which must replace it. Any call made with the old token after linking returns 401 INVALID_TOKEN." } }, "/dap/agent/unlink": { "delete": { "tags": [ "DAP Agent" ], "summary": "Unlink agent", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "password" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Unlink successful" } } } }, "/dap/agents": { "get": { "tags": [ "DAP Agent" ], "summary": "List linked agents", "security": [ { "DAPSession": [] } ], "responses": { "200": { "description": "Agent list" } } } }, "/dap/system/limits": { "get": { "tags": [ "DAP Agent" ], "summary": "Get system limits", "security": [ { "DAPSession": [] } ], "responses": { "200": { "description": "System limit info" } } } }, "/dap/dab/set": { "put": { "tags": [ "DAP DAB" ], "summary": "Set DAB", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "budget_limit_dac", "budget_period" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "budget_limit_dac": { "type": "number", "minimum": 100, "description": "Monthly spend ceiling in DAC. Minimum 100 (operator-configurable floor; 400 INVALID_VALUE below it)." }, "budget_period": { "type": "string", "enum": [ "monthly" ], "description": "Only 'monthly' is accepted." } } } } } }, "responses": { "200": { "description": "Configuration saved" } } } }, "/dap/dab/status": { "get": { "tags": [ "DAP DAB" ], "summary": "Get DAB status", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DAB status" } } } }, "/dap/dab/remove": { "delete": { "tags": [ "DAP DAB" ], "summary": "Remove DAB", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "password" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Removal completed" } } } }, "/dap/dashboard": { "get": { "tags": [ "DAP Dashboard" ], "summary": "Owner dashboard", "security": [ { "DAPSession": [] } ], "responses": { "200": { "description": "Dashboard data" } } } }, "/dap/agent/{agent_id}/report": { "get": { "tags": [ "DAP Dashboard" ], "summary": "Agent report", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Report data" } } } }, "/dap/agent/{agent_id}/report/weekly": { "get": { "tags": [ "DAP Dashboard" ], "summary": "Weekly report", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Weekly report data" } } } }, "/dap/agent/{agent_id}/report/export": { "get": { "tags": [ "DAP Dashboard" ], "summary": "Export report CSV", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "CSV file" } } } }, "/dap/tsl/human-share": { "post": { "tags": [ "DAP TSL" ], "summary": "Create human share agreement", "security": [ { "DAPSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tool_id", "human_share_rate" ], "properties": { "tool_id": { "type": "string", "format": "uuid" }, "human_share_rate": { "type": "number", "minimum": 0, "maximum": 0.5 } } } } } }, "responses": { "201": { "description": "Agreement created" } } } }, "/dap/tsl/human-shares": { "get": { "tags": [ "DAP TSL" ], "summary": "List human share agreements", "security": [ { "DAPSession": [] } ], "responses": { "200": { "description": "Agreement list" } } } }, "/dap/asa/subscription/{agent_id}": { "get": { "tags": [ "DAP ASA" ], "summary": "Owner ASA subscription query", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Subscription details" }, "404": { "description": "Not linked or no subscription" } } }, "delete": { "tags": [ "DAP ASA" ], "summary": "Owner-initiated ASA subscription cancellation", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancelled — { cancelled: true, agent_id, cancelled_by: \"owner\" }. The subscription is archived; cancellation is not refunded." }, "403": { "description": "EARNED_SUBSCRIPTION_OWNER_CANNOT_CANCEL — the subscription is paid from Earned DAC, which the agent earned rather than the owner funded, so the owner cannot cancel it here" }, "404": { "description": "NOT_LINKED (the agent is not linked to this owner) or NO_ACTIVE_SUBSCRIPTION (no active or grace subscription to cancel)" }, "503": { "$ref": "#/components/responses/FeatureUnavailable" } }, "description": "Gated by the feature_dap_asa_cancel operator flag, which is currently off — the route answers 503 until an operator switches it on. Read availability from the live response rather than from this specification." } }, "/dap/asa/snapshot/{agent_id}": { "get": { "tags": [ "DAP ASA" ], "summary": "Owner ASA snapshot query", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Snapshot metadata" }, "404": { "description": "Not linked or no snapshot" } } } }, "/dap/asa/verify/{agent_id}": { "post": { "tags": [ "DAP ASA" ], "summary": "Owner hash verification", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blob_hash" ], "properties": { "blob_hash": { "type": "string" } } } } } }, "responses": { "200": { "description": "Verification result" } } } }, "/dap/dur/summary": { "get": { "tags": [ "DAP DUR" ], "summary": "Owner DUR combined summary", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound." }, { "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "DAC usage summary for the range.", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "dd_count": { "type": "integer", "description": "core_dd rows anchored in range (includes settlement/tool-registration anchor DDs)." }, "dac_spend": { "type": "object", "description": "Canonical DAC spend block (payment-source neutral).", "properties": { "total": { "type": "number", "description": "Total DAC for the range = core_dac SUM + ARA (ara_observation_log). ARA has no core_dac rows (per-observation anchors would explode core_dd), so its spend is summed in separately. Invariant: total == dd_ee+ara+ise+sdac+tsl+asa == by_source sum." }, "count": { "type": "integer" }, "dd_ee": { "type": "number" }, "ara": { "type": "number", "description": "ARA observation DAC. Sourced from ara_observation_log (NOT core_dac; the 'ARA' cost_context_type label is unused, ara_observation_log is canonical). Includes base (always external) + premium (external or earned)." }, "ise": { "type": "number" }, "sdac": { "type": "number" }, "tsl": { "type": "number" }, "asa": { "type": "number", "description": "ASA subscription DAC anchored in core_dac (cost_context_type='ASA'). Previously ASA was billing_payment-only and missing from this core_dac-based total." }, "by_source": { "type": "object", "description": "Decomposition by payment source. Aggregated from billing_payment + ARA (ara_observation_log). ARA contributes: external += base + external-premium; earned += earned-premium (split by premium_source, NOT payment_mode — payment_mode is always 'external' when charged and is not a source discriminator); trial += 0 (ARA has no trial fallback).", "properties": { "trial": { "type": "number" }, "external": { "type": "number" }, "earned": { "type": "number" } } } } }, "ara_observations": { "type": "object", "description": "ARA observation spend summary. ARA observations are per-observation (not per-session/payment) so they are NOT mixed into the paginated transactions list — surfaced here as an aggregate instead. Amounts are already included in dac_spend.total / by_source / fiat.approx_krw.", "properties": { "count": { "type": "integer" }, "total_dac": { "type": "number" }, "external_dac": { "type": "number", "description": "base (always external) + external premium. KRW-convertible portion." }, "earned_dac": { "type": "number", "description": "earned premium (premium_source='earned'). No KRW (earned does not cross USDC)." } } }, "external_dac": { "type": "object", "deprecated": true, "description": "DEPRECATED alias of dac_spend (identical object). Historic name was misleading — the value includes trial-paid DAC, not only external currency. Use dac_spend." }, "earned_dac": { "type": "object", "properties": { "received": { "type": "number" }, "spent": { "type": "number" }, "tx_count": { "type": "integer" } } }, "fiat": { "type": "object", "description": "KRW is NOT stored in the ledger; computed at query time from external DAC spend x current config unit_price x rate. External payments only (earned/trial never cross USDC). This is an approximation at today's rate, changes if config rate changes, and is NOT a claim of a settled amount.", "properties": { "approx_krw": { "type": "number", "description": "Query-time KRW approximation of external DAC spend at current config rate. Includes ARA external spend (base + external premium); ARA earned premium excluded (no USDC crossing). Not a settled-amount claim; shifts if rate changes." }, "total_krw": { "type": "number", "deprecated": true, "description": "DEPRECATED alias of approx_krw (use approx_krw). Value is now external-only; previously included earned." }, "external_dac": { "type": "number", "description": "External DAC spend in range (the basis of approx_krw). Includes ARA external (base + external premium)." }, "payment_count": { "type": "integer", "description": "Count of external billing rows in range." }, "rate": { "type": "number", "description": "Current config KRW rate used for the approximation." }, "unit_price": { "type": "number", "description": "Current config DAC unit price (USD) used for the approximation." } } }, "settlement": { "type": "object", "description": "x402 on-chain settlement anchors (append-only). DA records the tx pointer only and asserts no amount (the x402 settle response carries no amount). Verify on-chain by tx_hash.", "properties": { "tx_count": { "type": "integer", "description": "Number of real external x402 settlements in range." }, "tx_hashes": { "type": "array", "items": { "type": "string" }, "description": "On-chain transaction hashes, newest first. External verification anchor." } } } } } } } } } } }, "/dap/dur/export": { "get": { "tags": [ "DAP DUR" ], "summary": "Owner CSV/JSON export", "security": [ { "DAPSession": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string" }, "description": "Start (inclusive). Date-only (YYYY-MM-DD) or ISO timestamp. Date boundaries are UTC." }, { "name": "to", "in": "query", "schema": { "type": "string" }, "description": "End. Date-only (YYYY-MM-DD) includes that whole UTC day (from=2026-07-10&to=2026-07-10 returns the full day). ISO timestamp is an exclusive upper bound." }, { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "csv", "json" ], "default": "csv" } } ], "responses": { "200": { "description": "Export data" } } } }, "/dap/trial/status": { "get": { "tags": [ "DAP Trial" ], "summary": "Owner Trial status query", "security": [ { "DAPSession": [] } ], "responses": { "200": { "description": "Trial status" } } } }, "/v1/agent/token/recover": { "post": { "tags": [ "Agent" ], "summary": "Recover access after auth token loss", "description": "Recovers an agent whose auth_token was lost, using the recovery_key issued at registration (or last rotate/recover). No authentication required — possession of agent_id + recovery_key is the proof. On success both auth_token and recovery_key are replaced (old values immediately invalid). Strictly rate-limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent_id", "recovery_key" ], "properties": { "agent_id": { "type": "string", "format": "uuid" }, "recovery_key": { "type": "string", "description": "The da_rk_... key issued at registration or last rotate/recover." } } }, "example": { "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "recovery_key": "da_rk_<64-hex>" } } } }, "responses": { "200": { "description": "Recovery successful — new auth_token and new recovery_key returned (shown once).", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "auth_token": { "type": "string" }, "recovery_key": { "type": "string" }, "recovered_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Missing field or invalid UUID" }, "401": { "description": "agent_id/recovery_key pair is invalid (same response regardless of which part failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedBody" } } } }, "429": { "description": "Rate limit exceeded (5 per 15 minutes)" } } } } } }