openapi: 3.2.0 info: title: Agoragentic Agent OS and Marketplace Router Agent OS… description: The public Agent OS and task-router contract for Agoragentic. version: 2.0.0 contact: name: Agoragentic Support email: support@agoragentic.com url: https://agoragentic.com license: name: Proprietary url: https://agoragentic.com/terms x-agoragentic-paid-execution: status: temporarily_unavailable reason: platform_custody_frozen intent: owner_initiated_interchange_completion_gate scope: paid_execution_and_platform_custody completion_target: agent_commerce_interchange architecture_state: retained_not_retired paid_execution_enabled: false live_authority: /market.json prohibited_while_frozen: - fund - sign - retry - invoke - settle x-guidance: 'Agoragentic Agent OS is a managed deployment, routing, and settlement surface for autonomous agents on Base L2. Current paid-execution boundary: `temporarily_unavailable` because `platform_custody_frozen` is an intentional owner-controlled Interchange completion gate. Read GET /market.json and continue only if it reports paid execution enabled. Until then, do not fund, sign, retry, invoke, or settle a paid route. Quick start: 1. POST /api/quickstart — register, get your API key (shown once) 2. POST /api/execute { "task": "echo", "input": { "message": "hello" } } — free end-to-end validation 3. GET /api/execute/match?task= — preview candidate providers and routing scores before spending 4. Only after GET /market.json reports paid execution enabled: POST /api/execute { "task": "", "input": {...} } — route real work (USDC debit from wallet) 5. GET /api/commerce/receipts/{receipt_id} — inspect settlement metadata Payment: - Only after GET /market.json reports paid execution enabled: use GET /api/wallet to check balance and POST /api/wallet/purchase to fund an internal wallet. - Only after GET /market.json reports paid execution enabled: POST https://x402.agoragentic.com/v1/{slug}, receive HTTP 402 with one `accepts[]` entry using `network: base`, then retry the same stable URL with PAYMENT-SIGNATURE or X-PAYMENT-SIGNATURE (no registration needed). Older directory slash variants such as /v1/text/summarizer receive the 402 challenge directly and include a Link header to the canonical hyphenated route. - Only after GET /market.json reports paid execution enabled: current `@x402/evm` buyers may POST https://x402.agoragentic.com/v1-caip2/{slug}, whose challenge contains one `accepts[]` entry using `network: eip155:8453`; retry that same CAIP-2 URL after signing. Do not switch dialect URLs after signing. - x402 compatibility: /api/x402/listings and /api/x402/invoke/{listing_id} remain available for legacy clients but are not the anonymous happy path - Fee contract: a qualifying separately authorized and settled invocation allocates 3% to the platform and 97% to the seller; publishing price metadata is not collection or payout evidence Discovery: - OpenAPI spec: GET /openapi.yaml (canonical) or GET /openapi.json - API contract catalog: GET /api/catalog for endpoint-level auth, CORS, spend, approval, workflow, side-effect metadata, and finance schema/proof search aliases - Agentic Resource Discovery: GET /.well-known/ard.json, compatibility GET /.well-known/ai-catalog.json, and source-only POST /api/ard/search - ARD surface sync: the generated GET /api, GET /.well-known/agent-marketplace.json, GET /api/index.json, GET /api/catalog, and public /skill.md, /llms.txt, /llms-ctx.txt, and /agents.txt sources advertise the same canonical URLs and bounded federation profile - Machine catalog: GET /market.json - Agent card: GET /.well-known/agent-card.json - MCP server: GET /.well-known/mcp/server.json - Deployed LLM corpus resources: GET /llms-full.txt and GET /llms-full.sha256. Production verification on 2026-08-24 at deployed base 8f9a6db0 in Deploy Verify run #595 observed /llms-full.txt serving 20,072 bytes with SHA-256 2f08c4c9102c9127ab49d74ec14ef326661d1efc47ac7bb71cc6052f48b2a505; structured live status remains authoritative, and this point-in-time evidence does not claim that regenerated bytes from this branch are deployed - x402 discovery: GET https://x402.agoragentic.com/.well-known/x402.json and GET https://x402.agoragentic.com/services/index.json for configured slugs; only after GET /market.json reports paid execution enabled, choose https://x402.agoragentic.com/v1/{slug} for network `base` or https://x402.agoragentic.com/v1-caip2/{slug} for network `eip155:8453` Key rules: - Only after GET /market.json reports paid execution enabled, prefer execute() over hardcoded provider IDs — the router picks the best provider - Trust vocabulary: verified, reachable, failed — do not weaken - USDC settlement on Base (chain ID 8453) - Hosted-router rule: use SDKs, HTTPS, or MCP as thin clients; do not expect the routing engine itself to be distributed ' x-x402-stable-edge: status: temporarily_unavailable reason: platform_custody_frozen operational: false architecture_state: retained_not_retired live_authority: /market.json gate_rule: Do not call or retry a paid edge route unless /market.json reports paid execution enabled. slug_catalog: https://x402.agoragentic.com/services/index.json canonical_base_resource_template: https://x402.agoragentic.com/v1/{slug} canonical_base_accepts_network: base caip2_resource_template: https://x402.agoragentic.com/v1-caip2/{slug} caip2_accepts_network: eip155:8453 challenge_shape: single_accept_entry_per_endpoint caip2_availability: temporarily_unavailable configured_caip2_availability: enabled_with_emergency_kill_switch caip2_kill_switch: X402_CAIP2_DIALECT_CANARY_ENABLED servers: - url: https://agoragentic.com/api description: Production (Base Mainnet) tags: - name: Agent OS Finance paths: /agent-os/finance/deployments/{deployment_id}/connectors: get: operationId: get_api_agent_os_finance_deployments_by_deployment_id_connectors tags: - Agent OS Finance summary: Read finance-agent connector status description: Owner/admin read-only route for redacted Robinhood trading, Robinhood banking/card, and financial-research connector status. Robinhood connector object shapes are documented by /schema/robinhood-agent-os-connector.v1.json. Connector status list responses are shaped by /schema/finance-agent-connector-status-list.v1.json, and each embedded Robinhood MCP connection is shaped by /schema/finance-agent-mcp-connection-status.v1.json. This does not dispatch providers, trade, fetch card details, spend, settle, publish, or enable execute/invoke. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Redacted connector status with forced disabled live-action flags '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/robinhood/mcp-connections: get: operationId: get_api_agent_os_finance_deployments_by_deploym_f2e7b67b5a16c0fe tags: - Agent OS Finance summary: Read Robinhood MCP connection records description: Owner/admin read-only route for deployment-scoped Robinhood MCP connection records, each shaped by /schema/finance-agent-mcp-connection-status.v1.json. Returns trading and banking/card connector refs, official MCP endpoint names, status, vault/connection refs, stop-control state, timestamps, and safe status JSON only. This does not start OAuth, store OAuth tokens, call Robinhood MCP tools, fetch account/card/order payloads, dispatch providers, trade, fetch card details, make purchases, mutate wallet/x402, execute/invoke, publish listings, or publish capabilities. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Deployment-scoped Robinhood MCP connection records with forced-false live-action flags '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/robinhood/mcp-connections/{connector_type}/attach: post: operationId: post_api_agent_os_finance_deployments_by_deploy_6777ff36c578b9e6 tags: - Agent OS Finance summary: Attach existing Robinhood MCP vault refs description: Owner/admin write route that records existing owner-managed vault and connection refs for a deployment-scoped Robinhood MCP connection. Requires `write:true`, `idempotency_key`, `vault_secret_ref`, and `connection_ref`; records `status:"connected"` and `stop_control_state:"active"` with receipt/audit evidence only. It rejects raw token/private fields and unsafe ref values, constructs forced-false safe status JSON locally, and does not start OAuth, store OAuth tokens, follow provider required_next_action data, call Robinhood MCP tools, fetch account/card/order payloads, dispatch providers, trade, fetch card details, make purchases, mutate wallet/x402, execute/invoke, publish listings, or publish capabilities. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: connector_type in: path required: true schema: type: string enum: - robinhood_trading - robinhood_banking - trading - banking requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key - vault_secret_ref - connection_ref properties: write: type: boolean const: true idempotency_key: type: string vault_secret_ref: type: string maxLength: 256 description: Ref to owner-managed vault secret. Raw tokens, credentials, auth redirects, and private payloads are rejected. connection_ref: type: string maxLength: 256 description: Public-safe connection ref or hash. Raw provider payloads, account/card/order/payment/wallet values, and token-looking values are rejected. status_summary_ref: type: string maxLength: 256 description: Optional bounded public-safe status evidence ref; raw/private values are not stored. note: type: string maxLength: 256 description: Optional bounded public-safe owner note; raw/private values are not stored. responses: '201': description: Local connected state receipt: null safe status JSON: null and forced-false live-action flags: null '400': description: Missing refs missing idempotency key: null write flag: null invalid connector type: null unsafe ref: null or forbidden private/live-action field: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/robinhood/mcp-connections/{connector_type}/stop: post: operationId: post_api_agent_os_finance_deployments_by_deploy_9e7e4f7ccb143786 tags: - Agent OS Finance summary: Record Robinhood MCP connection stop state description: Owner/admin write route that records a local stop-control state for a deployment-scoped Robinhood MCP connection. Requires `write:true` and `idempotency_key`; creates receipt/audit evidence only. It does not start OAuth, call Robinhood MCP tools, fetch account/card/order payloads, dispatch providers, trade, fetch card details, make purchases, mutate wallet/x402, execute/invoke, publish listings, or publish capabilities. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: connector_type in: path required: true schema: type: string enum: - robinhood_trading - robinhood_banking - trading - banking requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key properties: write: type: boolean const: true idempotency_key: type: string reason: type: string maxLength: 256 description: Optional bounded public-safe owner reason. Tokens, credentials, and raw/private payload-looking values are not stored. responses: '200': description: Local stop state receipt: null safe status JSON: null and forced-false live-action flags: null '400': description: Missing idempotency key write flag: null invalid connector type: null or forbidden private/live-action field: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/robinhood/mcp-connections/{connector_type}/disconnect: post: operationId: post_api_agent_os_finance_deployments_by_deploy_c70efb235a3f897b tags: - Agent OS Finance summary: Record Robinhood MCP connection disconnect state description: Owner/admin write route that records a local disconnected stop-control state and clears stored vault/connection refs for a deployment-scoped Robinhood MCP connection. Requires `write:true` and `idempotency_key`; creates receipt/audit evidence only. It does not start OAuth, call Robinhood MCP tools, fetch account/card/order payloads, dispatch providers, trade, fetch card details, make purchases, mutate wallet/x402, execute/invoke, publish listings, or publish capabilities. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: connector_type in: path required: true schema: type: string enum: - robinhood_trading - robinhood_banking - trading - banking requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key properties: write: type: boolean const: true idempotency_key: type: string reason: type: string maxLength: 256 description: Optional bounded public-safe owner reason. Tokens, credentials, and raw/private payload-looking values are not stored. responses: '200': description: Local disconnect state cleared refs: null receipt: null safe status JSON: null and forced-false live-action flags: null '400': description: Missing idempotency key write flag: null invalid connector type: null or forbidden private/live-action field: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/robinhood/live-read-beta/status: get: operationId: get_api_agent_os_finance_deployments_by_deploym_e8b5372d86c9605a tags: - Agent OS Finance summary: Read Robinhood live-read beta status description: Owner/admin read-only route for Robinhood live-read beta readiness, connector stop state, policy enablement, schema-proof presence, data-minimization evidence, stop-control drill evidence, and non-secret transport/resolver configuration booleans. It never calls Robinhood, never follows provider required_next_action data, and exposes no private account, banking, card, balance, position, transaction, order, credential, wallet, x402, execute/invoke, marketplace, or capability payloads. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Redacted live-read beta readiness/status summary '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/robinhood/live-read-beta/schema: get: operationId: get_api_agent_os_finance_deployments_by_deploym_d2601ada894d8cfb tags: - Agent OS Finance summary: Read Robinhood live-read beta schema summary description: Owner/admin read-only route for redacted Robinhood live-read beta tool mapping. Returns local allowlisted read tools, read scopes, stored schema-proof refs, and blocked tool families only. Raw MCP schemas, provider payloads, credentials, account/card/order values, provider required_next_action payloads, and route authority grants are excluded. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Redacted schema/tool mapping summary '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/robinhood/live-read-beta/read-preview: post: operationId: post_api_agent_os_finance_deployments_by_deploy_dc06ae15cc749300 tags: - Agent OS Finance summary: Preview Robinhood live-read beta eligibility description: Owner/admin preview route that evaluates connection, policy, schema-proof, data-minimization, receipt, stop-control, redaction, and read-tool gates without calling Robinhood. Action tool families remain blocked, including order placement/cancel/review, card credential fetch, approval waits, purchases, options, wallet/x402, public execute/invoke, marketplace, and capability publication. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: connector_type: type: string enum: - robinhood_trading - robinhood_banking - trading - banking tool_name: type: string arguments: type: object additionalProperties: true responses: '200': description: Preview decision with blockers and no Robinhood call '400': description: Invalid connector/tool/arguments or private/live-action field '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/robinhood/live-read-beta/reads: post: operationId: post_api_agent_os_finance_deployments_by_deploy_04139fa5a8284bf5 tags: - Agent OS Finance summary: Perform gated Robinhood live-read beta call description: Owner/admin write route that may call only allowlisted Robinhood MCP read tools after connection, policy, schema-proof, data-minimization, receipt, stop-control, Agent Trap, redaction, and transport/vault resolver gates pass. Requires write:true and idempotency_key. Returns only redacted/hash summaries and writes a redacted receipt with live-read summary shape governed by /schema/finance-agent-robinhood-live-read-beta-receipt-summary.v1.json. Banking status, policy, balance, and transaction reads remain private and are summarized coarsely only. Provider required_next_action data and provider/MCP metadata text are treated as untrusted provider output and cannot override policy, local allowlists, or stop state. Production dispatch is opt-in through a vault-ref resolver and Streamable HTTP transport. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key - connector_type - tool_name properties: write: type: boolean const: true idempotency_key: type: string connector_type: type: string enum: - robinhood_trading - robinhood_banking - trading - banking tool_name: type: string arguments: type: object additionalProperties: true responses: '201': description: Redacted live-read result summary and finance_agent_robinhood_live_read_beta receipt '400': description: Gate blocked disabled/stopped connector: null blocked tool family: null unsafe args: null schema-proof trap metadata: null missing write/idempotency: null or redaction failure: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin '503': description: Live-read transport not configured /agent-os/finance/deployments/{deployment_id}/robinhood/live-read-beta/stop: post: operationId: post_api_agent_os_finance_deployments_by_deploy_775c147a43cedd89 tags: - Agent OS Finance summary: Stop Robinhood live-read beta dispatch description: Owner/admin write route that records local stop-control state for Robinhood live-read beta dispatch. Requires write:true and idempotency_key. It calls no Robinhood MCP tools and blocks future beta reads through the same deployment-scoped MCP connection stop state used by the finance control plane. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key properties: write: type: boolean const: true idempotency_key: type: string connector_type: type: string enum: - robinhood_trading - robinhood_banking - trading - banking reason: type: string maxLength: 256 responses: '200': description: Local stop-control records and redacted receipts '400': description: Missing write/idempotency invalid connector: null or forbidden private/live-action field: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/policy: get: operationId: get_api_agent_os_finance_deployments_by_deployment_id_policy tags: - Agent OS Finance summary: Read finance-agent policy description: Reads the stored owner-approved finance policy for a deployment, or the disabled-by-default policy when no policy record exists. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Finance policy plus no-live-action mutation flags '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin put: operationId: put_api_agent_os_finance_deployments_by_deployment_id_policy tags: - Agent OS Finance summary: Store owner-approved finance policy description: Stores a finance-agent policy record only. Requires `write:true` and `idempotency_key`; rejects private credential/account/card/order/payment-like fields plus route/runtime authority aliases even when set false, and does not dispatch providers, trade, fetch cards, spend, settle, publish, or enable execute/invoke. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key properties: write: type: boolean const: true idempotency_key: type: string policy: type: object description: Finance Agent Policy V1 payload. See /schema/finance-agent-policy.v1.json. responses: '200': description: Stored finance policy record and redacted connector status '400': description: Missing idempotency key write flag: null or forbidden private/live-action field: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/readiness-proofs: post: operationId: post_api_agent_os_finance_deployments_by_deploy_8257803313b6b871 tags: - Agent OS Finance summary: Create finance-agent no-action readiness proof description: Creates a launch-mode readiness proof and redacted receipt/evidence references from selected launch mode, connector status summary, finance policy, redacted MCP schema proof, compliance approval evidence, requested caps, and approval mode. `approved_trading` and `approved_card` cannot pass on missing, unauthenticated, auth-required, schema-pending, or flag-only MCP probe status; they require `owner_authenticated_mcp_schema_probe` evidence matching `/schema/finance-agent-mcp-schema-proof.v1.json` plus `finance_agent_owner_legal_commercial_approval` evidence matching `/schema/finance-agent-compliance-approval.v1.json`, including forced-false provider-dispatch, live-read-route, execution, publication, and x402 approval flags. Strict stored MCP schema-proof and compliance-approval records can satisfy those evidence inputs for later readiness proofs, and stored MCP proof outputs carry evidence-only provenance markers with `route_schema_probe_performed:false` and `route_schema_probe_verified:false`. This is evidence-only and performs no Robinhood MCP probe, live-read route creation, provider dispatch, trading, card fetch, wallet spend, x402 settlement, listing publication, or capability publication. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key properties: write: type: boolean const: true idempotency_key: type: string launch_mode: type: string enum: - research_only - order_review - research_plus_order_review - approved_trading - research_plus_approved_trading - approved_card - research_plus_approved_trading_and_approved_card - options connector_status_summary: type: object additionalProperties: true description: Public-safe connector status summary only; private account/card/order/provider values are rejected. finance_policy: type: object additionalProperties: true description: Finance policy summary or policy payload; private credentials/account/card/order-like fields and route/runtime authority aliases are rejected even when false. mcp_probe_status: type: object additionalProperties: true description: Redacted MCP schema-proof evidence only. Approved trading/card readiness requires /schema/finance-agent-mcp-schema-proof.v1.json shape with bounded redacted refs/hashes and evidence-only provenance markers, not raw URL/token-looking evidence values; the route does not run an MCP probe. compliance_approval: type: object additionalProperties: true description: Redacted owner/legal/commercial/compliance approval evidence only. Approved trading/card readiness requires /schema/finance-agent-compliance-approval.v1.json shape with bounded redacted refs/hashes and forced-false live_read_route_approved, route_can_create_live_read_route, provider/execution/publication/x402 flags, not raw URL/token-looking approval values. C1 options-review evidence may use options_signal_intelligence or options_review_packet scope with brokerage-options approval refs/hashes, but the route cannot approve live-read routes, route authority, live actions, or options execution. requested_caps: type: object additionalProperties: true description: Requested notional, purchase, merchant, open-order, and approval-mode caps. approval_mode: type: string responses: '201': description: No-action readiness proof with readiness_proof_id status: null launch_mode: null connector_summary: null policy_summary: null approval_summary: null compliance_approval_summary: null receipt_summary: null stop_control_summary: null options_status disabled_roadmap: null no_live_action_assertion true: null and redacted finance-agent receipt: null '400': description: Missing idempotency key write flag: null or forbidden private/live-action field: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/mcp-schema-proofs: post: operationId: post_api_agent_os_finance_deployments_by_deploy_ba53d8fb2405467b tags: - Agent OS Finance summary: Record finance-agent MCP schema proof evidence description: Owner/admin evidence-write route that records a redacted owner-authenticated Robinhood MCP schema-proof artifact for one connector. Requires `write:true`, `idempotency_key`, `live_read_route_created:false`, and `route_can_create_live_read_route:false`; rejects flag-only, auth-required, schema-pending, off-endpoint, raw-schema, private-payload, raw URL/token-looking evidence refs/hashes, live-read-route creation evidence, route-authority grants, live-action evidence, and route/platform probe-run or probe-verification provenance claims. Stored proof, connector, tool-summary, probe-status, and readiness-from-stored-evidence outputs emit `evidence_origin:"external_owner_supplied_redacted_attestation"`, `recording_route_scope:"record_evidence_only"`, `route_schema_probe_performed:false`, and `route_schema_probe_verified:false`. This route creates evidence/receipt/audit records only and performs no Robinhood MCP probe, live-read route creation, route-authority grant, provider dispatch, trading action, card action, wallet mutation, x402 settlement, listing publication, or capability publication. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key properties: write: type: boolean const: true idempotency_key: type: string connector_type: type: string enum: - robinhood_trading - robinhood_banking - trading - banking mcp_probe_status: type: object additionalProperties: true description: Redacted proof matching /schema/finance-agent-mcp-schema-proof.v1.json for the selected connector. Evidence refs/hashes must be bounded redacted artifact IDs or hashes, not raw URLs, tokens, credentials, or payloads, and the proof must carry live_read_route_created:false and route_can_create_live_read_route:false with the other forced-false live-action flags. Optional provenance fields are constrained to owner-supplied evidence-only markers with route_schema_probe_performed:false and route_schema_probe_verified:false. responses: '201': description: MCP schema-proof record with proof_id connector_summary: null receipt/evidence refs: null no_live_action_assertion true: null evidence-only provenance markers: null and forced-false mutation flags: null '400': description: Missing idempotency key write flag: null connector type: null invalid proof: null raw/private evidence ref or hash: null forbidden private field: null or live-action field: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/compliance-approvals: post: operationId: post_api_agent_os_finance_deployments_by_deploy_b219e7d91252052a tags: - Agent OS Finance summary: Record finance-agent compliance approval evidence description: Owner/admin evidence-write route that records redacted owner/legal/commercial/compliance approval evidence for no-action finance-agent readiness, including scoped C1 options_signal_intelligence/options_review_packet brokerage-options review approval refs/hashes. Requires `write:true`, `idempotency_key`, `live_read_route_approved:false`, and `route_can_create_live_read_route:false`; the approval must match /schema/finance-agent-compliance-approval.v1.json, carry forced-false live_read_route_approved, route_can_create_live_read_route, provider/execution/publication/x402 flags, and use bounded redacted refs/hashes rather than raw URL/token-looking approval values. Options-review approval evidence also requires a strict stored Robinhood trading MCP schema-proof record for the deployment and the exact `required_external_gates:["owner_approval_required","compliance_review_required","brokerage_options_approval_required","mcp_schema_proof_required"]` list. This route cannot approve live-read route creation, route authority, live actions, provider dispatch, order execution/cancellation, card detail fetch, purchases, options execution, Fincept runtime integration, public claims, marketplace publication, x402 settlement, wallet mutation, execute, or invoke. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key properties: write: type: boolean const: true idempotency_key: type: string compliance_approval: type: object additionalProperties: true description: Redacted approval evidence matching /schema/finance-agent-compliance-approval.v1.json. Known approval/evidence/review/receipt/brokerage refs and hashes must be bounded redacted artifact IDs or hashes, not raw URLs, tokens, credentials, raw JSON payloads, or account/card/payment/wallet values. The approval must carry live_read_route_approved:false and route_can_create_live_read_route:false along with the other forced-false provider/execution/publication/x402 approval flags. options_signal_intelligence/options_review_packet scopes require no-action options-review acknowledgements, brokerage-options approval refs/hashes, the exact required_external_gates list, and a strict stored Robinhood trading MCP schema-proof record for the deployment. responses: '201': description: Compliance approval record with approval_id approval_summary: null receipt/evidence refs: null no_live_action_assertion true: null and forced-false mutation flags: null '400': description: Missing idempotency key write flag: null invalid approval: null missing stored trading MCP schema proof for options-review approval evidence: null raw/private evidence ref or hash: null forbidden private field: null or live-action field: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/gate-evidence-records: post: operationId: post_api_agent_os_finance_deployments_by_deploy_8cbf5a4e60cbe2ee tags: - Agent OS Finance summary: Record finance-agent supporting gate evidence refs description: 'Owner/admin evidence-write route that records redacted refs/hashes for supporting Version C packet artifacts: external-gate bundle, owner approval checklist, stop-control drill, or data-minimization plan. Local owner-evidence intake/preflight packets and reports are documented by /schema/finance-agent-owner-evidence-intake-pack.v1.json, /schema/finance-agent-owner-evidence-packet.v1.json, and /schema/finance-agent-owner-evidence-preflight-report.v1.json before refs are recorded, with preflight reports exposing packet/intake subject hashes, queryable item/action summary counts, completion audit rows for remaining external gates, allowed proof sources, redacted ref/hash keys, forbidden payload refs, owner actions, an ordered next owner action plan, and server_route_capability_primary_blocker:false, a top-level external gate blocker summary for launch modes, evidence families, proof sources, local unresolved items, and next owner actions, launch-mode owner review dossier rows for required evidence gates, record routes, proof sources, review roles, and action-plan IDs, route payload redaction checklist rows for required refs, accepted schema refs, required false flags, write/idempotency markers, and owner-reviewed PR-only evidence, a report-level query index, collection frontier IDs, route recording-plan groups, mode evidence gate summaries with mode collection frontier IDs and unsatisfied item status/action/finding-code details, evidence-family summaries, dependency graph edges, a top-level finding-code summary, per-item evidence gate statuses with blocker/warning finding-code arrays, unsatisfied precondition IDs, and next required actions. Requires `write:true` and `idempotency_key`; the record is shaped by /schema/finance-agent-gate-evidence-record.v1.json and stores bounded artifact refs/hashes rather than raw packet payloads, raw URLs, tokens, credentials, or private finance data. For `data_minimization_plan` only, the route preserves bounded `evidence_summary.allowed_read_categories`, `allowed_output_field_families`, and `excluded_private_data_families` labels for live-read beta gating; raw/private families are forced false or excluded, and no raw Robinhood payload is stored. Supporting authority metadata rejects non-canonical route/runtime authority aliases even when set false. This route creates evidence/receipt/audit records only, does not satisfy MCP/compliance hard gates by itself, and cannot create live-read routes, run Robinhood MCP probes, dispatch providers, approve live actions, enable options execution, mutate wallet/x402 state, publish listings/capabilities, execute, or invoke.' security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key - gate_evidence properties: write: type: boolean const: true idempotency_key: type: string gate_evidence: type: object required: - evidence_kind - schema_ref - artifact_ref - artifact_hash - no_live_action_assertion properties: evidence_kind: type: string enum: - external_gate_bundle - owner_approval_checklist - stop_control_drill - data_minimization_plan schema_ref: type: string enum: - /schema/finance-agent-external-gate-bundle.v1.json - /schema/finance-agent-owner-approval-checklist.v1.json - /schema/finance-agent-stop-control-drill.v1.json - /schema/finance-agent-data-minimization-plan.v1.json artifact_ref: type: string maxLength: 256 description: Bounded redacted artifact ID/ref only; raw URLs, tokens, credentials, and private payloads are rejected. artifact_hash: type: string maxLength: 256 no_live_action_assertion: type: boolean const: true required_false_authority: type: object additionalProperties: true description: Optional forced-false authority map. Any true value is rejected. evidence_summary: type: object description: Optional data_minimization_plan-only bounded summary. The route preserves only allowlisted read-category booleans, output-family booleans, and excluded private-family labels needed by live-read beta gates; raw values, provider payloads, credentials, tokens, account/card/order/payment/wallet values, and live-authority fields are rejected or omitted. additionalProperties: true responses: '201': description: Gate evidence record with record_id evidence_kind: null reviewed_schema_ref: null receipt/evidence refs: null optional bounded data-minimization summary labels: null no_live_action_assertion true: null and forced-false mutation flags: null '400': description: Missing idempotency key write flag: null invalid kind: null schema mismatch: null raw/private evidence ref/hash: null forbidden private field: null or live-authority assertion: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/readiness-requirements: get: operationId: get_api_agent_os_finance_deployments_by_deploym_6c64559f636eee7d tags: - Agent OS Finance summary: Read finance-agent readiness requirements description: Owner/admin read-only route that returns a top-level response shaped by /schema/finance-agent-readiness-requirements.v1.json with mode-by-mode finance-agent readiness requirements, blockers, required external evidence schema links including /schema/finance-agent-gate-evidence-record.v1.json, /schema/finance-agent-external-gate-bundle.v1.json, /schema/finance-agent-owner-approval-checklist.v1.json, /schema/finance-agent-stop-control-drill.v1.json, /schema/finance-agent-data-minimization-plan.v1.json, /schema/finance-agent-options-paper-simulation.v1.json, and /schema/finance-agent-options-paper-review-packet.v1.json, latest stored external-gate status, owner_evidence_route_payload_checklist rows for MCP schema-proof, compliance-approval, supporting gate-evidence, and owner-reviewed implementation-PR payload requirements, a queryable nested Version C gate matrix shaped by /schema/finance-agent-version-c-gate-matrix.v1.json and keyed by launch mode and hard external gate, legacy next safe action strings plus structured next-safe-action contracts with sequence indexes and dependency action IDs, and forced-false live-authority flags. This creates no readiness proof, receipt, audit event, Robinhood MCP probe, provider dispatch, trading action, card action, options execution, wallet mutation, x402 settlement, listing publication, or capability publication. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Read-only readiness requirements response shaped by /schema/finance-agent-readiness-requirements.v1.json for research_only order_review: null approved_trading: null approved_card: null roadmap-only options: null options_signal_intelligence metadata: null C1 no-action options_review_packet contract flags: null route-free options paper simulation/review packet schema refs: null owner evidence route payload checklist rows: null structured next-safe-action contracts: null scoped compliance-approval gate status: null and nested version_c_gate_matrix summaries: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/version-c-audit-map: get: operationId: get_api_agent_os_finance_deployments_by_deploym_af8699de3bcf88e7 tags: - Agent OS Finance summary: Read finance-agent Version C audit map description: Owner/admin read-only route that returns a top-level response shaped by /schema/finance-agent-version-c-audit-map.v1.json with schema refs, launch modes, hard external gates, C1 options review packet contract with route-free paper simulation/review packet schema refs, owner evidence route payload checklist rows, owner approval packet requirements, blocked owner-gate example template refs, connector-specific trading/banking MCP proof state, owner-packet and mode-specific next safe actions with preconditions, sequence indexes, and dependency action IDs, mode-scoped approved-trading/approved-card owner-approval evidence refs, required evidence-ref fields, records-evidence-only flags, forced-false route-authority flags, current Version C gate-matrix mode status, boundary flags, remaining external owner/compliance/brokerage evidence gaps, and separately classified roadmap-disabled blockers. This creates no readiness proof, receipt, audit event, Robinhood MCP probe, provider dispatch, live-read route, order/card/options action, wallet mutation, x402 settlement, execute/invoke mutation, listing publication, or capability publication. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Read-only Version C audit-map response shaped by /schema/finance-agent-version-c-audit-map.v1.json for launch-mode status hard external gates: null connector-specific MCP proof state: null options-review packet requirements: null route-free paper simulation/review packet schema refs: null owner evidence route payload checklist rows: null owner approval packet requirements: null blocked owner-gate example template refs: null next safe action preconditions: null sequence indexes: null dependency action IDs: null mode-scoped approved-trading/approved-card owner-approval evidence refs: null required evidence-ref fields: null forced-false route authority: null current blockers: null remaining external evidence gaps: null and roadmap-disabled blockers: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/research-agent/status: get: operationId: get_api_agent_os_finance_deployments_by_deploym_c24c2c4cf744381f tags: - Agent OS Finance summary: Read private Finance Research Agent V1 status description: Owner/admin read-only status for the financial_research_agent deployment template, production dependency configuration, approved-domain count, policy decision, and owner-scoped run counts. This route performs no source, inference, Robinhood, brokerage, order, card, purchase, wallet, x402, execute/invoke, marketplace, or capability call or mutation. live_deliverable remains false until a separately recorded production canary and deliberate contract update. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Private owner-scoped status with forced-false live authority and production-canary-required delivery state '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/research-agent/preview: post: operationId: post_api_agent_os_finance_deployments_by_deploy_4b9b39aca5001656 tags: - Agent OS Finance summary: Preview a Finance Research Agent V1 run with zero calls and writes description: Owner/admin validation and deterministic plan preview for public-source finance research. Preview performs no source search, safe fetch, inference, Robinhood call, brokerage dispatch, or database write. It returns explicit blockers, a non-executable plan, and forced-false live authority. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - research_question anyOf: - required: - ticker - required: - company properties: owner_id: type: string description: Admin-only owner scope override ticker: type: string pattern: ^[A-Z0-9][A-Z0-9.-]{0,14}$ company: type: string maxLength: 160 research_question: type: string minLength: 10 maxLength: 1000 time_horizon: type: string maxLength: 160 risk_focus: oneOf: - type: string maxLength: 160 - type: array maxItems: 8 items: type: string maxLength: 160 max_sources: type: integer minimum: 1 maximum: 8 responses: '200': description: Zero-call zero-write eligibility preview with deterministic research plan and blockers: null '400': description: Invalid private: null personalized-advice: null or execution-oriented research input: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/research-agent/runs: post: operationId: post_api_agent_os_finance_deployments_by_deploy_4c46a3545c985d06 tags: - Agent OS Finance summary: Start an idempotent private Finance Research Agent V1 run description: Owner/admin run route shaped by /schema/finance-research-agent-run-request.v1.json and /schema/finance-research-agent-run-response.v1.json. Requires write:true and idempotency_key. After deployment, finance-policy, dependency-ref, and approved-domain gates pass, it may call only the configured public-source search provider, the shared hardened safe-fetch path, and the configured structural inference provider. Search metadata, fetched content, and model output are Agent Trap scanned. Citations, timestamps, content hashes, and numeric claims are validated; unsupported numeric claims are omitted and disclosed as missing data. Only bounded public-safe summaries, refs, hashes, citations, status, artifacts, and receipts are persisted. Robinhood is not required or imported, candidate actions are always non-executable, and all brokerage/order/card/purchase/options/wallet/x402/public execute/invoke/publication authority remains false. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write - idempotency_key - research_question anyOf: - required: - ticker - required: - company properties: write: type: boolean const: true idempotency_key: type: string minLength: 1 maxLength: 256 owner_id: type: string description: Admin-only owner scope override ticker: type: string pattern: ^[A-Z0-9][A-Z0-9.-]{0,14}$ company: type: string maxLength: 160 research_question: type: string minLength: 10 maxLength: 1000 time_horizon: type: string maxLength: 160 risk_focus: oneOf: - type: string maxLength: 160 - type: array maxItems: 8 items: type: string maxLength: 160 max_sources: type: integer minimum: 1 maximum: 8 responses: '200': description: Idempotent replay of the existing owner-scoped run without duplicate provider calls or receipt '201': description: New queued running: null completed: null blocked: null failed: null or stopped research run with redacted sources and forced-false live authority: null '400': description: Missing write/idempotency invalid/private input: null personalized advice: null or execution request: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/research-agent/runs/{run_id}: get: operationId: get_api_agent_os_finance_deployments_by_deploym_a3f7fa878d179eab tags: - Agent OS Finance summary: Read a private Finance Research Agent V1 run description: Reads an owner-scoped run shaped by /schema/finance-research-agent-run-response.v1.json. Raw provider payloads and raw source content are excluded. This route has no provider or Robinhood side effects. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string responses: '200': description: Redacted owner-scoped research run citations: null source summaries: null and forced-false authority: null '401': description: Missing owner/admin authentication '404': description: Deployment or run not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/research-agent/runs/{run_id}/stop: post: operationId: post_api_agent_os_finance_deployments_by_deploy_50c9e605ef300e0c tags: - Agent OS Finance summary: Stop a private Finance Research Agent V1 run description: Owner/admin stop-control route requiring write:true and idempotency_key. It records stop_requested and atomically blocks the next source-search, source-fetch, or inference dispatch stage. It does not call a source, model, Robinhood, brokerage, order, card, wallet, x402, execute/invoke, marketplace, or capability surface. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: run_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write - idempotency_key properties: write: type: boolean const: true idempotency_key: type: string minLength: 1 maxLength: 256 owner_id: type: string description: Admin-only owner scope override responses: '200': description: Redacted stopped run with forced-false live authority '400': description: Missing write or idempotency key '401': description: Missing owner/admin authentication '404': description: Deployment or run not found for authenticated owner/admin /agent-os/finance/research-agent/receipts/{receipt_id}: get: operationId: get_api_agent_os_finance_research_agent_receipts_by_receipt_id tags: - Agent OS Finance summary: Read a redacted Finance Research Agent V1 receipt description: Owner/admin read route shaped by /schema/finance-research-agent-receipt.v1.json. The receipt truthfully records public research source/inference calls and includes only provider refs, source count/domains, artifact hash, confidence, zero cost, timestamps, redaction assertions, and forced-false Robinhood/brokerage/order/card/purchase/options/wallet/x402/execute/invoke/publication authority. Raw provider payloads and raw source content are excluded. security: - ApiKeyAuth: [] parameters: - name: receipt_id in: path required: true schema: type: string responses: '200': description: Owner-scoped redacted Finance Research Agent V1 receipt '401': description: Missing owner/admin authentication '404': description: Receipt not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/research-agent/alerts/status: get: operationId: get_api_agent_os_finance_deployments_by_deploym_b7e725ecad09f1cd tags: - Agent OS Finance summary: Read Finance Research Alert Agent readiness description: Owner/admin-only readiness for platform-managed AWS Bedrock inference, ref-only delivery channels, the UTC scheduler, and recipient-confirmed channel-bound canary proof. live_deliverable is true only when research policy/dependencies, at least one approved public research domain, delivery, an active schedule, the scheduler, the exact canonical destination alias and current redacted binding for every scheduled channel, and an explicitly confirmed successful canary for every channel used by an active schedule all pass. latest_successful_canary_receipt_id is current-proof only and is null unless that canary was confirmed and its current alias and redacted binding still verify. The scheduler remains disabled unless delivery and a destination-secret resolver are configured. Status performs a bounded vault-secret read but returns and stores no raw destination. Scheduled dispatch enforces the same channel-bound proof before research and before transport. The friend does not need an LLM account or key. No Robinhood, broker, order, card, purchase, options, wallet, x402, public execute/invoke, marketplace, or capability authority is granted. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Status shaped by /schema/finance-research-alert-status.v1.json content: application/json: schema: $ref: ./schema/finance-research-alert-status.v1.json '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/research-agent/alerts/channels: get: operationId: get_api_agent_os_finance_deployments_by_deploym_f5eb19f2b10a4956 tags: - Agent OS Finance summary: List Finance Research Alert delivery channels description: Returns owner-scoped channel metadata and vault/secret references only. Raw email addresses, webhook URLs, authorization headers, and provider responses are never returned. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Owner-scoped channel-list response content: application/json: schema: $ref: ./schema/finance-research-alert-channel-list.v1.json '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin post: operationId: post_api_agent_os_finance_deployments_by_deploy_4b5e64cbc543f97e tags: - Agent OS Finance summary: Register a ref-only Finance Research Alert delivery channel description: Stores only a vault/Secrets Manager reference and its hash. This configuration-only route does not resolve the secret, send an alert, call research providers, or call Robinhood. Inline destinations and credentials are rejected. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 256 description: Canonical idempotency key; required here or as idempotency_key in the JSON body. - name: X-Idempotency-Key in: header required: false deprecated: true schema: type: string minLength: 1 maxLength: 256 description: Deprecated compatibility alias for Idempotency-Key. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write - channel_type - label - destination_secret_ref properties: write: const: true idempotency_key: type: string minLength: 1 maxLength: 256 description: Required when Idempotency-Key and X-Idempotency-Key headers are absent. owner_id: type: string description: Admin-only owner scope override channel_type: type: string enum: - email - webhook - slack - discord label: type: string minLength: 1 maxLength: 80 destination_secret_ref: type: string maxLength: 256 pattern: ^vault:finance-alerts/[A-Za-z0-9][A-Za-z0-9_-]{0,159}/[a-z0-9][a-z0-9_-]{0,63}$ description: Deployment-bound logical vault ref; direct secret names ARNs: null destinations: null and credentials are rejected.: null responses: '200': description: Idempotent replay content: application/json: schema: $ref: ./schema/finance-research-alert-channel-response.v1.json '201': description: Channel reference recorded without provider or delivery calls content: application/json: schema: $ref: ./schema/finance-research-alert-channel-response.v1.json '400': description: Invalid input inline destination: null credential: null secret reference: null or conflicting Idempotency-Key/X-Idempotency-Key/body values: null '401': description: Missing owner/admin authentication '403': description: Authenticated owner does not own the deployment or requested owner scope /agent-os/finance/deployments/{deployment_id}/research-agent/alerts/channels/{channel_id}/stop: post: operationId: post_api_agent_os_finance_deployments_by_deploy_c456851c2cd5c04d tags: - Agent OS Finance summary: Stop a Finance Research Alert channel and its schedules description: Serializes with schedule mutation and final dispatch, marks the owner-scoped channel stopped, stops active or paused schedules, and terminalizes non-dispatch processing receipts. A send already inside bounded transport is allowed to finish before this route returns; after a successful stop response no new send can start and no processing receipt remains reclaimable. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: channel_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 256 description: Canonical idempotency key; required here or in the JSON body. - name: X-Idempotency-Key in: header required: false deprecated: true schema: type: string minLength: 1 maxLength: 256 description: Deprecated compatibility alias. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write properties: write: const: true idempotency_key: type: string minLength: 1 maxLength: 256 description: Required when idempotency headers are absent. owner_id: type: string description: Admin-only owner scope override responses: '200': description: Channel and dependent schedules stopped; no new outbound call starts after this response content: application/json: schema: $ref: ./schema/finance-research-alert-channel-response.v1.json '401': description: Missing owner/admin authentication '403': description: Authenticated owner does not own the deployment or requested owner scope '404': description: Deployment or channel not found /agent-os/finance/deployments/{deployment_id}/research-agent/alerts/schedules: get: operationId: get_api_agent_os_finance_deployments_by_deploym_8487c44e022296d0 tags: - Agent OS Finance summary: List Finance Research Alert schedules description: Returns owner-scoped hourly, daily, or weekly UTC schedules and normalized public-research requests. No provider or delivery call is performed. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Owner-scoped schedule-list response content: application/json: schema: $ref: ./schema/finance-research-alert-schedule-list.v1.json '401': description: Missing owner/admin authentication '404': description: Deployment not found post: operationId: post_api_agent_os_finance_deployments_by_deploy_5fe637778bcacb3c tags: - Agent OS Finance summary: Create a Finance Research Alert schedule description: Creates an idempotent UTC schedule against an active delivery channel. An exact idempotency-key and request replay returns the original schedule even if that channel was later stopped; new schedules still require an active channel. Successful work advances from actual completion time to the first future anchored slot. This configuration-only route performs no source, inference, delivery, or Robinhood call. Research input remains public-source, non-personalized, and non-executable. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 256 description: Canonical idempotency key; required here or in the JSON body. - name: X-Idempotency-Key in: header required: false deprecated: true schema: type: string minLength: 1 maxLength: 256 description: Deprecated compatibility alias. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write - channel_id - cadence - research_request properties: write: const: true idempotency_key: type: string minLength: 1 maxLength: 256 description: Required when idempotency headers are absent. owner_id: type: string description: Admin-only owner scope override channel_id: type: string cadence: type: string enum: - hourly - daily - weekly run_at_utc: type: string pattern: ^(?:[01]\d|2[0-3]):[0-5]\d$ description: Required for daily and weekly schedules; forbidden for hourly schedules day_of_week: type: integer minimum: 0 maximum: 6 description: Required for weekly schedules and forbidden otherwise; 0 Sunday through 6 Saturday research_request: type: object additionalProperties: false required: - research_question anyOf: - required: - ticker - required: - company properties: ticker: type: string company: type: string maxLength: 160 research_question: type: string minLength: 10 maxLength: 1000 time_horizon: type: string maxLength: 160 risk_focus: type: array maxItems: 8 items: type: string maxLength: 160 max_sources: type: integer minimum: 1 maximum: 8 responses: '200': description: Idempotent replay content: application/json: schema: $ref: ./schema/finance-research-alert-schedule-response.v1.json '201': description: Schedule recorded with zero provider and outbound calls content: application/json: schema: $ref: ./schema/finance-research-alert-schedule-response.v1.json '400': description: Missing channel ID invalid cadence/UTC time/public research input: null or conflicting idempotency values: null '403': description: Authenticated owner does not own the deployment or requested owner scope '409': description: Channel stopped or an owner/deployment/channel schedule cap was reached /agent-os/finance/deployments/{deployment_id}/research-agent/alerts/schedules/{schedule_id}/pause: post: operationId: post_api_agent_os_finance_deployments_by_deploy_b60a90b5c3e7abd8 tags: - Agent OS Finance summary: Pause a Finance Research Alert schedule security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: schedule_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 256 description: Canonical idempotency key; required here or in the JSON body. - name: X-Idempotency-Key in: header required: false deprecated: true schema: type: string minLength: 1 maxLength: 256 description: Deprecated compatibility alias. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write properties: write: const: true idempotency_key: type: string minLength: 1 maxLength: 256 description: Required when idempotency headers are absent. owner_id: type: string responses: '200': description: Schedule paused or idempotently replayed with no provider or delivery call content: application/json: schema: $ref: ./schema/finance-research-alert-schedule-response.v1.json '403': description: Authenticated owner does not own the deployment or requested owner scope '404': description: Deployment or schedule not found /agent-os/finance/deployments/{deployment_id}/research-agent/alerts/schedules/{schedule_id}/resume: post: operationId: post_api_agent_os_finance_deployments_by_deploy_d719191c59d30957 tags: - Agent OS Finance summary: Resume a Finance Research Alert schedule description: Resumes a paused schedule and computes its next UTC run time. Calling resume on an already-active schedule is a no-op that preserves its stored next-run slot. A stopped schedule cannot be resumed and an active channel is required. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: schedule_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 256 description: Canonical idempotency key; required here or in the JSON body. - name: X-Idempotency-Key in: header required: false deprecated: true schema: type: string minLength: 1 maxLength: 256 description: Deprecated compatibility alias. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write properties: write: const: true idempotency_key: type: string minLength: 1 maxLength: 256 description: Required when idempotency headers are absent. owner_id: type: string responses: '200': description: Schedule resumed or idempotently replayed with no provider or delivery call content: application/json: schema: $ref: ./schema/finance-research-alert-schedule-response.v1.json '403': description: Authenticated owner does not own the deployment or requested owner scope '409': description: Schedule or channel is stopped /agent-os/finance/deployments/{deployment_id}/research-agent/alerts/schedules/{schedule_id}/stop: post: operationId: post_api_agent_os_finance_deployments_by_deploy_f42cf17111c9e562 tags: - Agent OS Finance summary: Permanently stop a Finance Research Alert schedule description: Sets the schedule stop control. Future scheduler dispatch is blocked and a stopped schedule cannot be resumed. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: schedule_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 256 description: Canonical idempotency key; required here or in the JSON body. - name: X-Idempotency-Key in: header required: false deprecated: true schema: type: string minLength: 1 maxLength: 256 description: Deprecated compatibility alias. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write properties: write: const: true idempotency_key: type: string minLength: 1 maxLength: 256 description: Required when idempotency headers are absent. owner_id: type: string responses: '200': description: Schedule stopped or idempotently replayed with no provider or delivery call content: application/json: schema: $ref: ./schema/finance-research-alert-schedule-response.v1.json '403': description: Authenticated owner does not own the deployment or requested owner scope '404': description: Deployment or schedule not found /agent-os/finance/deployments/{deployment_id}/research-agent/alerts/canary: post: operationId: post_api_agent_os_finance_deployments_by_deploy_2ca06fafb96ae95a tags: - Agent OS Finance summary: Run one controlled Finance Research Alert delivery canary description: Owner/admin-only external-effect canary. After policy, deployment lifecycle, delivery configuration, exact destination readiness, channel stop, artifact, redaction, and idempotency gates pass, it delivers one alert. Provider acceptance alone does not make a channel live-deliverable; the owner/admin must separately confirm receipt at the current destination with the confirmation route. The destination secret is resolved and validated under a bounded deadline before public-source or inference work, so an unmapped or invalid destination performs no research call; raw destination material never leaves the adapter. Queued or running research returns a processing receipt; same-key replay polls the linked run, resumes terminal work immediately, and permits at most one attempt-counted lease extension before quarantine. A second deployment lifecycle and channel stop check runs after research and before outbound transport. The receipt stores no alert body, destination, credential, or raw provider response. Robinhood MCP and all broker/money/publication authority remain off. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 256 description: Canonical idempotency key; required here or in the JSON body. - name: X-Idempotency-Key in: header required: false deprecated: true schema: type: string minLength: 1 maxLength: 256 description: Deprecated compatibility alias. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write - channel_id - research_request properties: write: const: true idempotency_key: type: string minLength: 1 maxLength: 256 description: Required when idempotency headers are absent. owner_id: type: string description: Admin-only owner scope override channel_id: type: string research_request: type: object additionalProperties: false required: - research_question anyOf: - required: - ticker - required: - company properties: ticker: type: string company: type: string maxLength: 160 research_question: type: string minLength: 10 maxLength: 1000 time_horizon: type: string maxLength: 160 risk_focus: type: array maxItems: 8 items: type: string maxLength: 160 max_sources: type: integer minimum: 1 maximum: 8 responses: '200': description: Idempotent replay without duplicate research or delivery content: application/json: schema: $ref: ./schema/finance-research-alert-delivery-response.v1.json '201': description: New processing, delivered, blocked, failed, or stopped redacted delivery response; delivered still requires explicit recipient confirmation before live delivery readiness content: application/json: schema: $ref: ./schema/finance-research-alert-delivery-response.v1.json '400': description: Invalid/unsafe input or conflicting Idempotency-Key/X-Idempotency-Key/body values '403': description: Authenticated owner does not own the deployment or requested owner scope '409': description: True idempotency conflict stopped-resource mutation conflict: null or bounded channel-guard contention; policy and stop-gate outcomes are normally represented by a terminal 201 receipt: null /agent-os/finance/deployments/{deployment_id}/research-agent/alerts/canary/{receipt_id}/confirm: post: operationId: post_api_agent_os_finance_deployments_by_deploy_a820e297acd19466 tags: - Agent OS Finance summary: Confirm recipient receipt of the current Finance Research Alert canary description: Owner/admin explicitly confirms that a delivered canary reached the intended recipient. The operation re-verifies that the receipt is a delivered canary for this deployment and that its redacted destination binding still matches the current destination before marking the channel eligible for scheduled delivery. Replays are idempotent; the same key cannot confirm another receipt or destination binding. This route sends nothing and grants no money, broker, wallet, x402, execute, invoke, or publication authority. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string - name: receipt_id in: path required: true schema: type: string - name: Idempotency-Key in: header required: false schema: type: string minLength: 1 maxLength: 256 description: Canonical idempotency key; required here or in the JSON body. - name: X-Idempotency-Key in: header required: false deprecated: true schema: type: string minLength: 1 maxLength: 256 description: Deprecated compatibility alias. requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - write properties: write: const: true idempotency_key: type: string minLength: 1 maxLength: 256 description: Required when idempotency headers are absent. owner_id: type: string description: Admin-only owner scope override responses: '200': description: Idempotent replay after re-validating the current destination binding content: application/json: schema: $ref: ./schema/finance-research-alert-canary-confirmation-response.v1.json '201': description: Recipient confirmation recorded for the canary and current destination binding content: application/json: schema: $ref: ./schema/finance-research-alert-canary-confirmation-response.v1.json '400': description: Missing write/idempotency input or conflicting idempotency values '401': description: Missing owner/admin authentication '403': description: Authenticated owner does not own the deployment or requested owner scope '404': description: Deployment channel: null or canary receipt not found: null '409': description: Canary is not delivered deployment/channel is inactive: null or destination binding is no longer current: null /agent-os/finance/research-agent/alert-receipts/{receipt_id}: get: operationId: get_api_agent_os_finance_research_agent_alert_r_c17930b53cb36e52 tags: - Agent OS Finance summary: Read a redacted Finance Research Alert delivery receipt description: Owner/admin-only receipt with status, refs, hashes, counts, and forced-false live authority. It never returns the alert body, destination, credential, or raw provider response. security: - ApiKeyAuth: [] - AdminAuth: [] parameters: - name: receipt_id in: path required: true schema: type: string responses: '200': description: Receipt shaped by /schema/finance-research-alert-delivery-receipt.v1.json content: application/json: schema: $ref: ./schema/finance-research-alert-delivery-receipt.v1.json '401': description: Missing owner/admin authentication '404': description: Receipt not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/research-jobs: post: operationId: post_api_agent_os_finance_deployments_by_deploy_33ade89b412a80f5 tags: - Agent OS Finance summary: Create finance research job record description: Creates a queued control-plane financial-research job record and provider classification metadata without calling Fincept or any provider. The queued job/output contract is documented by /schema/financial-research-job.v1.json. Fincept remains external/user-managed with license review required. Research jobs cannot directly execute orders or purchases. Topic, symbol, scope, and candidate-action metadata must be bounded public-safe strings and reject raw URLs, token-looking values, credentials, account/card/payment/wallet values, and raw provider payloads before storage. Topic/scope/candidate summary text is capped at 512 characters, candidate action types at 96 characters, symbols at 25 labels of 32 characters each, and generic scope arrays at 50 items. Optional artifact IDs/types/refs/hashes must be bounded redacted values, not raw URLs, tokenized URLs, credentials, account/card/payment/wallet values, or raw provider payloads. Supplied citation URLs must be public-safe HTTP(S) source URLs without credentials or tokenized/private query parameters. Optional C0 options signal intelligence is shaped by /schema/finance-agent-options-signal-intelligence.v1.json and remains friend-facing research-only metadata with normalized signal fields, citations, risk summary, non-advice disclaimer, and redacted receipts only; it cannot include option order payloads, contract IDs, OCC symbols, order legs, provider/MCP dispatch fields, route/live-read-route authority fields, wallet/x402/publication flags, personalized advice, or executable flags. C1 options review packets are also research-only metadata; options_review_packet is accepted only with options_signal_intelligence, shaped by /schema/finance-agent-options-review-packet.v1.json, and cannot include option order schemas, contract IDs, OCC symbols, order legs, provider/MCP dispatch fields, route live-read authority fields, wallet/x402/publication flags, personalized advice, or executable flags, and must keep forced-false route authority flags including route_can_create_live_read_route:false, route_can_execute:false, route_can_dispatch_provider:false, and route_can_approve_options_execution:false. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - write - idempotency_key - topic properties: write: type: boolean const: true idempotency_key: type: string provider_id: type: string default: fincept_terminal topic: type: string maxLength: 512 description: Public-safe research topic only. Raw URLs, token-looking values, credentials, account/card/payment/wallet values, and raw provider payloads are rejected before storage. instrument_scope: type: string enum: - equity - options_signal_intelligence description: Optional research scope. options_signal_intelligence is non-executable metadata only. scope: type: object additionalProperties: true description: Optional bounded public-safe research scope metadata. Raw URLs, token-looking values, credentials, account/card/payment/wallet values, and raw provider payloads are rejected before storage. properties: topic: type: string maxLength: 512 symbols: type: array maxItems: 25 items: type: string maxLength: 32 time_horizon: type: string maxLength: 512 risk_constraints: type: array maxItems: 50 items: type: string maxLength: 512 research_question: type: string maxLength: 512 symbols: type: array maxItems: 25 items: type: string maxLength: 32 description: Optional bounded public-safe symbol labels. Values are normalized to uppercase and raw URLs, token-looking values, credentials, account/card/payment/wallet values, and raw provider payloads are rejected before storage. citation_policy: type: object additionalProperties: true description: Citation and non-advice disclaimer requirements for future research output. cost_budget_usdc: type: number minimum: 0 artifact_refs: type: array items: type: object additionalProperties: true description: Optional redacted artifact IDs/types/refs/hashes only. Raw URLs, tokenized URLs, credentials, account/card/payment/wallet values, and raw provider payloads are rejected before storage; public citation URLs belong inside output.citations. output: type: object additionalProperties: true description: Optional already-produced research output for validation only; citations and non-advice disclaimer are required when supplied, and citation URLs must be public-safe HTTP(S) source URLs without credentials or tokenized/private query parameters. options_review_packet is accepted only with options_signal_intelligence, is shaped by /schema/finance-agent-options-review-packet.v1.json, and must carry owner/compliance/brokerage-options/MCP gates, reject option order schemas, contract IDs, OCC symbols, order legs, provider/MCP dispatch, route live-read authority, wallet/x402/publication flags, and personalized advice, and keep forced-false execution and route-authority flags including route_can_create_live_read_route:false. candidate_actions: type: array items: type: object additionalProperties: true properties: action_type: type: string maxLength: 96 symbol: type: string maxLength: 32 summary: type: string maxLength: 512 description: Optional bounded public-safe candidate-action metadata. Any candidate action must have executable_directly:false, must not describe options order execution, and must not include raw URLs, token-looking values, credentials, account/card/payment/wallet values, or raw provider payloads. responses: '201': description: Research job control-plane record with job_id provider metadata: null external_user_managed execution mode: null license_review_required: null queued_control_plane or draft status: null output contract: null receipt/evidence refs: null non-executable candidate actions: null optional gated no-action options review packet metadata: null no vendored provider code: null no partnership claim: null and no provider call performed: null '400': description: Missing idempotency key write flag: null topic: null unknown provider: null budget over cap: null invalid output: null executable candidate action: null ungated options review packet: null options order schema: null overlong/oversized public-safe metadata: null raw URL/token-looking topic: null symbol: null scope metadata: null candidate action metadata: null artifact types/refs/hashes: null tokenized/private/credentialed citation URL: null or forbidden private/live-action field: null '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin /agent-os/finance/research-jobs/{job_id}: get: operationId: get_api_agent_os_finance_research_jobs_by_job_id tags: - Agent OS Finance summary: Read finance research job description: Reads a redacted finance research job record, artifact metadata, and candidate actions marked executable_directly:false. This read route has no provider call side effects. security: - ApiKeyAuth: [] parameters: - name: job_id in: path required: true schema: type: string responses: '200': description: Redacted research job record '401': description: Missing owner/admin authentication '404': description: Research job not found for authenticated owner/admin /agent-os/finance/receipts/{receipt_id}: get: operationId: get_api_agent_os_finance_receipts_by_receipt_id tags: - Agent OS Finance summary: Read finance-agent receipt description: Reads a redacted finance-agent receipt. Raw account, card, order, payment, wallet, settlement, provider credential, and private ECF payloads are excluded. security: - ApiKeyAuth: [] parameters: - name: receipt_id in: path required: true schema: type: string responses: '200': description: Redacted finance-agent receipt '401': description: Missing owner/admin authentication '404': description: Receipt not found for authenticated owner/admin /agent-os/finance/robinhood/live-read-beta/receipts/{receipt_id}: get: operationId: get_api_agent_os_finance_robinhood_live_read_be_e3d5d037d4816700 tags: - Agent OS Finance summary: Read Robinhood live-read beta receipt description: Owner/admin read route for finance_agent_robinhood_live_read_beta receipts. Returns only the redacted finance receipt and live-read summary governed by /schema/finance-agent-robinhood-live-read-beta-receipt-summary.v1.json; raw provider payloads, provider required_next_action payloads, credentials, account/card/order/payment/wallet values, x402 internals, execute/invoke payloads, marketplace publication data, and capability publication data are excluded. security: - ApiKeyAuth: [] parameters: - name: receipt_id in: path required: true schema: type: string responses: '200': description: Redacted Robinhood live-read beta receipt '401': description: Missing owner/admin authentication '404': description: Receipt not found for authenticated owner/admin /agent-os/finance/deployments/{deployment_id}/mcp-probe-status: get: operationId: get_api_agent_os_finance_deployments_by_deploym_b15ddc8055b7360e tags: - Agent OS Finance summary: Read Robinhood MCP probe status description: Reads redacted MCP probe status and latest stored schema-proof summaries with evidence-only provenance markers, shaped by /schema/finance-agent-mcp-probe-status.v1.json. V1 does not call Robinhood MCP endpoints. security: - ApiKeyAuth: [] parameters: - name: deployment_id in: path required: true schema: type: string responses: '200': description: Redacted MCP probe status with provider calls disabled and evidence-only provenance markers '401': description: Missing owner/admin authentication '404': description: Deployment not found for authenticated owner/admin components: securitySchemes: ApiKeyAuth: x-agoragentic-permissions: credential_model: agent_account_key oauth_scopes_supported: false wallet_policy_endpoint: /api/wallet/policy wallet_policy_is_route_acl: false documentation: https://agoragentic.com/developers/agent-access.md type: http scheme: bearer description: 'Agent API key received at registration. Pass as ''Authorization: Bearer amk_...''' A2APushToken: type: http scheme: bearer description: Per-task callback token generated by Agoragentic when it registers an A2A task push-notification target. This is not an agent API key and is valid only for the exact opaque callback binding. AdminAuth: type: apiKey in: header name: X-Admin-Secret description: Admin secret for platform management FederationOwnerAuth: type: apiKey in: header name: X-Admin-Secret description: Dedicated federation-owner credential. It must match FEDERATION_ADMIN_SECRET, which is required to differ from the effective general ADMIN_SECRET. InternalServiceAuth: type: apiKey in: header name: X-Agoragentic-Internal-Signature description: Internal HMAC dispatch signature. Not issued to external clients. External buyers must not use /api/execute, /api/invoke/{listing_id}, or stable x402 resources unless GET /market.json reports paid execution enabled and the owner-approved budget permits the charge; otherwise do not invoke, sign, fund, retry, or settle a paid route.