{"openapi":"3.1.0","info":{"title":"MagicPay API","version":"1.1.0","description":"MagicPay is a workflow payment and Memory-request platform for autonomous agents. The public model centers on workflow sessions, Memory catalog/materialization, Memory items, requests, trust rules, and request artifacts. Agents typically integrate through `fetchMemoryCatalog`, `materializeMemoryValues`, `client.memoryItems.*`, `client.memory.*`, and `actions.run`; curated public docs intentionally omit legacy secret-chain endpoints from the product narrative.\n\nRecommended reading order:\n1. `GET /health`\n2. `GET /agent/me`\n3. `POST /sessions`\n4. `GET /sessions/{id}`\n5. `GET /sessions/{id}/memory-catalog`\n6. `POST /sessions/{id}/memory-materializations`\n7. `POST /sessions/{id}/requests`\n8. `POST /sessions/{id}/requests/{requestId}/decisions`\n9. `POST /sessions/{id}/requests/{requestId}/claim`\n10. `POST /sessions/{id}/complete`\n11. `POST /observability/telemetry/traces`"},"components":{"schemas":{"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok"],"description":"Static health status for the API deployment.","example":"ok"}},"required":["status"],"description":"Public health check response."},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable error code.","example":"unauthorized"},"message":{"type":"string","description":"Safe client-facing message. For machine-only states, callers should branch on error, error_code, status, category, and reason instead of parsing this text.","example":"Invalid API key."},"violated_limit":{"type":"string","description":"Limit key returned by policy engine when spending limit is exceeded.","example":"daily_limit"},"current_spend":{"type":"number","description":"Current spend value at the moment the request was blocked.","example":124.5},"limit_value":{"type":"number","description":"Configured spend limit that was violated.","example":100},"provider":{"type":"string","description":"Upstream provider identifier when relevant.","example":"openrouter"},"retry_after":{"type":"number","description":"Retry-after interval in seconds when returned by an upstream provider.","example":30},"error_code":{"type":"string","description":"Structured upstream/provider-specific subcode when available.","example":"structured_output_truncated"},"diagnostic_id":{"type":"string","description":"Opaque support correlation id for matching a client error to backend logs.","example":"mpdiag_550e8400e29b41d4a716446655440000"},"status":{"type":"string","description":"Machine-readable state for structured blocked or availability responses.","example":"authorization_required"},"category":{"type":"string","description":"Structured resource category when the error belongs to one resource family.","example":"payment_card"},"reason":{"type":"string","description":"Machine-readable reason for the structured state.","example":"payment_authorization_required"},"finish_reason":{"type":"string","description":"Provider finish reason when relevant to the failure.","example":"length"},"completion_tokens":{"type":"number","description":"Completion token count captured for provider truncation failures.","example":1024},"max_output_tokens":{"type":"number","description":"Configured max output token limit for provider truncation failures.","example":1024}},"required":["error","message"],"description":"Standard error envelope returned by MagicPay API.","example":{"error":"limit_exceeded","message":"Spending limit exceeded.","violated_limit":"daily_limit","current_spend":124.5,"limit_value":100}},"AgentResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Canonical agent identifier.","example":"bc6a74cb-6ee7-49f2-a91e-0f5eaa6f3b8d"},"name":{"type":"string","description":"Human-readable agent name.","example":"Finance Automation Agent"},"description":{"type":"string","nullable":true,"description":"Optional operator-facing description of the agent purpose.","example":"Handles recurring SaaS and infra payments."},"status":{"type":"string","description":"Current agent lifecycle status.","example":"active"},"budget_limit":{"type":"number","nullable":true,"description":"Optional overall budget limit configured for the agent.","example":1000},"daily_limit":{"type":"number","nullable":true,"description":"Optional daily spend limit configured for the agent.","example":100},"transaction_limit":{"type":"number","nullable":true,"description":"Optional per-operation transaction limit configured for the agent.","example":50},"created_at":{"type":"string","description":"Creation timestamp.","example":"2026-02-20T10:00:00.000Z"},"stats":{"type":"object","nullable":true,"properties":{"monthly_spend":{"type":"number","description":"Current month spend attributed to this agent.","example":312.45},"payment_operation_count_month":{"type":"number","description":"Number of payment operations created by this agent in the current month.","example":16},"active_subscriptions":{"type":"number","description":"Count of active subscription-style payment operations linked to this agent.","example":4},"avg_risk_score":{"type":"number","description":"Average normalized risk score across recent payment operations.","example":0.18}},"required":["monthly_spend","payment_operation_count_month","active_subscriptions","avg_risk_score"],"description":"Aggregated recent statistics for the authenticated agent."}},"required":["id","name","description","status","budget_limit","daily_limit","transaction_limit","created_at","stats"],"description":"Authenticated agent profile and aggregated stats."},"ChatCompletionUsage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","minimum":0,"example":512},"completion_tokens":{"type":"integer","minimum":0,"example":97},"total_tokens":{"type":"integer","minimum":0,"example":609},"reasoning_tokens":{"type":"integer","minimum":0,"example":0},"cached_input_tokens":{"type":"integer","minimum":0,"example":0}},"required":["prompt_tokens","completion_tokens","total_tokens"],"description":"Normalized token usage returned by the MagicPay LLM gateway."},"ChatCompletionResponse":{"type":"object","properties":{"id":{"type":"string","description":"MagicPay-generated chat completion identifier.","example":"chatcmpl_magicpay_123"},"object":{"type":"string","enum":["chat.completion"],"example":"chat.completion"},"created":{"type":"integer","minimum":0,"description":"Unix timestamp in seconds.","example":1743286400},"model":{"type":"string","minLength":1,"description":"Normalized public backend catalog model key used for the request.","example":"magicpay/medium"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"example":0},"message":{"type":"object","properties":{"role":{"type":"string","enum":["assistant"],"example":"assistant"},"content":{"type":"string","description":"Assistant response content.","example":"{\"elements\":[{\"elementId\":\"1-42\",\"description\":\"Buy button\",\"method\":\"click\",\"arguments\":[]}]}"}},"required":["role","content"],"additionalProperties":false},"finish_reason":{"type":"string","description":"OpenAI-compatible finish reason.","example":"stop"}},"required":["index","message","finish_reason"],"additionalProperties":false},"description":"Single completion choice returned by MagicPay."},"usage":{"$ref":"#/components/schemas/ChatCompletionUsage"}},"required":["id","object","created","model","choices","usage"],"description":"OpenAI-compatible chat completion response returned by MagicPay."},"ChatCompletionRequest":{"type":"object","properties":{"model":{"type":"string","minLength":1,"description":"Public backend catalog model key or alias. The response echoes the normalized catalog model key.","example":"magicpay/medium"},"messages":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"role":{"type":"string","enum":["system","user"],"description":"Chat message role.","example":"user"},"content":{"anyOf":[{"type":"string","minLength":1,"description":"String content for simple chat messages.","example":"Find actionable elements on this page."},{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string","minLength":1,"description":"Plain text content block.","example":"Find the active checkout form."}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["image_url"]},"image_url":{"type":"object","properties":{"url":{"type":"string","minLength":1,"description":"Inline image data URL.","example":"data:image/jpeg;base64,/9j/4AAQSk..."},"detail":{"type":"string","enum":["auto","low","high"],"description":"Optional OpenAI-compatible image detail hint.","example":"auto"}},"required":["url"],"additionalProperties":false}},"required":["type","image_url"],"additionalProperties":false}]},"minItems":1,"description":"Rich multimodal content array."}]}},"required":["role","content"],"additionalProperties":false},{"type":"object","properties":{"role":{"type":"string","enum":["assistant"],"description":"Assistant message role.","example":"assistant"},"content":{"anyOf":[{"type":"string","description":"Assistant text content. May be empty when tool_calls are present.","example":""},{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string","minLength":1,"description":"Plain text content block.","example":"Find the active checkout form."}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["image_url"]},"image_url":{"type":"object","properties":{"url":{"type":"string","minLength":1,"description":"Inline image data URL.","example":"data:image/jpeg;base64,/9j/4AAQSk..."},"detail":{"type":"string","enum":["auto","low","high"],"description":"Optional OpenAI-compatible image detail hint.","example":"auto"}},"required":["url"],"additionalProperties":false}},"required":["type","image_url"],"additionalProperties":false}]},"minItems":1,"description":"Rich multimodal assistant content array."}]},"tool_calls":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Provider tool call identifier.","example":"call_123"},"type":{"type":"string","enum":["function"],"description":"OpenAI-compatible tool call type.","example":"function"},"function":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Function/tool name.","example":"click_element"},"arguments":{"type":"string","description":"JSON string containing function arguments.","example":"{\"index\":1}"}},"required":["name","arguments"],"additionalProperties":false}},"required":["id","type","function"],"additionalProperties":false},"minItems":1,"description":"OpenAI-compatible assistant tool calls from earlier turns."}},"required":["role","content"],"additionalProperties":false},{"type":"object","properties":{"role":{"type":"string","enum":["tool"],"description":"OpenAI-compatible tool result role.","example":"tool"},"content":{"type":"string","minLength":1,"description":"Tool result content.","example":"Clicked destination field."},"tool_call_id":{"type":"string","minLength":1,"description":"Tool call id being answered.","example":"call_123"}},"required":["role","content","tool_call_id"],"additionalProperties":false}],"description":"OpenAI-compatible chat message, including tool-call history."},"minItems":1,"description":"OpenAI-compatible chat messages."},"response_format":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["json_schema"]},"json_schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"Structured response schema name.","example":"Observation"},"strict":{"type":"boolean","description":"OpenAI-compatible strict mode flag.","example":true},"schema":{"nullable":true,"description":"JSON Schema describing the required structured output.","example":{"type":"object","properties":{"elements":{"type":"array","items":{"type":"object"}}},"required":["elements"]}}},"required":["name"],"additionalProperties":false}},"required":["type","json_schema"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["json_object"]}},"required":["type"],"additionalProperties":false}],"description":"Optional structured output mode."},"temperature":{"type":"number","minimum":0,"maximum":2,"description":"Optional sampling temperature.","example":0.1},"max_completion_tokens":{"type":"integer","minimum":32,"maximum":10000,"description":"Optional output token ceiling. Backend may clamp it.","example":1024}},"required":["model","messages"],"additionalProperties":false,"description":"OpenAI-compatible chat completion request subset supported by MagicPay.","example":{"model":"magicpay","messages":[{"role":"system","content":"Return only valid JSON."},{"role":"user","content":"Find actionable elements."}],"response_format":{"type":"json_schema","json_schema":{"name":"Observation","strict":true,"schema":{"type":"object","properties":{"elements":{"type":"array","items":{"type":"object"}}},"required":["elements"]}}},"temperature":0.1,"max_completion_tokens":1024}},"CaptchaTaskCreateResponse":{"type":"object","properties":{"provider":{"type":"string","example":"capsolver"},"task_id":{"type":"string","example":"task-123456"},"status":{"type":"string","enum":["pending"],"example":"pending"}},"required":["provider","task_id","status"],"description":"Created captcha task metadata."},"CaptchaTaskProxy":{"type":"object","properties":{"server":{"type":"string","minLength":1,"description":"Proxy server URL or host:port used by the browser session.","example":"http://proxy.example:8080"},"username":{"type":"string","minLength":1,"description":"Proxy username for basic auth, when required.","example":"demo-user"},"password":{"type":"string","minLength":1,"description":"Proxy password for basic auth, when required.","example":"demo-pass"}},"required":["server"],"description":"Exact proxy used by the browser session when the solver must share the same outward IP."},"CaptchaTaskCreateRequest":{"type":"object","properties":{"type":{"type":"string","enum":["recaptcha-v2","hcaptcha","turnstile"],"description":"CAPTCHA type observed on checkout page.","example":"hcaptcha"},"site_key":{"type":"string","minLength":1,"description":"Site key extracted from captcha widget.","example":"10000000-ffff-ffff-ffff-000000000001"},"page_url":{"type":"string","format":"uri","description":"Page URL where captcha challenge is shown.","example":"https://checkout.example.com/pay"},"action":{"type":"string","minLength":1,"description":"Cloudflare Turnstile challenge action, when required by the provider.","example":"managed"},"data":{"type":"string","minLength":1,"description":"Cloudflare Turnstile challenge cData payload.","example":"cdata-123"},"pagedata":{"type":"string","minLength":1,"description":"Cloudflare Turnstile challenge chlPageData payload.","example":"pagedata-456"},"user_agent":{"type":"string","minLength":1,"description":"Current browser User-Agent required by some challenge-mode captcha providers.","example":"Mozilla/5.0 Challenge Browser"},"proxy":{"$ref":"#/components/schemas/CaptchaTaskProxy"}},"required":["type","site_key","page_url"],"description":"Create captcha solving task via backend gateway."},"CaptchaTaskStatusResponse":{"type":"object","properties":{"provider":{"type":"string","example":"capsolver"},"task_id":{"type":"string","example":"task-123456"},"status":{"type":"string","enum":["pending","ready","failed"],"description":"Current status of captcha task.","example":"ready"},"token":{"type":"string","description":"Captcha token when status=ready.","example":"03AFcWeA7..."},"user_agent":{"type":"string","description":"User-Agent returned by the solver for challenge-mode captchas.","example":"Mozilla/5.0 Solver Browser"},"error":{"type":"string","description":"Provider error when status=failed.","example":"CAPTCHA solve timeout"}},"required":["provider","task_id","status"],"description":"Captcha task polling result."},"MagicSearchQueryResponse":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"source":{"type":"string","enum":["provider_index","exa","search_fallback"]},"searchProvider":{"type":"string","nullable":true,"enum":["exa","duckduckgo"]},"title":{"type":"string","nullable":true},"query":{"type":"string"},"confidence":{"type":"string","enum":["high","medium","low"]},"provider":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"methodId":{"type":"string","nullable":true},"methodType":{"type":"string","nullable":true},"confidence":{"type":"string","enum":["high","medium","low","none"]}},"required":["id","name","methodId","methodType","confidence"]},"fallbackReason":{"type":"string","enum":["no_provider_match","provider_url_unavailable","provider_catalog_unavailable","missing_exa_api_key","exa_timeout","exa_unavailable","exa_no_results"]},"choices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"url":{"type":"string","nullable":true,"format":"uri"},"price":{"nullable":true},"images":{"type":"array","items":{"nullable":true}},"characteristics":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"raw":{"nullable":true}},"required":["id","title"]}},"choiceRecommended":{"type":"boolean"},"choiceRecommendationReason":{"type":"string","nullable":true,"enum":["policy_never","policy_always","not_enough_choices","auto_not_choice_intent","search_alternatives_choice_intent","provider_candidates_close"]},"choiceVertical":{"type":"string","nullable":true,"enum":["flight","hotel"]}},"required":["url","source","title","query","confidence","provider","choiceRecommended","choiceRecommendationReason"]},"MagicSearchQueryBody":{"type":"object","properties":{"query":{"type":"string","minLength":1},"hints":{"type":"object","properties":{"merchantHint":{"type":"string","minLength":1},"domainHint":{"type":"string","minLength":1},"productHint":{"type":"string","minLength":1},"category":{"type":"string","minLength":1},"country":{"type":"string","minLength":1},"region":{"type":"string","minLength":1},"placeHint":{"type":"string","minLength":1}}},"providerQuery":{"type":"object","nullable":true,"properties":{"rawPrompt":{"type":"string","nullable":true,"minLength":1},"intentType":{"type":"string","nullable":true,"minLength":1},"merchantHint":{"type":"string","nullable":true,"minLength":1},"domainHint":{"type":"string","nullable":true,"minLength":1},"productHint":{"type":"string","nullable":true,"minLength":1},"category":{"type":"string","nullable":true,"minLength":1},"geo":{"type":"object","nullable":true,"properties":{"mode":{"type":"string","nullable":true},"coordinates":{"type":"object","nullable":true,"properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"]},"radiusMeters":{"type":"number","nullable":true},"placeHint":{"type":"string","nullable":true,"minLength":1}}},"fulfillmentMode":{"type":"string","nullable":true,"minLength":1},"checkoutShape":{"type":"string","nullable":true,"minLength":1},"quoteRequirements":{"type":"array","items":{"type":"string","minLength":1}},"authContext":{"type":"array","items":{"type":"string","minLength":1}},"region":{"type":"string","nullable":true,"minLength":1},"country":{"type":"string","nullable":true,"minLength":1},"preferredMethodTypes":{"type":"array","items":{"type":"string","enum":["x402","mcp","api","reversed_api","browser"]}}}},"purpose":{"type":"string","enum":["checkout","provider","product"]},"choicePolicy":{"type":"string","enum":["never","auto","always"]},"choiceLimit":{"type":"integer","minimum":2,"maximum":8}},"required":["query"]},"SessionJsonRecord":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Arbitrary JSON object stored without additional schema validation."},"Session":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["in_progress","waiting_for_user","error","canceled","completed"]},"type":{"type":"string","enum":["payment","subscription","cancellation"]},"method":{"type":"string","nullable":true,"enum":["card","crypto","x402"]},"amount_total":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"merchant_name":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"current_request_id":{"type":"string","nullable":true,"format":"uuid"},"last_event_seq":{"type":"integer","minimum":0},"phase":{"type":"string","nullable":true,"enum":["clarification","provider_search","provider_selection","method_selection","execution_preparation","execution","post_execution","completed"]},"phase_metadata":{"$ref":"#/components/schemas/SessionJsonRecord"},"commerce_provider_id":{"type":"string","nullable":true},"commerce_method_key":{"type":"string","nullable":true},"commerce_method_type":{"type":"string","nullable":true,"enum":["x402","mcp","api","reversed_api","browser"]},"commerce_provider_name":{"type":"string","nullable":true},"commerce_selection":{"$ref":"#/components/schemas/SessionJsonRecord"},"commerce_execution_metadata":{"$ref":"#/components/schemas/SessionJsonRecord"},"error_code":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"context":{"$ref":"#/components/schemas/SessionJsonRecord"},"metadata":{"$ref":"#/components/schemas/SessionJsonRecord"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","agent_id","status","type","method","amount_total","currency","merchant_name","description","current_request_id","last_event_seq","error_code","error_message","context","metadata","created_at","updated_at","completed_at"]},"SessionCurrentRequest":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","example":"data","description":"Canonical request kind for the active workflow-session request. Public integrations should reason in terms of data, action, captcha, alert, or other request categories rather than legacy shadow values."},"status":{"type":"string","enum":["pending","fulfilled","denied","expired","failed","canceled"]},"blocking":{"type":"boolean"},"title":{"type":"string"},"summary":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","type","status","blocking","title","summary","created_at","updated_at","expires_at"]},"SessionBrowserBinding":{"type":"object","nullable":true,"properties":{"session_id":{"type":"string","minLength":1,"description":"Stable browser instance identifier when the workflow session is bound to a live browser runtime.","example":"browser_123"}},"required":["session_id"],"additionalProperties":false,"description":"Optional browser binding for sessions attached to a live browser runtime."},"SessionEnvelope":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/Session"},"current_request":{"$ref":"#/components/schemas/SessionCurrentRequest"},"browser":{"$ref":"#/components/schemas/SessionBrowserBinding"}},"required":["session","current_request","browser"]},"SessionPage":{"type":"object","properties":{"ref":{"type":"string","minLength":1,"description":"CLI page ref from the local runtime graph.","example":"p0"},"url":{"type":"string","format":"uri","description":"Current page URL.","example":"https://example.com/checkout"},"title":{"type":"string","minLength":1,"description":"Current page title when available.","example":"Checkout"}}},"SessionRun":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Optional caller-side run id for local runtime correlation.","example":"run_123"},"started_at":{"type":"string","format":"date-time","description":"ISO timestamp when the local run started.","example":"2026-03-26T09:00:00.000Z"},"ended_at":{"type":"string","format":"date-time","description":"ISO timestamp when the local run ended, if already known.","example":"2026-03-26T09:15:00.000Z"},"source":{"type":"string","enum":["cli","test","replay"],"default":"cli","description":"Run producer source when the caller tracks local runtime lineage."},"status":{"type":"string","enum":["running","completed","failed","aborted"],"description":"Current run status if the caller already knows it.","example":"running"},"profile":{"type":"string","minLength":1,"description":"Named browser profile when a browser runtime is active.","example":"default"},"site_host":{"type":"string","minLength":1,"description":"Best-effort host summary for the current target site or API origin.","example":"example.com"},"protected_run":{"type":"boolean","description":"Whether the run is currently flagged as sensitive.","example":false}},"required":["id","started_at"],"additionalProperties":false},"SessionStep":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Optional caller-side step id for local runtime correlation.","example":"step_start_session_1"},"ordinal":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Step ordinal inside the local run.","example":1},"command":{"type":"string","minLength":1,"description":"CLI command that produced this step.","example":"start-session"},"started_at":{"type":"string","format":"date-time","description":"ISO timestamp when the local step started.","example":"2026-03-26T09:00:00.000Z"},"ended_at":{"type":"string","format":"date-time","description":"ISO timestamp when the local step ended, if already known.","example":"2026-03-26T09:00:01.000Z"},"success":{"type":"boolean","description":"Final command result when the step is already completed.","example":true},"outcome_type":{"type":"string","minLength":1,"description":"Short machine-readable outcome category.","example":"workflow_session_started"},"message":{"type":"string","minLength":1,"description":"Human-readable summary of the command result.","example":"Workflow session started."},"reason":{"type":"string","minLength":1,"description":"Optional longer error or blocking reason.","example":"A new workflow session was started on the same browser session."},"page_ref":{"type":"string","minLength":1,"description":"Current page ref at the time of the step.","example":"p0"},"target_ref":{"type":"string","minLength":1,"description":"Target ref when the step acts on a specific target.","example":"t0"},"surface_ref":{"type":"string","minLength":1,"description":"Surface ref when the step acts on a surface.","example":"s0"},"fill_ref":{"type":"string","minLength":1,"description":"Fill ref when the step is related to a fill action.","example":"fill_123"},"before_snapshot_id":{"type":"string","minLength":1,"description":"Before snapshot id captured locally, if any.","example":"snap_before_1"},"after_snapshot_id":{"type":"string","minLength":1,"description":"After snapshot id captured locally, if any.","example":"snap_after_1"},"event_count":{"type":"integer","minimum":0,"description":"Count of local child events captured for this step.","example":2},"child_span_count":{"type":"integer","minimum":0,"description":"Count of child spans linked to this step.","example":0},"protected_step":{"type":"boolean","description":"Whether the step is marked as sensitive.","example":false}},"required":["id","ordinal","command","started_at"],"additionalProperties":false},"CreateSessionBrowser":{"type":"object","properties":{"session_id":{"type":"string","minLength":1,"description":"Stable browser instance identifier returned by the browser runtime.","example":"browser_123"},"entry_command":{"type":"string","enum":["start-session"],"description":"Optional browser-runtime start marker for runtimes that track command provenance."},"page":{"$ref":"#/components/schemas/SessionPage"},"run":{"$ref":"#/components/schemas/SessionRun"},"step":{"$ref":"#/components/schemas/SessionStep"}},"required":["session_id"],"additionalProperties":false,"description":"Optional browser binding and runtime metadata for browser-driven sessions."},"SessionTelemetryEnvelope":{"type":"object","properties":{"root_trace":{"nullable":true,"description":"Root OTLP traces payload in the same structure the local CLI exports."},"step_trace":{"nullable":true,"description":"Step OTLP traces payload in the same structure the local CLI exports."}},"additionalProperties":false},"CreateSessionBody":{"type":"object","properties":{"agent_id":{"type":"string","format":"uuid","description":"Explicit agent id when the caller is authenticated with a signed-in user session instead of an agent-scoped API key.","example":"550e8400-e29b-41d4-a716-446655440000"},"browser":{"$ref":"#/components/schemas/CreateSessionBrowser"},"type":{"type":"string","enum":["payment","subscription","cancellation"],"default":"payment"},"method":{"type":"string","nullable":true,"enum":["card","crypto","x402"]},"amount_total":{"type":"number","nullable":true,"minimum":0,"description":"Optional current amount estimate.","example":19.99},"currency":{"type":"string","nullable":true,"minLength":3,"maxLength":3,"description":"Currency code if amount is already known.","example":"USD"},"merchant_name":{"type":"string","nullable":true,"minLength":1,"description":"Merchant or target service name if already known.","example":"OpenAI"},"description":{"type":"string","nullable":true,"minLength":1,"description":"Operator-facing session description.","example":"Checkout flow for API usage renewal"},"phase":{"type":"string","nullable":true,"enum":["clarification","provider_search","provider_selection","method_selection","execution_preparation","execution","post_execution","completed"],"description":"Optional payment-agent phase for staged orchestration flows such as clarification or provider search.","example":"clarification"},"phase_metadata":{"allOf":[{"$ref":"#/components/schemas/SessionJsonRecord"},{"description":"Optional structured phase details such as missing clarification fields or provider-search candidates."}]},"commerce_provider_id":{"type":"string","nullable":true,"minLength":1,"description":"Optional selected provider id when a curated commerce provider is already known.","example":"openai.chatgpt_plus.monthly"},"commerce_method_key":{"type":"string","nullable":true,"minLength":1,"description":"Optional selected provider method key for staged execution flows.","example":"browser-checkout"},"commerce_method_type":{"type":"string","nullable":true,"enum":["x402","mcp","api","reversed_api","browser"],"description":"Optional selected provider method type for staged execution flows.","example":"browser"},"commerce_provider_name":{"type":"string","nullable":true,"minLength":1,"description":"Optional selected provider display name.","example":"openai"},"commerce_selection":{"allOf":[{"$ref":"#/components/schemas/SessionJsonRecord"},{"description":"Optional structured selection details for the chosen provider or method."}]},"commerce_execution_metadata":{"allOf":[{"$ref":"#/components/schemas/SessionJsonRecord"},{"description":"Optional structured execution metadata for staged or mock commerce execution."}]},"context":{"$ref":"#/components/schemas/SessionJsonRecord"},"metadata":{"$ref":"#/components/schemas/SessionJsonRecord"},"telemetry":{"$ref":"#/components/schemas/SessionTelemetryEnvelope"}},"additionalProperties":false},"SessionEvent":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"sequence_no":{"type":"integer","minimum":0,"exclusiveMinimum":true},"type":{"type":"string","enum":["state","observe","reflect","action","error"]},"actor":{"type":"string"},"summary":{"type":"string"},"payload":{"$ref":"#/components/schemas/SessionJsonRecord"},"created_at":{"type":"string","format":"date-time"}},"required":["id","sequence_no","type","actor","summary","payload","created_at"]},"SessionEventResponse":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/Session"},"current_request":{"$ref":"#/components/schemas/SessionCurrentRequest"},"browser":{"$ref":"#/components/schemas/SessionBrowserBinding"},"event":{"$ref":"#/components/schemas/SessionEvent"},"duplicate":{"type":"boolean","description":"Whether this was an idempotent replay of an already ingested event.","example":false}},"required":["session","current_request","browser","event","duplicate"]},"SessionTerminalRun":{"allOf":[{"$ref":"#/components/schemas/SessionRun"},{"type":"object","properties":{"status":{"type":"string","enum":["completed","failed","aborted"],"description":"Final local run status for this workflow session.","example":"completed"}},"required":["status"],"additionalProperties":false}]},"CompleteSessionBrowser":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/SessionPage"},"run":{"$ref":"#/components/schemas/SessionTerminalRun"},"step":{"$ref":"#/components/schemas/SessionStep"}},"additionalProperties":false},"CompleteSessionBody":{"type":"object","properties":{"client_completion_id":{"type":"string","minLength":1,"description":"Idempotency key for one logical workflow-session completion attempt.","example":"complete_session_1"},"status":{"type":"string","enum":["completed","canceled","error"],"description":"Terminal workflow-session status requested by the CLI.","example":"completed"},"command":{"type":"string","minLength":1,"description":"CLI command that triggered this terminal transition.","example":"end-session"},"summary":{"type":"string","minLength":1,"description":"Human-readable terminal session summary.","example":"Workflow session completed."},"timestamp":{"type":"string","format":"date-time","description":"When the terminal transition happened on the CLI side.","example":"2026-03-26T09:15:00.000Z"},"details":{"$ref":"#/components/schemas/SessionJsonRecord"},"telemetry":{"$ref":"#/components/schemas/SessionTelemetryEnvelope"},"browser":{"$ref":"#/components/schemas/CompleteSessionBrowser"}},"required":["client_completion_id","status","command","summary","timestamp"],"additionalProperties":false},"SessionBrowserRuntime":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/SessionPage"},"run":{"$ref":"#/components/schemas/SessionRun"},"step":{"$ref":"#/components/schemas/SessionStep"}},"additionalProperties":false},"CreateSessionEventBody":{"type":"object","properties":{"client_event_id":{"type":"string","minLength":1,"description":"Idempotency key generated by the CLI for this session event.","example":"evt_start_session_completed_1"},"sequence_no":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Strictly increasing session event sequence number.","example":2},"type":{"type":"string","enum":["state","observe","reflect","action","error"]},"command":{"type":"string","minLength":1,"description":"CLI command that emitted the event.","example":"observe"},"status":{"type":"string","enum":["started","completed","blocked","failed"]},"summary":{"type":"string","minLength":1,"description":"Human-readable event summary.","example":"Observation completed."},"timestamp":{"type":"string","format":"date-time","description":"When the event happened on the CLI side.","example":"2026-03-26T09:02:00.000Z"},"phase":{"type":"string","nullable":true,"enum":["clarification","provider_search","provider_selection","method_selection","execution_preparation","execution","post_execution","completed"],"description":"Optional next phase for staged payment-agent orchestration flows.","example":"provider_search"},"phase_metadata":{"allOf":[{"$ref":"#/components/schemas/SessionJsonRecord"},{"description":"Optional structured phase details to persist alongside the event."}]},"commerce_provider_id":{"type":"string","nullable":true,"minLength":1},"commerce_method_key":{"type":"string","nullable":true,"minLength":1},"commerce_method_type":{"type":"string","nullable":true,"enum":["x402","mcp","api","reversed_api","browser"]},"commerce_provider_name":{"type":"string","nullable":true,"minLength":1},"commerce_selection":{"$ref":"#/components/schemas/SessionJsonRecord"},"commerce_execution_metadata":{"$ref":"#/components/schemas/SessionJsonRecord"},"details":{"$ref":"#/components/schemas/SessionJsonRecord"},"telemetry":{"$ref":"#/components/schemas/SessionTelemetryEnvelope"},"browser":{"$ref":"#/components/schemas/SessionBrowserRuntime"}},"required":["client_event_id","sequence_no","type","command","status","summary","timestamp"],"additionalProperties":false},"RuntimeRequestRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"intent_session_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"client_request_id":{"type":"string"},"kind":{"type":"string","enum":["data","action","choice"]},"status":{"type":"string","enum":["waiting_user","approved","executing","fulfilled","denied","expired","failed","canceled"]},"terminal":{"type":"boolean"},"resolution_path":{"type":"string","enum":["auto","confirm","provide"]},"blocking":{"type":"boolean"},"spec":{"type":"object","additionalProperties":{"nullable":true}},"context":{"type":"object","additionalProperties":{"nullable":true}},"bridge_context":{"type":"object","additionalProperties":{"nullable":true}},"resolution":{"type":"object","additionalProperties":{"nullable":true}},"selected_item_ref":{"type":"string","nullable":true,"minLength":1},"matched_trust_rule_ids":{"type":"array","items":{"type":"string"}},"result_ref":{"type":"string","nullable":true,"format":"uuid"},"title":{"type":"string"},"summary":{"type":"string","nullable":true},"error_code":{"type":"string","nullable":true},"error_message":{"type":"string","nullable":true},"scoring_status":{"type":"string","enum":["pending","processing","completed","failed"]},"scoring_result":{"type":"object","nullable":true,"additionalProperties":{"nullable":true}},"scoring_error":{"type":"string","nullable":true},"scoring_attempts":{"type":"integer","minimum":0},"scoring_started_at":{"type":"string","nullable":true,"format":"date-time"},"scoring_completed_at":{"type":"string","nullable":true,"format":"date-time"},"scoring_failed_at":{"type":"string","nullable":true,"format":"date-time"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"expires_at":{"type":"string","nullable":true,"format":"date-time"},"resolved_at":{"type":"string","nullable":true,"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"deleted":{"type":"boolean"}},"required":["id","intent_session_id","user_id","agent_id","client_request_id","kind","status","terminal","resolution_path","blocking","spec","context","bridge_context","resolution","selected_item_ref","matched_trust_rule_ids","result_ref","title","summary","error_code","error_message","scoring_status","scoring_result","scoring_error","scoring_attempts","scoring_started_at","scoring_completed_at","scoring_failed_at","metadata","expires_at","resolved_at","created_at","updated_at","deleted"]},"RuntimeRequestSubscriptionApprovalDecisionValue":{"type":"string","enum":["subscribe","do_not_subscribe"]},"RuntimeRequestSubscriptionTermsHash":{"type":"string","minLength":1,"pattern":"\\S","description":"Versioned hash of the normalized observed subscription terms.","example":"subscription_terms_v1_8b0f0a2c"},"RuntimeRequestSubscriptionApprovalDecisionPayload":{"type":"object","properties":{"approval_kind":{"type":"string","enum":["subscription_terms"]},"decision":{"$ref":"#/components/schemas/RuntimeRequestSubscriptionApprovalDecisionValue"},"approved_terms_hash":{"$ref":"#/components/schemas/RuntimeRequestSubscriptionTermsHash"},"previous_approved_terms_hash":{"allOf":[{"$ref":"#/components/schemas/RuntimeRequestSubscriptionTermsHash"},{"nullable":true}]}},"required":["approval_kind","decision","approved_terms_hash"],"additionalProperties":false},"RuntimeRequestDecisionPayload":{"type":"object","properties":{"subscription_approval":{"$ref":"#/components/schemas/RuntimeRequestSubscriptionApprovalDecisionPayload"}}},"RuntimeRequestDecisionRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"request_id":{"type":"string","format":"uuid"},"actor_type":{"type":"string","enum":["system","user","wallet","provider"]},"actor_id":{"type":"string","nullable":true,"format":"uuid"},"channel":{"type":"string","enum":["policy","dashboard","mobile","telegram","otp","wallet_ui","provider_callback"]},"decision":{"type":"string","nullable":true,"enum":["auto_approved","confirmed","denied","provided"]},"status":{"type":"string","enum":["pending","resolved","expired","failed"]},"attempt_count":{"type":"integer","minimum":0},"max_attempts":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true},"payload":{"$ref":"#/components/schemas/RuntimeRequestDecisionPayload"},"expires_at":{"type":"string","nullable":true,"format":"date-time"},"resolved_at":{"type":"string","nullable":true,"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","request_id","actor_type","actor_id","channel","decision","status","attempt_count","max_attempts","payload","expires_at","resolved_at","created_at","updated_at"]},"SessionStop":{"type":"object","properties":{"status":{"type":"string","enum":["canceled"]},"reason_code":{"type":"string"},"message":{"type":"string"},"stopped_at":{"type":"string","format":"date-time"}},"required":["status","reason_code"]},"RuntimeRequestEnvelope":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/RuntimeRequestRecord"},"decision":{"$ref":"#/components/schemas/RuntimeRequestDecisionRecord"},"session_stop":{"$ref":"#/components/schemas/SessionStop"}}},"RuntimeRequestContext":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"page_title":{"type":"string","minLength":1},"pageTitle":{"type":"string","minLength":1},"merchant_name":{"type":"string","minLength":1},"merchantName":{"type":"string","minLength":1},"form_purpose":{"type":"string","minLength":1},"formPurpose":{"type":"string","minLength":1}}},"RuntimeRequestBridge":{"type":"object","properties":{"page_ref":{"type":"string","minLength":1},"fill_ref":{"type":"string","minLength":1},"scope_ref":{"type":"string","minLength":1},"surface_ref":{"type":"string","minLength":1}}},"CreateRuntimeRequestBody":{"type":"object","properties":{"client_request_id":{"type":"string","minLength":1},"ttl_ms":{"type":"integer","minimum":0,"exclusiveMinimum":true},"kind":{"type":"string","enum":["data","action","choice"]},"spec":{"type":"object","additionalProperties":{"nullable":true}},"context":{"$ref":"#/components/schemas/RuntimeRequestContext"},"bridge":{"$ref":"#/components/schemas/RuntimeRequestBridge"}},"required":["client_request_id","kind","spec"]},"RequestDecisionBody":{"type":"object","properties":{"decision":{"type":"string","enum":["confirmed","provided","deny","denied","cancel","canceled","timeout","expired","choose_candidate"]},"selected_item_ref":{"type":"string","minLength":1},"selected_choice_id":{"type":"string","minLength":1},"inline_trust_rule_request":{"type":"object","properties":{"requested":{"type":"boolean"},"mode":{"type":"string","enum":["auto","confirm","provide","auto_with_limit"]},"limit":{"type":"number","minimum":0},"currency":{"type":"string","minLength":1},"period":{"type":"string","enum":["hour","day","week","month","total"]}},"required":["requested"]},"applicability_update":{"type":"object","properties":{"add_sites":{"type":"array","items":{"type":"string","minLength":1}}}},"subscription_approval":{"$ref":"#/components/schemas/RuntimeRequestSubscriptionApprovalDecisionPayload"},"values":{"type":"object","additionalProperties":{"nullable":true}},"save":{"type":"boolean"},"save_as":{"type":"object","properties":{"display_name":{"type":"string","minLength":1}}}},"required":["decision"]},"RuntimeRequestConfirmOtpBody":{"type":"object","properties":{"otp":{"type":"string","pattern":"^\\d{6}$"}},"required":["otp"]},"RuntimeArtifact":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["values"]},"values":{"type":"object","additionalProperties":{"nullable":true}}},"required":["kind","values"]},{"type":"object","properties":{"kind":{"type":"string","enum":["signature"]},"signature":{"type":"string"},"signer":{"type":"string"}},"required":["kind","signature","signer"]},{"type":"object","properties":{"kind":{"type":"string","enum":["reference"]},"reference":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"nullable":true}}},"required":["kind","reference"]},{"type":"object","properties":{"kind":{"type":"string","enum":["confirmation"]},"confirmed":{"type":"boolean","enum":[true]}},"required":["kind","confirmed"]},{"type":"object","properties":{"kind":{"type":"string","enum":["choice"]},"selected_option":{"type":"object","additionalProperties":{"nullable":true}},"adjustment_prompt":{"type":"string"}},"required":["kind"]}]},"RuntimeArtifactClaim":{"type":"object","properties":{"artifact":{"$ref":"#/components/schemas/RuntimeArtifact"},"session_stop":{"$ref":"#/components/schemas/SessionStop"}}},"RuntimeRequestList":{"type":"object","properties":{"requests":{"type":"array","items":{"$ref":"#/components/schemas/RuntimeRequestRecord"}}},"required":["requests"]},"RuntimeRequestEventsResponse":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["events"]},"MemoryValueHandle":{"type":"object","properties":{"resolver":{"type":"string"},"value_class":{"type":"string"},"ref":{"type":"string"}},"required":["resolver","value_class"]},"MemoryField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"hint":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true,"enum":["date","phone_number","person_name"]},"is_secret":{"type":"boolean"},"provider_managed":{"type":"boolean"},"value_handle":{"$ref":"#/components/schemas/MemoryValueHandle"},"exposure_profile":{"type":"object","additionalProperties":{"nullable":true}},"provenance":{"type":"object","additionalProperties":{"nullable":true}},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true}},"required":["id","label","hint","is_secret","provider_managed","value_handle","exposure_profile","provenance","status","created_at","updated_at","deleted_at"]},"MemoryItem":{"type":"object","properties":{"id":{"type":"string"},"owner_user_id":{"type":"string"},"schema_ref":{"type":"string"},"schema_version":{"type":"number"},"label":{"type":"string"},"display_label":{"type":"string"},"status":{"type":"string"},"durability":{"type":"string"},"storage_root":{"type":"string","enum":["memory_item"]},"subject_links":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"scope":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"provenance":{"type":"object","additionalProperties":{"nullable":true}},"availability":{"type":"object","additionalProperties":{"nullable":true}},"read_only":{"type":"boolean"},"read_only_reason":{"type":"string"},"policies":{"type":"object","additionalProperties":{"nullable":true}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/MemoryField"}},"promoted_to_durable_memory":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true}},"required":["id","owner_user_id","schema_ref","schema_version","label","display_label","status","durability","storage_root","subject_links","scope","provenance","availability","policies","fields","promoted_to_durable_memory","created_at","updated_at","deleted_at"]},"MemoryItemList":{"type":"object","properties":{"value_visibility":{"type":"string","enum":["handles_only"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/MemoryItem"}}},"required":["value_visibility","items"]},"MemoryItemEnvelope":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/MemoryItem"}},"required":["item"]},"MemoryApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"fields":{"type":"array","items":{"type":"string"}}},"required":["code"]}},"required":["error"]},"MemoryFieldInput":{"type":"object","properties":{"id":{"type":"string","minLength":1},"field_ref":{"type":"string","minLength":1},"fieldRef":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"field_label":{"type":"string","minLength":1},"fieldLabel":{"type":"string","minLength":1},"hint":{"type":"string","nullable":true,"minLength":1},"value_type":{"type":"string","nullable":true,"enum":["date","phone_number","person_name"]},"is_secret":{"type":"boolean"},"value_handle":{"type":"object","additionalProperties":{"nullable":true}},"materialized_payload":{"type":"object","additionalProperties":{"nullable":true}},"value_payload":{"type":"object","additionalProperties":{"nullable":true}},"provider_payload":{"type":"object","additionalProperties":{"nullable":true}},"exposure_profile":{"type":"object","additionalProperties":{"nullable":true}},"provenance":{"type":"object","additionalProperties":{"nullable":true}},"status":{"type":"string","minLength":1},"remove":{"type":"boolean"}}},"CreateMemoryItemBody":{"type":"object","properties":{"label":{"type":"string","minLength":1},"display_label":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"durability":{"type":"string","minLength":1},"subject_links":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"scope":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"provenance":{"type":"object","additionalProperties":{"nullable":true}},"availability":{"type":"object","additionalProperties":{"nullable":true}},"ask_before_use":{"type":"boolean"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/MemoryFieldInput"}}}},"MemoryFieldForEdit":{"allOf":[{"$ref":"#/components/schemas/MemoryField"},{"type":"object","properties":{"value_status":{"type":"string","enum":["ready","missing","conflict","provider_unavailable","provider_needs_reauth","not_materializable","provider_managed"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true},{"nullable":true}]}},"required":["value_status"]}]},"MemoryItemForEditEnvelope":{"type":"object","properties":{"value_visibility":{"type":"string","enum":["editor_values"]},"item":{"allOf":[{"$ref":"#/components/schemas/MemoryItem"},{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/MemoryFieldForEdit"}}}}]}},"required":["value_visibility","item"]},"MemoryItemPatchEnvelope":{"type":"object","properties":{"item":{"$ref":"#/components/schemas/MemoryItem"},"created_new_item":{"type":"boolean","enum":[false]}},"required":["item","created_new_item"]},"PatchMemoryItemBody":{"allOf":[{"$ref":"#/components/schemas/CreateMemoryItemBody"},{"type":"object","properties":{"update_mode":{"type":"string","minLength":1}}}]},"MemoryPolicyEvaluateResponse":{"type":"object","properties":{"policy_level":{"type":"string"},"ask_before_use":{"type":"boolean"},"created_runtime_request":{"type":"boolean","enum":[false]},"evaluation_order":{"type":"array","items":{"type":"string"}}},"required":["policy_level","ask_before_use","created_runtime_request","evaluation_order"]},"MemoryPolicyEvaluateBody":{"type":"object","properties":{"item_ref":{"type":"string","minLength":1},"overrides":{"type":"object","additionalProperties":{"nullable":true}}}},"MemoryAvailabilityState":{"type":"object","properties":{"status":{"type":"string","enum":["ready","missing","conflict","provider_unavailable","provider_needs_reauth","not_materializable","authorization_required"],"description":"Machine-readable Memory availability state. `authorization_required` means a resource exists but is hidden until the matching approval succeeds.","example":"authorization_required"},"reason":{"type":"string","description":"Machine-readable reason for the availability state.","example":"payment_authorization_required"},"category":{"type":"string","description":"Resource category when the state applies to a category-level entry.","example":"payment_card"}},"description":"Machine-readable Memory availability state. Provider-backed payment cards use `status: \"authorization_required\"` before payment authorization.","example":{"status":"authorization_required","reason":"payment_authorization_required","category":"payment_card"}},"MemoryCatalogUnavailableEntry":{"type":"object","properties":{"type":{"type":"string"},"category":{"type":"string"},"item_ref":{"type":"string"},"item_name":{"type":"string"},"item_label":{"type":"string"},"provider_managed":{"type":"boolean"},"availability":{"$ref":"#/components/schemas/MemoryAvailabilityState"}},"required":["availability"]},"MemoryCatalogResponse":{"type":"object","properties":{"value_visibility":{"type":"string","enum":["handles_only"]},"catalog_source":{"type":"string","enum":["memory"]},"ranking_order":{"type":"array","items":{"type":"string"}},"items":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"candidates":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"missing":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"conflicts":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}},"unavailable":{"type":"array","items":{"$ref":"#/components/schemas/MemoryCatalogUnavailableEntry"}},"availability":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/MemoryAvailabilityState"}},"policies":{"type":"object","additionalProperties":{"nullable":true}}},"required":["value_visibility","catalog_source","ranking_order","items","candidates","missing","conflicts","unavailable","availability","policies"]},"MemoryMaterializedValue":{"type":"object","properties":{"handle":{"type":"string"},"status":{"type":"string","enum":["ready","missing","conflict","provider_unavailable","provider_needs_reauth","not_materializable"]},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true},{"nullable":true}]},"text":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"nullable":true},{"nullable":true}]},"reason":{"type":"string"}},"required":["handle","status"]},"MemoryMaterializationResponse":{"type":"object","properties":{"value_visibility":{"type":"string","enum":["runtime_only"]},"values":{"type":"array","items":{"$ref":"#/components/schemas/MemoryMaterializedValue"}}},"required":["value_visibility","values"]},"MemoryMaterializationBody":{"type":"object","properties":{"handles":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":64}},"required":["handles"]},"TrustScope":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["category"]},"category":{"type":"string","minLength":1},"site":{"type":"string","minLength":1}},"required":["type","category"]},{"type":"object","properties":{"type":{"type":"string","enum":["capability"]},"capability":{"type":"string","minLength":1},"site":{"type":"string","minLength":1}},"required":["type","capability"]},{"type":"object","properties":{"type":{"type":"string","enum":["site"]},"site":{"type":"string","minLength":1}},"required":["type","site"]}]},"TrustRuleMode":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","enum":["auto"]}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","enum":["confirm"]}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","enum":["auto_with_limit"]},"limit":{"type":"number","minimum":0},"currency":{"type":"string","minLength":1},"period":{"type":"string","enum":["hour","day","week","month","total"]}},"required":["mode","limit","currency","period"]}]},"TrustRule":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","nullable":true,"format":"uuid"},"scope":{"$ref":"#/components/schemas/TrustScope"},"rule":{"$ref":"#/components/schemas/TrustRuleMode"},"status":{"type":"string","enum":["active","paused"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","user_id","agent_id","scope","rule","status","created_at","updated_at"]},"TrustRuleList":{"type":"object","properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/TrustRule"}}},"required":["rules"]},"CreateTrustRuleBody":{"type":"object","properties":{"agent_id":{"type":"string","nullable":true,"format":"uuid"},"scope":{"$ref":"#/components/schemas/TrustScope"},"rule":{"$ref":"#/components/schemas/TrustRuleMode"},"status":{"type":"string","enum":["active","paused"]}},"required":["scope","rule"]},"PatchTrustRuleBody":{"type":"object","properties":{"agent_id":{"type":"string","nullable":true,"format":"uuid"},"scope":{"$ref":"#/components/schemas/TrustScope"},"rule":{"$ref":"#/components/schemas/TrustRuleMode"},"status":{"type":"string","enum":["active","paused"]}}},"TelemetryTraceIngestResponse":{"type":"object","properties":{"accepted":{"type":"boolean","description":"True when the payload passed validation and was accepted for ingest.","example":true},"forwarded":{"type":"boolean","description":"True when the payload was forwarded to the configured OTLP sink.","example":true},"duplicate":{"type":"boolean","description":"Present when ingest recognized a duplicate payload and skipped a second forward.","example":false}},"required":["accepted","forwarded"],"description":"Accepted observability ingest result."},"TelemetryTraceIngestError":{"type":"object","properties":{"error":{"type":"string","description":"Stable machine-readable ingest error code.","example":"invalid_otlp_payload"},"message":{"type":"string","description":"Human-readable explanation of why ingest failed.","example":"Telemetry ingest expects a non-empty OTLP/HTTP JSON traces payload."},"upstreamStatus":{"type":"integer","description":"Status returned by the downstream OTLP sink when forward failed.","example":503}},"required":["error","message"],"description":"Observability ingest error envelope."},"TelemetryTraceIngestBody":{"type":"object","properties":{"resourceSpans":{"type":"array","items":{"type":"object","properties":{"scopeSpans":{"type":"array","items":{"type":"object","properties":{"spans":{"type":"array","items":{"nullable":true},"minItems":1,"description":"Non-empty OTLP span batch for one instrumentation scope."}},"required":["spans"]},"minItems":1,"description":"One or more scope span batches grouped under one OTLP resource."}},"required":["scopeSpans"]},"minItems":1,"description":"Non-empty OTLP/HTTP JSON traces payload."}},"required":["resourceSpans"],"description":"OTLP/HTTP JSON traces payload accepted by the observability ingest route. Additional OTLP fields are preserved and forwarded unchanged.","example":{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"@nuanu-ai/agentbrowse"}}]},"scopeSpans":[{"scope":{"name":"agentbrowse.local-run-store"},"spans":[{"traceId":"11111111111111111111111111111111","spanId":"2222222222222222","name":"agentbrowse.launch"}]}]}]}},"NotificationPreference":{"type":"object","properties":{"type":{"type":"string","enum":["transaction_alert","balance_alert","agent_status","security"],"example":"transaction_alert"},"push":{"type":"boolean","example":true},"email":{"type":"boolean","example":true},"telegram":{"type":"boolean","example":false}},"required":["type","push","email","telegram"]},"NotificationPreferencesResponse":{"type":"array","items":{"$ref":"#/components/schemas/NotificationPreference"},"description":"List of notification preferences for all notification types."},"UpdateNotificationPreferenceResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true],"example":true}},"required":["ok"]},"UpdateNotificationPreferenceBody":{"type":"object","properties":{"notification_type":{"type":"string","enum":["transaction_alert","balance_alert","agent_status","security"],"description":"The notification type to update.","example":"transaction_alert"},"channel":{"type":"string","enum":["push","email","telegram"],"description":"The delivery channel to toggle.","example":"telegram"},"enabled":{"type":"boolean","description":"Whether the channel should be enabled for this notification type.","example":true}},"required":["notification_type","channel","enabled"]},"SubscriptionLifecycleStatus":{"type":"string","enum":["active","pending_activation","needs_review","cancelled"]},"SubscriptionRecurringObligation":{"type":"string","enum":["none","confirmed","possible"]},"ManagedSubscriptionTermsHash":{"type":"string","nullable":true,"minLength":1,"pattern":"\\S","description":"Versioned hash of the normalized observed subscription terms.","example":"subscription_terms_v1_8b0f0a2c"},"SubscriptionDetectedAtPhase":{"type":"string","enum":["pre_fill","pre_submit"]},"SubscriptionBillingShape":{"type":"object","properties":{"summary_label":{"type":"string","nullable":true,"minLength":1,"pattern":"\\S"},"attributes":{"type":"array","items":{"type":"string","minLength":1,"pattern":"\\S"}},"raw_terms":{"type":"array","items":{"type":"string","minLength":1,"pattern":"\\S"}},"unmodeled_terms":{"type":"array","items":{"type":"string","minLength":1,"pattern":"\\S"}}},"required":["summary_label","attributes","raw_terms","unmodeled_terms"],"additionalProperties":false},"SubscriptionMoneyAmount":{"type":"object","properties":{"amount":{"type":"number","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount","currency"],"additionalProperties":false},"SubscriptionMoneyTermsField":{"oneOf":[{"type":"object","properties":{"state":{"type":"string","enum":["known"]},"value":{"$ref":"#/components/schemas/SubscriptionMoneyAmount"}},"required":["state","value"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","enum":["unknown"]}},"required":["state"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","enum":["not_applicable"]}},"required":["state"],"additionalProperties":false}]},"SubscriptionStringTermsField":{"oneOf":[{"type":"object","properties":{"state":{"type":"string","enum":["known"]},"value":{"type":"string","minLength":1,"pattern":"\\S"}},"required":["state","value"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","enum":["unknown"]}},"required":["state"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","enum":["not_applicable"]}},"required":["state"],"additionalProperties":false}]},"SubscriptionTermsCompleteness":{"type":"string","enum":["complete","partial"]},"SubscriptionEvidenceSufficiency":{"type":"string","enum":["sufficient","insufficient"]},"SubscriptionContextCoverage":{"type":"string","enum":["sufficient","insufficient"]},"SubscriptionEvidencePolarity":{"type":"string","enum":["positive","negative","neutral"]},"SubscriptionEvidenceItem":{"type":"object","properties":{"snippet":{"type":"string","minLength":1,"pattern":"\\S"},"source":{"type":"string","minLength":1,"pattern":"\\S"},"polarity":{"$ref":"#/components/schemas/SubscriptionEvidencePolarity"},"normalized_meaning":{"type":"string","minLength":1,"pattern":"\\S"},"proximity":{"type":"string","nullable":true,"minLength":1,"pattern":"\\S"}},"required":["snippet","source","polarity","normalized_meaning","proximity"],"additionalProperties":false},"SubscriptionTermsHash":{"type":"string","minLength":1,"pattern":"\\S","description":"Versioned hash of the normalized observed subscription terms.","example":"subscription_terms_v1_8b0f0a2c"},"ObservedTermsSnapshot":{"type":"object","nullable":true,"properties":{"detected_at_phase":{"$ref":"#/components/schemas/SubscriptionDetectedAtPhase"},"recurring_obligation":{"$ref":"#/components/schemas/SubscriptionRecurringObligation"},"billing_shape":{"$ref":"#/components/schemas/SubscriptionBillingShape"},"first_charge":{"$ref":"#/components/schemas/SubscriptionMoneyTermsField"},"recurring_charge":{"$ref":"#/components/schemas/SubscriptionMoneyTermsField"},"interval":{"$ref":"#/components/schemas/SubscriptionStringTermsField"},"trial_end":{"$ref":"#/components/schemas/SubscriptionStringTermsField"},"display_price":{"$ref":"#/components/schemas/SubscriptionStringTermsField"},"language_or_locale":{"type":"string","minLength":1,"pattern":"\\S"},"terms_completeness":{"$ref":"#/components/schemas/SubscriptionTermsCompleteness"},"evidence_sufficiency":{"$ref":"#/components/schemas/SubscriptionEvidenceSufficiency"},"context_coverage":{"$ref":"#/components/schemas/SubscriptionContextCoverage"},"missing_fields":{"type":"array","items":{"type":"string","minLength":1,"pattern":"\\S"}},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionEvidenceItem"}},"terms_hash":{"$ref":"#/components/schemas/SubscriptionTermsHash"},"extractor_version":{"type":"string","nullable":true,"minLength":1,"pattern":"\\S"},"normalizer_version":{"type":"string","nullable":true,"minLength":1,"pattern":"\\S"}},"required":["detected_at_phase","recurring_obligation","billing_shape","first_charge","recurring_charge","interval","trial_end","display_price","language_or_locale","terms_completeness","evidence_sufficiency","context_coverage","missing_fields","evidence","terms_hash","extractor_version","normalizer_version"],"additionalProperties":false},"SubscriptionManagementCapabilities":{"type":"object","properties":{"can_cancel":{"type":"boolean"},"can_pause":{"type":"boolean"},"can_resume":{"type":"boolean"},"reason":{"type":"string","nullable":true,"minLength":1}},"required":["can_cancel","can_pause","can_resume","reason"],"additionalProperties":false},"SubscriptionAgent":{"type":"object","nullable":true,"properties":{"name":{"type":"string","minLength":1,"pattern":"\\S"}},"required":["name"],"additionalProperties":false},"ManagedSubscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"service_name":{"type":"string","minLength":1,"pattern":"\\S"},"service_url":{"type":"string","nullable":true,"minLength":1},"provider_name":{"type":"string","nullable":true,"minLength":1},"amount":{"type":"number","minimum":0},"currency":{"type":"string","minLength":1,"pattern":"\\S"},"frequency":{"type":"string","nullable":true,"minLength":1},"status":{"type":"string","minLength":1,"pattern":"\\S"},"lifecycle_status":{"$ref":"#/components/schemas/SubscriptionLifecycleStatus"},"recurring_obligation":{"$ref":"#/components/schemas/SubscriptionRecurringObligation"},"summary_label":{"type":"string","nullable":true,"minLength":1},"summary_amount":{"type":"number","nullable":true,"minimum":0},"summary_currency":{"type":"string","nullable":true,"minLength":1},"summary_interval":{"type":"string","nullable":true,"minLength":1},"next_renewal_at":{"type":"string","nullable":true,"format":"date-time"},"next_known_renewal_at":{"type":"string","nullable":true,"format":"date-time"},"trial_end_at":{"type":"string","nullable":true,"format":"date-time"},"last_payment_at":{"type":"string","nullable":true,"format":"date-time"},"total_paid":{"type":"number","minimum":0},"deleted":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":{"nullable":true}},"flags":{"type":"array","items":{"type":"string","minLength":1,"pattern":"\\S"}},"derived_states":{"type":"array","items":{"type":"string","minLength":1,"pattern":"\\S"}},"current_terms_hash":{"$ref":"#/components/schemas/ManagedSubscriptionTermsHash"},"current_terms_snapshot":{"$ref":"#/components/schemas/ObservedTermsSnapshot"},"extractor_version":{"type":"string","nullable":true,"minLength":1},"normalizer_version":{"type":"string","nullable":true,"minLength":1},"source_request_id":{"type":"string","nullable":true,"format":"uuid"},"source_session_id":{"type":"string","nullable":true,"format":"uuid"},"source_payment_operation_id":{"type":"string","nullable":true,"format":"uuid"},"source_approval_decision_id":{"type":"string","nullable":true,"format":"uuid"},"payment_operation_id":{"type":"string","nullable":true,"format":"uuid"},"evidence_preview":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionEvidenceItem"}},"management_capabilities":{"$ref":"#/components/schemas/SubscriptionManagementCapabilities"},"agents":{"$ref":"#/components/schemas/SubscriptionAgent"}},"required":["id","agent_id","user_id","service_name","service_url","provider_name","amount","currency","frequency","status","lifecycle_status","recurring_obligation","summary_label","summary_amount","summary_currency","summary_interval","next_renewal_at","next_known_renewal_at","trial_end_at","last_payment_at","total_paid","deleted","created_at","updated_at","metadata","flags","derived_states","current_terms_hash","current_terms_snapshot","extractor_version","normalizer_version","source_request_id","source_session_id","source_payment_operation_id","source_approval_decision_id","payment_operation_id","evidence_preview","management_capabilities"],"additionalProperties":false},"SubscriptionListResponse":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/ManagedSubscription"}}},"required":["subscriptions"],"additionalProperties":false},"SubscriptionEnvelope":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/ManagedSubscription"}},"required":["subscription"],"additionalProperties":false}},"parameters":{}},"servers":[{"url":"/functions/v1"}],"tags":[{"name":"Core","description":"Start here: health checks and metadata for the agent linked to your API key."},{"name":"Sessions","description":"Run browser-backed workflows: start a session, send progress updates, create or review requests, claim one-time artifacts, and finish the run."},{"name":"LLM","description":"OpenAI-compatible chat completions subset backed by the MagicPay LLM gateway."},{"name":"Observability","description":"Ingest OTLP traces for workflow observability without mixing raw telemetry into product session routes."},{"name":"Tools","description":"Call backend services such as CAPTCHA solving."},{"name":"Subscriptions","description":"Read-only managed subscription records with lifecycle, source links, evidence, hashes, and backend capability flags."}],"paths":{"/api/health":{"get":{"tags":["Core"],"summary":"Check API health","description":"Unauthenticated health check for uptime probes and deployment verification.","responses":{"200":{"description":"API is reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/agent/me":{"get":{"tags":["Core"],"summary":"Get the current agent","security":[{"bearerAuth":[]}],"description":"Returns the profile and aggregate usage stats for the agent linked to the API key.","responses":{"200":{"description":"Agent info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"},"example":{"id":"bc6a74cb-6ee7-49f2-a91e-0f5eaa6f3b8d","name":"Finance Automation Agent","description":"Handles recurring SaaS and infra payments.","status":"active","budget_limit":1000,"daily_limit":100,"transaction_limit":50,"created_at":"2026-02-20T10:00:00.000Z","stats":{"monthly_spend":312.45,"payment_operation_count_month":16,"active_subscriptions":4,"avg_risk_score":0.18}}}}},"403":{"description":"Not an agent-scoped key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/chat/completions":{"post":{"tags":["LLM"],"summary":"Create a chat completion","security":[{"bearerAuth":[]}],"description":"OpenAI-compatible chat completions subset backed by the MagicPay LLM gateway.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"Chat completion response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Provider rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Provider configuration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Provider gateway error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/tools/captcha/tasks":{"post":{"tags":["Tools"],"summary":"Create a CAPTCHA solving task","security":[{"bearerAuth":[]}],"description":"Starts a CAPTCHA task on the backend. Poll the returned `task_id` until the task becomes ready.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptchaTaskCreateRequest"},"example":{"type":"hcaptcha","site_key":"10000000-ffff-ffff-ffff-000000000001","page_url":"https://checkout.example.com/pay"}}}},"responses":{"200":{"description":"Captcha task created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptchaTaskCreateResponse"},"example":{"provider":"capsolver","task_id":"task-123456","status":"pending"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Provider gateway error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/tools/captcha/tasks/{id}":{"get":{"tags":["Tools"],"summary":"Get a CAPTCHA task result","security":[{"bearerAuth":[]}],"description":"Polls the status of a previously created CAPTCHA task. When `status=ready`, use the returned token on the target site.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Task identifier returned by POST /tools/captcha/tasks.","example":"task-123456"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Captcha task status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaptchaTaskStatusResponse"},"examples":{"pending":{"value":{"provider":"capsolver","task_id":"task-123456","status":"pending"}},"ready":{"value":{"provider":"capsolver","task_id":"task-123456","status":"ready","token":"03AFcWeA7..."}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Provider gateway error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/magicsearch/query":{"post":{"tags":["Tools"],"summary":"Resolve a refined purchase prompt to a start URL","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MagicSearchQueryBody"}}}},"responses":{"200":{"description":"Resolved URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MagicSearchQueryResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions":{"post":{"tags":["Sessions"],"summary":"Start a workflow session","security":[{"bearerAuth":[]}],"description":"Starts one active workflow session for the current agent. Browser metadata is optional and is attached through the `browser` binding when the runtime is actively connected to a browser.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionBody"}}}},"responses":{"201":{"description":"Workflow session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionEnvelope"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Agent scope required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}":{"get":{"tags":["Sessions"],"summary":"Get session state","security":[{"bearerAuth":[]}],"description":"Returns the current state of a workflow session, including any active canonical request.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Workflow session id.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Workflow session state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionEnvelope"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/complete":{"post":{"tags":["Sessions"],"summary":"Finish a session","security":[{"bearerAuth":[]}],"description":"Closes a session with a final status such as `completed`, `canceled`, or `error`. Use this when the run is over. The request is idempotent and fails if the session is still waiting for an unresolved canonical request.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Workflow session id.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteSessionBody"}}}},"responses":{"200":{"description":"Workflow session closed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionEventResponse"}}}},"400":{"description":"Invalid session completion request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/events":{"post":{"tags":["Sessions"],"summary":"Send a session event","security":[{"bearerAuth":[]}],"description":"Use this endpoint to report progress updates, observations, actions, or errors for an active session. It records timeline entries and updates session state, but it does not finish the session.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Workflow session id.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionEventBody"}}}},"responses":{"200":{"description":"Event accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionEventResponse"}}}},"400":{"description":"Invalid session event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/requests":{"post":{"tags":["Sessions"],"summary":"Create a canonical runtime request","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRuntimeRequestBody"}}}},"responses":{"200":{"description":"Request created or reused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeRequestEnvelope"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Sessions"],"summary":"List canonical requests for a session","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Session requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeRequestList"}}}}}}},"/api/sessions/{id}/requests/{requestId}":{"get":{"tags":["Sessions"],"summary":"Get a canonical runtime request snapshot","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"requestId","in":"path"}],"responses":{"200":{"description":"Request snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeRequestEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/requests/{requestId}/decisions":{"post":{"tags":["Sessions"],"summary":"Submit a runtime request decision","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"requestId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestDecisionBody"}}}},"responses":{"200":{"description":"Updated request snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeRequestEnvelope"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/requests/{requestId}/confirm-otp":{"post":{"tags":["Sessions"],"summary":"Confirm a runtime request with OTP","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"requestId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeRequestConfirmOtpBody"}}}},"responses":{"200":{"description":"Updated request snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeRequestEnvelope"}}}},"400":{"description":"Invalid, ineligible, or already resolved request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request or OTP approval not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"OTP attempts exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/requests/{requestId}/claim":{"post":{"tags":["Sessions"],"summary":"Claim a request artifact","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid"},"required":true,"name":"requestId","in":"path"}],"responses":{"200":{"description":"Claimed artifact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeArtifactClaim"}}}},"400":{"description":"Artifact not ready or already consumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/requests":{"get":{"tags":["Sessions"],"summary":"List runtime requests for the authenticated user","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["waiting_user","approved","executing","fulfilled","denied","expired","failed","canceled"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Runtime requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeRequestList"}}}}}}},"/api/requests/{requestId}/events":{"get":{"tags":["Sessions"],"summary":"List request events","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"requestId","in":"path"}],"responses":{"200":{"description":"Request events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuntimeRequestEventsResponse"}}}}}}},"/api/memory-items":{"get":{"tags":["Sessions"],"summary":"List value-free MagicPay Memory items","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"url","in":"query"},{"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"required":false,"name":"all_sites","in":"query"}],"responses":{"200":{"description":"Memory items with value handles only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryItemList"}}}}}},"post":{"tags":["Sessions"],"summary":"Create a MagicPay Memory item","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMemoryItemBody"}}}},"responses":{"201":{"description":"Created Memory item with value handles only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryItemEnvelope"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Memory item failed product validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryApiError"}}}}}}},"/api/memory-items/{id}/for-edit":{"get":{"tags":["Sessions"],"summary":"Get a MagicPay Memory item with owner-only editor values","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Memory item with raw values for the owner editor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryItemForEditEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/memory-items/{id}":{"get":{"tags":["Sessions"],"summary":"Get a value-free MagicPay Memory item","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Memory item with value handles only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryItemEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Sessions"],"summary":"Patch a MagicPay Memory item and its fields","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchMemoryItemBody"}}}},"responses":{"200":{"description":"Updated Memory item with value handles only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryItemPatchEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Memory item failed product validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryApiError"}}}}}},"delete":{"tags":["Sessions"],"summary":"Soft-delete a MagicPay Memory item","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deleted Memory item with value handles only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryItemEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/memory-policy/evaluate":{"post":{"tags":["Sessions"],"summary":"Evaluate deterministic item-level Memory use state","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryPolicyEvaluateBody"}}}},"responses":{"200":{"description":"Deterministic item-level Memory use state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryPolicyEvaluateResponse"}}}}}}},"/api/sessions/{id}/memory-catalog":{"get":{"tags":["Sessions"],"summary":"List value-free MagicPay Memory handles for a session","description":"Returns handles-only Memory descriptors for an active workflow session. Provider-backed payment cards are advertised as `unavailable` with `availability.status: \"authorization_required\"` until `authorize_payment` succeeds for that session; card field handles are returned only after that approval.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","minLength":1},"required":true,"name":"url","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"purpose","in":"query"},{"schema":{"type":"string","minLength":1},"required":false,"name":"subject_hint","in":"query"}],"responses":{"200":{"description":"Value-free Memory catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryCatalogResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/sessions/{id}/memory-materializations":{"post":{"tags":["Sessions"],"summary":"Materialize MagicPay Memory handles for trusted apply-fill","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryMaterializationBody"}}}},"responses":{"200":{"description":"Runtime-only materialized values for trusted executors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryMaterializationResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/trust-rules":{"get":{"tags":["Sessions"],"summary":"List canonical trust rules","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Visible trust rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustRuleList"}}}}}},"post":{"tags":["Sessions"],"summary":"Create a trust rule","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTrustRuleBody"}}}},"responses":{"200":{"description":"Created trust rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustRule"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/trust-rules/{id}":{"patch":{"tags":["Sessions"],"summary":"Patch a trust rule","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchTrustRuleBody"}}}},"responses":{"200":{"description":"Updated trust rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustRule"}}}}}}},"/api/trust-rules/{id}/pause":{"post":{"tags":["Sessions"],"summary":"Pause a trust rule","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Paused trust rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustRule"}}}}}}},"/api/trust-rules/{id}/activate":{"post":{"tags":["Sessions"],"summary":"Activate a trust rule","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Activated trust rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustRule"}}}}}}},"/api/observability/telemetry/traces":{"post":{"tags":["Observability"],"summary":"Ingest OTLP traces","security":[{"bearerAuth":[]}],"description":"Accepts OTLP/HTTP JSON traces for workflow observability. This route uses the same bearer API key model as other agent-facing API routes. Product session routes do not accept raw telemetry payloads.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryTraceIngestBody"}}}},"responses":{"202":{"description":"Telemetry payload accepted for ingest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryTraceIngestResponse"}}}},"400":{"description":"Invalid OTLP payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryTraceIngestError"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryTraceIngestError"}}}},"500":{"description":"Failed to write telemetry index rows","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryTraceIngestError"}}}},"502":{"description":"Failed to forward traces to downstream OTLP sink","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryTraceIngestError"}}}}}}},"/api/notification-preferences":{"get":{"tags":["Core"],"summary":"Get notification preferences","security":[{"bearerAuth":[]}],"description":"Returns notification delivery preferences for all notification types belonging to the authenticated user.","responses":{"200":{"description":"Notification preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferencesResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["Core"],"summary":"Update a notification preference","security":[{"bearerAuth":[]}],"description":"Toggle a single notification delivery channel for a given notification type.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNotificationPreferenceBody"}}}},"responses":{"200":{"description":"Preference updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNotificationPreferenceResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/subscriptions":{"get":{"tags":["Subscriptions"],"summary":"List managed subscriptions","security":[{"bearerAuth":[]}],"description":"Returns read-only managed subscription records visible to the current API key scope, including lifecycle status, source links, terms evidence, versioned terms hash, and backend capability flags.","parameters":[{"schema":{"$ref":"#/components/schemas/SubscriptionLifecycleStatus"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"agent_id","in":"query"}],"responses":{"200":{"description":"Managed subscription list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionListResponse"}}}}}}},"/api/subscriptions/{id}":{"get":{"tags":["Subscriptions"],"summary":"Get one managed subscription","security":[{"bearerAuth":[]}],"description":"Returns one read-only managed subscription visible to the current API key scope.","parameters":[{"schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Managed subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionEnvelope"}}}},"404":{"description":"Subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}