{"openapi":"3.1.0","info":{"title":"DNAi Intelligence API","version":"unknown","summary":"Ten domain engines behind one A2A v1.0 API, with evidence on every answer.","description":"Address an engine by domain key (health, fitness, finance, legal, nutrition, research, science, support, practice, growth) or legacy agent id. Put your own name on the answer with metadata.persona. Pin depth with metadata.depth ('base' or 'auto'); every task reports depth_served (base, mid, apex). Benchmarks per depth: https://dnai.systems/benchmarks. Docs and console: https://dnai.systems/developers.\n\n## Request IDs\n\nEvery response carries `X-Request-ID`; errors repeat it as `error.request_id`. Send your own `X-Request-ID` to correlate with your logs; otherwise one is generated. Quote it to support.\n\n## Idempotent retries\n\n`POST /a2a/v1/message:send` (and the per-agent variant) accepts `Idempotency-Key` (1 to 255 characters; use a UUID v4, never personal data). A retry with the same key and body within 24 hours returns the saved response with `Idempotent-Replayed: true`, without running again or counting toward allowances. A different body with the same key is `idempotency_key_reused`; a retry while the first is running is `idempotency_in_progress` (wait `retry_after`). Nothing is saved when a request fails auth, limits, or validation. Streams do not take keys: recover with `GET /a2a/v1/tasks/{id}`.\n\n## Versioning\n\nResponses on `/a2a/v1` carry `A2A-Version: 1.0`. Changes are listed at https://dnai.systems/a2a#changelog.\n\n## Errors\n\nEvery error from the developer paths returns one JSON object: `{\"error\": {\"code\", \"type\", \"message\", \"doc_url\", \"request_id\", \"param\"?, \"retry_after\"?}, \"detail\": ...}`. Branch on `error.type`; it is unique per cause and stable. `error.code` follows JSON-RPC 2.0 and A2A v1.0 where a standard number exists, so related types can share a code. 429s and retryable 503s send `Retry-After` (seconds), mirrored in `error.retry_after`. `detail` is the legacy field, kept unchanged for older clients. The OpenAI-compatible `/v1` paths use the OpenAI envelope `{\"error\": {\"message\", \"type\", \"code\"}}` instead, with the same cause in `code`. Send `Accept: application/problem+json` to receive RFC 9457 Problem Details (`type` is the doc_url, plus `code`, `error_type`, `request_id`, `param`, `retry_after` as extensions).\n\n| HTTP | `type` | `code` | Retry | Meaning |\n|---|---|---|---|---|\n| 400 | `invalid_request` | `-32600` | no | The request is malformed: empty message, message over 500,000 characters, or a signup or billing field with a value the API does not accept. |\n| 400 | `invalid_params` | `-32602` | no | A parameter has a value outside its allowed set, for example metadata.depth other than base or auto. |\n| 422 | `validation_error` | `-32602` | no | The body does not match the schema (wrong type, missing required field). error.fields lists each failing field. |\n| 401 | `authentication_required` | `-32050` | no | No Authorization: Bearer header was sent. |\n| 401 | `invalid_api_key` | `-32050` | no | The key is unknown, mistyped, or was rotated. |\n| 403 | `permission_denied` | `-32051` | no | The key may not call this agent or operation (Asha keys reach Asha only; internal agents are never reachable). |\n| 403 | `account_suspended` | `-32051` | no | The account is suspended, usually after a failed payment. Fix billing in the portal; access resumes when the invoice is paid. |\n| 404 | `not_found` | `-32052` | no | The account, billing record, or resource does not exist for this key. |\n| 404 | `agent_not_found` | `-32052` | no | No public agent has this id or domain key. |\n| 404 | `task_not_found` | `-32001` | no | The task id does not exist or belongs to another key (A2A TaskNotFoundError). |\n| 409 | `conflict` | `-32053` | no | The resource already exists, for example a second signup with the same email. |\n| 409 | `task_not_cancelable` | `-32002` | no | The task already reached a terminal state (A2A TaskNotCancelableError). |\n| 410 | `agent_retired` | `-32054` | no | The agent was retired and no longer answers. |\n| 400 | `idempotency_key_reused` | `-32055` | no | The Idempotency-Key was already used with a different request body or endpoint. Use a new key for a new request. |\n| 409 | `idempotency_in_progress` | `-32056` | yes | A request with this Idempotency-Key is still running. Retry after retry_after seconds to receive its result. |\n| 429 | `rate_limited` | `-32060` | yes | Too many requests in the last 60 seconds. Wait retry_after seconds. |\n| 429 | `daily_quota_exceeded` | `-32061` | yes | The daily query allowance is used up. Resets at 00:00 UTC. |\n| 429 | `monthly_quota_exceeded` | `-32062` | yes | The monthly query allowance is used up. Resets on the 1st at 00:00 UTC, or upgrade the plan. |\n| 429 | `spending_cap_reached` | `-32063` | yes | Estimated spend this month reached the account's cap. Resets on the 1st, or raise the cap by upgrading. |\n| 429 | `signup_rate_limited` | `-32064` | yes | Too many new keys from this network in 24 hours. |\n| 500 | `internal_error` | `-32603` | no | Unexpected server error. Quote error.error_id to support. |\n| 503 | `service_unavailable` | `-32070` | yes | A dependency (engine, database, signup store) is temporarily down. Retry after a short wait. |","termsOfService":"https://dnai.systems/terms","contact":{"name":"DNAi Systems","url":"https://dnai.systems/developers","email":"hello@dnai.systems"}},"servers":[{"url":"https://api.askasha.org","description":"Canonical API host"},{"url":"https://api.dnai.systems","description":"Company-domain alias (same API)"}],"externalDocs":{"description":"Developer site","url":"https://dnai.systems/developers"},"paths":{"/api/audit/corpus-state/public":{"get":{"tags":["Audit"],"summary":"Get the corpus commitment","description":"Public cryptographic corpus commitment endpoint for third-party verification.","operationId":"getCorpusCommitment","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/audit/corpus-state/public"}]}},"/api/benchmarks":{"get":{"tags":["Benchmarks"],"summary":"List benchmarks","description":"The full register plus the SHA-256 of the file it was served from.","operationId":"listBenchmarks","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/benchmarks"}]}},"/api/benchmarks/verify":{"get":{"tags":["Benchmarks"],"summary":"Verify the benchmark register","description":"Fetch the published static mirror and report whether it matches this copy byte for byte.","operationId":"verifyBenchmarks","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/benchmarks/verify"}]}},"/api/benchmarks/{benchmark_id}":{"get":{"tags":["Benchmarks"],"summary":"Get a benchmark","description":"One row, by id, from the main table or the small-n appendix.","operationId":"getBenchmark","parameters":[{"name":"benchmark_id","in":"path","required":true,"schema":{"type":"string","title":"Benchmark Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/benchmarks/$BENCHMARK_ID"}]}},"/api/agents/{agent_id}/knowledge":{"post":{"tags":["Agent knowledge"],"summary":"Upload knowledge files","description":"Upload files to an agent's knowledge base.\n\nAccepts multiple files (PDF, DOCX, CSV, TXT, JSON).\nFiles are parsed, chunked, embedded, and indexed into Qdrant.\nSmall uploads (<50MB total) are processed inline.","operationId":"uploadAgentKnowledge","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_knowledge_api_agents__agent_id__knowledge_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[{"dnai_session":[]}],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/api/agents/$AGENT_ID/knowledge \\\n  -H \"Authorization: Bearer $DNAI_SESSION_TOKEN\" \\\n  -F files=@document.pdf"}]},"get":{"tags":["Agent knowledge"],"summary":"List knowledge collections","description":"List all knowledge collections for an agent.","operationId":"listAgentKnowledge","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[{"dnai_session":[]}],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/agents/$AGENT_ID/knowledge \\\n  -H \"Authorization: Bearer $DNAI_SESSION_TOKEN\""}]}},"/api/agents/{agent_id}/knowledge/url":{"post":{"tags":["Agent knowledge"],"summary":"Ingest a URL","description":"Ingest content from a URL (web page or YouTube video).","operationId":"ingestAgentKnowledgeUrl","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/URLIngestionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[{"dnai_session":[]}],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/api/agents/$AGENT_ID/knowledge/url \\\n  -H \"Authorization: Bearer $DNAI_SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\": \"https://example.com/clinic-handbook\", \"visibility\": \"private\"}'"}]}},"/api/agents/{agent_id}/knowledge/{collection_name}":{"delete":{"tags":["Agent knowledge"],"summary":"Delete a knowledge collection","description":"Delete an agent's knowledge collection.\nRequires the collection to be owned by this agent (name prefix check).","operationId":"deleteAgentKnowledge","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}},{"name":"collection_name","in":"path","required":true,"schema":{"type":"string","title":"Collection Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[{"dnai_session":[]}],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X DELETE https://api.askasha.org/api/agents/$AGENT_ID/knowledge/$COLLECTION_NAME \\\n  -H \"Authorization: Bearer $DNAI_SESSION_TOKEN\""}]}},"/a2a/v1/health":{"get":{"tags":["Discovery"],"summary":"Check service health","description":"A2A health check: returns 503 if engine unavailable.","operationId":"getHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/a2a/v1/health"}]}},"/a2a/v1/message:send":{"post":{"tags":["A2A"],"summary":"Send a message","description":"Accept an A2A message and return a completed (or failed) Task.","operationId":"sendMessage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__routes__a2a__SendMessageRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}},"headers":{"Idempotent-Replayed":{"description":"`true` when this is the saved response of an earlier request.","schema":{"type":"string","enum":["true"]}},"Idempotency-Status":{"description":"`unavailable` when the idempotency store could not be reached and the request ran without protection.","schema":{"type":"string","enum":["unavailable"]}},"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"`invalid_request` (-32600): The request is malformed: empty message, message over 500,000 characters, or a signup or billing field with a value the API does not accept.\n\n`invalid_params` (-32602): A parameter has a value outside its allowed set, for example metadata.depth other than base or auto.\n\n`idempotency_key_reused` (-32055): The Idempotency-Key was already used with a different request body or endpoint. Use a new key for a new request.","content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":-32600,"type":"invalid_request","message":"Message must contain at least one non-empty text part","doc_url":"https://dnai.systems/a2a#err-invalid_request","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Message must contain at least one non-empty text part"}},"invalid_params":{"summary":"invalid_params","value":{"error":{"code":-32602,"type":"invalid_params","message":"metadata.depth must be 'base' or 'auto'","doc_url":"https://dnai.systems/a2a#err-invalid_params","param":"metadata.depth","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"metadata.depth must be 'base' or 'auto'"}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":-32055,"type":"idempotency_key_reused","message":"This Idempotency-Key was used with a different request. Use a new key for a new request.","doc_url":"https://dnai.systems/a2a#err-idempotency_key_reused","param":"Idempotency-Key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"This Idempotency-Key was used with a different request. Use a new key for a new request."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"`validation_error` (-32602): The body does not match the schema (wrong type, missing required field). error.fields lists each failing field.","content":{"application/json":{"examples":{"validation_error":{"summary":"validation_error","value":{"error":{"code":-32602,"type":"validation_error","message":"message.parts: Field required","doc_url":"https://dnai.systems/a2a#err-validation_error","param":"message.parts","fields":[{"loc":["body","message","parts"],"msg":"Field required","type":"missing"}],"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"message.parts: Field required"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"`permission_denied` (-32051): The key may not call this agent or operation (Asha keys reach Asha only; internal agents are never reachable).\n\n`account_suspended` (-32051): The account is suspended, usually after a failed payment. Fix billing in the portal; access resumes when the invoice is paid.","content":{"application/json":{"examples":{"permission_denied":{"summary":"permission_denied","value":{"error":{"code":-32051,"type":"permission_denied","message":"API key does not have access to agent 'leo'","doc_url":"https://dnai.systems/a2a#err-permission_denied","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"API key does not have access to agent 'leo'"}},"account_suspended":{"summary":"account_suspended","value":{"error":{"code":-32051,"type":"account_suspended","message":"Account suspended. Check billing at /api/a2a/portal.","doc_url":"https://dnai.systems/a2a#err-account_suspended","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Account suspended. Check billing at /api/a2a/portal."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"410":{"description":"`agent_retired` (-32054): The agent was retired and no longer answers.","content":{"application/json":{"examples":{"agent_retired":{"summary":"agent_retired","value":{"error":{"code":-32054,"type":"agent_retired","message":"agent sage is retired","doc_url":"https://dnai.systems/a2a#err-agent_retired","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"agent sage is retired"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"429":{"description":"`rate_limited` (-32060): Too many requests in the last 60 seconds. Wait retry_after seconds.\n\n`daily_quota_exceeded` (-32061): The daily query allowance is used up. Resets at 00:00 UTC.\n\n`monthly_quota_exceeded` (-32062): The monthly query allowance is used up. Resets on the 1st at 00:00 UTC, or upgrade the plan.\n\n`spending_cap_reached` (-32063): Estimated spend this month reached the account's cap. Resets on the 1st, or raise the cap by upgrading.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"code":-32060,"type":"rate_limited","message":"Rate limit exceeded: 10 requests/minute","doc_url":"https://dnai.systems/a2a#err-rate_limited","retry_after":60,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Rate limit exceeded: 10 requests/minute"}},"daily_quota_exceeded":{"summary":"daily_quota_exceeded","value":{"error":{"code":-32061,"type":"daily_quota_exceeded","message":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-daily_quota_exceeded","retry_after":21600,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more."}},"monthly_quota_exceeded":{"summary":"monthly_quota_exceeded","value":{"error":{"code":-32062,"type":"monthly_quota_exceeded","message":"Monthly query limit reached (50/50). Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-monthly_quota_exceeded","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Monthly query limit reached (50/50). Upgrade tier for more."}},"spending_cap_reached":{"summary":"spending_cap_reached","value":{"error":{"code":-32063,"type":"spending_cap_reached","message":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap.","doc_url":"https://dnai.systems/a2a#err-spending_cap_reached","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"409":{"description":"`idempotency_in_progress` (-32056): A request with this Idempotency-Key is still running. Retry after retry_after seconds to receive its result.","content":{"application/json":{"examples":{"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":-32056,"type":"idempotency_in_progress","message":"A request with this Idempotency-Key is still running. Retry shortly to get its result.","doc_url":"https://dnai.systems/a2a#err-idempotency_in_progress","retry_after":5,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A request with this Idempotency-Key is still running. Retry shortly to get its result."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retry safe. The first request with a key runs; a retry with the same key and body within 24 hours returns the saved response with `Idempotent-Replayed: true` and does not run again or count toward allowances. Use a fresh UUID v4 per logical request; never put personal data in it. Nothing is saved when the request fails auth, limits, or validation."}],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"KEY=$(uuidgen)  # reuse the same key if you retry this request\ncurl -X POST https://api.askasha.org/a2a/v1/message:send \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $KEY\" \\\n  -d '{\"agent_id\": \"asha\", \"message\": {\"role\": \"user\", \"parts\": [{\"text\": \"What is the first-line treatment for type 2 diabetes in adults?\"}]}, \"metadata\": {\"session_id\": \"demo-session-1\"}}'"},{"lang":"Python","label":"Python (requests)","source":"import os, uuid, requests\n\nkey = str(uuid.uuid4())  # reuse the same key if you retry this request\nresp = requests.post(\n    \"https://api.askasha.org/a2a/v1/message:send\",\n    headers={\"Authorization\": f\"Bearer {os.environ['DNAI_API_KEY']}\",\n             \"Idempotency-Key\": key},\n    json={\"agent_id\": \"asha\",\n          \"message\": {\"role\": \"user\", \"parts\": [{\"text\": \"What is sepsis?\"}]}},\n    timeout=120,\n)\nif resp.status_code >= 400:\n    err = resp.json()[\"error\"]\n    raise SystemExit(f\"{err['type']}: {err['message']} (request {err.get('request_id')})\")\ntask = resp.json()[\"task\"]\nprint(task[\"artifacts\"][0][\"parts\"][0][\"text\"])"}]}},"/a2a/v1/agents/{agent_id}/agent-card.json":{"get":{"tags":["Discovery"],"summary":"Get an agent card","description":"A2A Agent Card for one public agent: interface URL, protocol version, security scheme, skills. No auth.","operationId":"getAgentCard","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`agent_not_found` (-32052): No public agent has this id or domain key.","content":{"application/json":{"examples":{"agent_not_found":{"summary":"agent_not_found","value":{"error":{"code":-32052,"type":"agent_not_found","message":"Agent 'unknown' not found","doc_url":"https://dnai.systems/a2a#err-agent_not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Agent 'unknown' not found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/a2a/v1/agents/$AGENT_ID/agent-card.json"}]}},"/a2a/v1/agents/{agent_id}/message:send":{"post":{"tags":["A2A"],"summary":"Send a message to one agent","description":"Same handler as POST /message:send with the path agent pinned.","operationId":"sendAgentMessage","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Makes a retry safe. The first request with a key runs; a retry with the same key and body within 24 hours returns the saved response with `Idempotent-Replayed: true` and does not run again or count toward allowances. Use a fresh UUID v4 per logical request; never put personal data in it. Nothing is saved when the request fails auth, limits, or validation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__routes__a2a__SendMessageRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}},"headers":{"Idempotent-Replayed":{"description":"`true` when this is the saved response of an earlier request.","schema":{"type":"string","enum":["true"]}},"Idempotency-Status":{"description":"`unavailable` when the idempotency store could not be reached and the request ran without protection.","schema":{"type":"string","enum":["unavailable"]}},"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`agent_not_found` (-32052): No public agent has this id or domain key.","content":{"application/json":{"examples":{"agent_not_found":{"summary":"agent_not_found","value":{"error":{"code":-32052,"type":"agent_not_found","message":"Agent 'unknown' not found","doc_url":"https://dnai.systems/a2a#err-agent_not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Agent 'unknown' not found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"`invalid_request` (-32600): The request is malformed: empty message, message over 500,000 characters, or a signup or billing field with a value the API does not accept.\n\n`invalid_params` (-32602): A parameter has a value outside its allowed set, for example metadata.depth other than base or auto.\n\n`idempotency_key_reused` (-32055): The Idempotency-Key was already used with a different request body or endpoint. Use a new key for a new request.","content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":-32600,"type":"invalid_request","message":"Message must contain at least one non-empty text part","doc_url":"https://dnai.systems/a2a#err-invalid_request","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Message must contain at least one non-empty text part"}},"invalid_params":{"summary":"invalid_params","value":{"error":{"code":-32602,"type":"invalid_params","message":"metadata.depth must be 'base' or 'auto'","doc_url":"https://dnai.systems/a2a#err-invalid_params","param":"metadata.depth","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"metadata.depth must be 'base' or 'auto'"}},"idempotency_key_reused":{"summary":"idempotency_key_reused","value":{"error":{"code":-32055,"type":"idempotency_key_reused","message":"This Idempotency-Key was used with a different request. Use a new key for a new request.","doc_url":"https://dnai.systems/a2a#err-idempotency_key_reused","param":"Idempotency-Key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"This Idempotency-Key was used with a different request. Use a new key for a new request."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"`validation_error` (-32602): The body does not match the schema (wrong type, missing required field). error.fields lists each failing field.","content":{"application/json":{"examples":{"validation_error":{"summary":"validation_error","value":{"error":{"code":-32602,"type":"validation_error","message":"message.parts: Field required","doc_url":"https://dnai.systems/a2a#err-validation_error","param":"message.parts","fields":[{"loc":["body","message","parts"],"msg":"Field required","type":"missing"}],"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"message.parts: Field required"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"`permission_denied` (-32051): The key may not call this agent or operation (Asha keys reach Asha only; internal agents are never reachable).\n\n`account_suspended` (-32051): The account is suspended, usually after a failed payment. Fix billing in the portal; access resumes when the invoice is paid.","content":{"application/json":{"examples":{"permission_denied":{"summary":"permission_denied","value":{"error":{"code":-32051,"type":"permission_denied","message":"API key does not have access to agent 'leo'","doc_url":"https://dnai.systems/a2a#err-permission_denied","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"API key does not have access to agent 'leo'"}},"account_suspended":{"summary":"account_suspended","value":{"error":{"code":-32051,"type":"account_suspended","message":"Account suspended. Check billing at /api/a2a/portal.","doc_url":"https://dnai.systems/a2a#err-account_suspended","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Account suspended. Check billing at /api/a2a/portal."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"410":{"description":"`agent_retired` (-32054): The agent was retired and no longer answers.","content":{"application/json":{"examples":{"agent_retired":{"summary":"agent_retired","value":{"error":{"code":-32054,"type":"agent_retired","message":"agent sage is retired","doc_url":"https://dnai.systems/a2a#err-agent_retired","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"agent sage is retired"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"429":{"description":"`rate_limited` (-32060): Too many requests in the last 60 seconds. Wait retry_after seconds.\n\n`daily_quota_exceeded` (-32061): The daily query allowance is used up. Resets at 00:00 UTC.\n\n`monthly_quota_exceeded` (-32062): The monthly query allowance is used up. Resets on the 1st at 00:00 UTC, or upgrade the plan.\n\n`spending_cap_reached` (-32063): Estimated spend this month reached the account's cap. Resets on the 1st, or raise the cap by upgrading.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"code":-32060,"type":"rate_limited","message":"Rate limit exceeded: 10 requests/minute","doc_url":"https://dnai.systems/a2a#err-rate_limited","retry_after":60,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Rate limit exceeded: 10 requests/minute"}},"daily_quota_exceeded":{"summary":"daily_quota_exceeded","value":{"error":{"code":-32061,"type":"daily_quota_exceeded","message":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-daily_quota_exceeded","retry_after":21600,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more."}},"monthly_quota_exceeded":{"summary":"monthly_quota_exceeded","value":{"error":{"code":-32062,"type":"monthly_quota_exceeded","message":"Monthly query limit reached (50/50). Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-monthly_quota_exceeded","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Monthly query limit reached (50/50). Upgrade tier for more."}},"spending_cap_reached":{"summary":"spending_cap_reached","value":{"error":{"code":-32063,"type":"spending_cap_reached","message":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap.","doc_url":"https://dnai.systems/a2a#err-spending_cap_reached","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"409":{"description":"`idempotency_in_progress` (-32056): A request with this Idempotency-Key is still running. Retry after retry_after seconds to receive its result.","content":{"application/json":{"examples":{"idempotency_in_progress":{"summary":"idempotency_in_progress","value":{"error":{"code":-32056,"type":"idempotency_in_progress","message":"A request with this Idempotency-Key is still running. Retry shortly to get its result.","doc_url":"https://dnai.systems/a2a#err-idempotency_in_progress","retry_after":5,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A request with this Idempotency-Key is still running. Retry shortly to get its result."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/a2a/v1/agents/$AGENT_ID/message:send \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"agent_id\": \"asha\", \"message\": {\"parts\": [{\"text\": \"What is the first-line treatment for type 2 diabetes in adults?\"}], \"role\": \"user\"}, \"metadata\": {\"depth\": \"base\", \"session_id\": \"demo-session-1\"}}'"}]}},"/a2a/v1/agents/{agent_id}":{"post":{"tags":["A2A"],"summary":"JSON-RPC binding","description":"JSON-RPC 2.0 binding at the agent card URL, for A2A clients that default to JSON-RPC.\n\nMethods: `SendMessage` (A2A 1.0; result is `{\"task\": {...}}`) and `message/send` (A2A 0.3; result is a\n0.3 Task). Protocol errors return HTTP 200 with a JSON-RPC `error` whose `code` comes from the error\ntable; a missing key returns 401.","operationId":"agentJsonRpc","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`agent_not_found` (-32052): No public agent has this id or domain key.","content":{"application/json":{"examples":{"agent_not_found":{"summary":"agent_not_found","value":{"error":{"code":-32052,"type":"agent_not_found","message":"Agent 'unknown' not found","doc_url":"https://dnai.systems/a2a#err-agent_not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Agent 'unknown' not found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"`account_suspended` (-32051): The account is suspended, usually after a failed payment. Fix billing in the portal; access resumes when the invoice is paid.","content":{"application/json":{"examples":{"account_suspended":{"summary":"account_suspended","value":{"error":{"code":-32051,"type":"account_suspended","message":"Account suspended. Check billing at /api/a2a/portal.","doc_url":"https://dnai.systems/a2a#err-account_suspended","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Account suspended. Check billing at /api/a2a/portal."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"429":{"description":"`rate_limited` (-32060): Too many requests in the last 60 seconds. Wait retry_after seconds.\n\n`daily_quota_exceeded` (-32061): The daily query allowance is used up. Resets at 00:00 UTC.\n\n`monthly_quota_exceeded` (-32062): The monthly query allowance is used up. Resets on the 1st at 00:00 UTC, or upgrade the plan.\n\n`spending_cap_reached` (-32063): Estimated spend this month reached the account's cap. Resets on the 1st, or raise the cap by upgrading.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"code":-32060,"type":"rate_limited","message":"Rate limit exceeded: 10 requests/minute","doc_url":"https://dnai.systems/a2a#err-rate_limited","retry_after":60,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Rate limit exceeded: 10 requests/minute"}},"daily_quota_exceeded":{"summary":"daily_quota_exceeded","value":{"error":{"code":-32061,"type":"daily_quota_exceeded","message":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-daily_quota_exceeded","retry_after":21600,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more."}},"monthly_quota_exceeded":{"summary":"monthly_quota_exceeded","value":{"error":{"code":-32062,"type":"monthly_quota_exceeded","message":"Monthly query limit reached (50/50). Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-monthly_quota_exceeded","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Monthly query limit reached (50/50). Upgrade tier for more."}},"spending_cap_reached":{"summary":"spending_cap_reached","value":{"error":{"code":-32063,"type":"spending_cap_reached","message":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap.","doc_url":"https://dnai.systems/a2a#err-spending_cap_reached","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/a2a/v1/agents/asha \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"SendMessage\", \"params\": {\"message\": {\"role\": \"user\", \"parts\": [{\"text\": \"What is sepsis?\"}]}}}'"}]}},"/a2a/v1/message:stream":{"post":{"tags":["A2A"],"summary":"Stream a message","description":"A2A v1.0 streaming variant: emits SSE phases, chunks, and final task.\n\nIdempotency-Key is not applied to streams; after a dropped connection,\nrecover the result with GET /a2a/v1/tasks/{task_id} from task_created.\n\nThe wire format is a sequence of named SSE events:\n\n  event: task_created   data: {task_id, agent_id, state, created_at}\n  event: phase          data: {name, elapsed_ms, ...payload}\n  event: chunk          data: {text, elapsed_ms}\n  event: heartbeat      data: {elapsed_ms}\n  event: task_completed data: {task, artifacts, metadata}\n  event: task_failed    data: {error, task_id}\n  data: [DONE]\n\nPhases come from CitadelEngine.process_query_stream and match the names\nsurfaced on /api/query/stream (retrieval_start, retrieval_complete,\narena_start, arena_complete, synthesis_start, etc.).","operationId":"streamMessage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__routes__a2a__SendMessageRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"`invalid_request` (-32600): The request is malformed: empty message, message over 500,000 characters, or a signup or billing field with a value the API does not accept.\n\n`invalid_params` (-32602): A parameter has a value outside its allowed set, for example metadata.depth other than base or auto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":-32600,"type":"invalid_request","message":"Message must contain at least one non-empty text part","doc_url":"https://dnai.systems/a2a#err-invalid_request","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Message must contain at least one non-empty text part"}},"invalid_params":{"summary":"invalid_params","value":{"error":{"code":-32602,"type":"invalid_params","message":"metadata.depth must be 'base' or 'auto'","doc_url":"https://dnai.systems/a2a#err-invalid_params","param":"metadata.depth","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"metadata.depth must be 'base' or 'auto'"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"`validation_error` (-32602): The body does not match the schema (wrong type, missing required field). error.fields lists each failing field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validation_error":{"summary":"validation_error","value":{"error":{"code":-32602,"type":"validation_error","message":"message.parts: Field required","doc_url":"https://dnai.systems/a2a#err-validation_error","param":"message.parts","fields":[{"loc":["body","message","parts"],"msg":"Field required","type":"missing"}],"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"message.parts: Field required"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"`permission_denied` (-32051): The key may not call this agent or operation (Asha keys reach Asha only; internal agents are never reachable).\n\n`account_suspended` (-32051): The account is suspended, usually after a failed payment. Fix billing in the portal; access resumes when the invoice is paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permission_denied":{"summary":"permission_denied","value":{"error":{"code":-32051,"type":"permission_denied","message":"API key does not have access to agent 'leo'","doc_url":"https://dnai.systems/a2a#err-permission_denied","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"API key does not have access to agent 'leo'"}},"account_suspended":{"summary":"account_suspended","value":{"error":{"code":-32051,"type":"account_suspended","message":"Account suspended. Check billing at /api/a2a/portal.","doc_url":"https://dnai.systems/a2a#err-account_suspended","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Account suspended. Check billing at /api/a2a/portal."}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"410":{"description":"`agent_retired` (-32054): The agent was retired and no longer answers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"agent_retired":{"summary":"agent_retired","value":{"error":{"code":-32054,"type":"agent_retired","message":"agent sage is retired","doc_url":"https://dnai.systems/a2a#err-agent_retired","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"agent sage is retired"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"429":{"description":"`rate_limited` (-32060): Too many requests in the last 60 seconds. Wait retry_after seconds.\n\n`daily_quota_exceeded` (-32061): The daily query allowance is used up. Resets at 00:00 UTC.\n\n`monthly_quota_exceeded` (-32062): The monthly query allowance is used up. Resets on the 1st at 00:00 UTC, or upgrade the plan.\n\n`spending_cap_reached` (-32063): Estimated spend this month reached the account's cap. Resets on the 1st, or raise the cap by upgrading.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"code":-32060,"type":"rate_limited","message":"Rate limit exceeded: 10 requests/minute","doc_url":"https://dnai.systems/a2a#err-rate_limited","retry_after":60,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Rate limit exceeded: 10 requests/minute"}},"daily_quota_exceeded":{"summary":"daily_quota_exceeded","value":{"error":{"code":-32061,"type":"daily_quota_exceeded","message":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-daily_quota_exceeded","retry_after":21600,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more."}},"monthly_quota_exceeded":{"summary":"monthly_quota_exceeded","value":{"error":{"code":-32062,"type":"monthly_quota_exceeded","message":"Monthly query limit reached (50/50). Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-monthly_quota_exceeded","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Monthly query limit reached (50/50). Upgrade tier for more."}},"spending_cap_reached":{"summary":"spending_cap_reached","value":{"error":{"code":-32063,"type":"spending_cap_reached","message":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap.","doc_url":"https://dnai.systems/a2a#err-spending_cap_reached","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap."}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -N -X POST https://api.askasha.org/a2a/v1/message:stream \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"agent_id\": \"asha\", \"message\": {\"role\": \"user\", \"parts\": [{\"text\": \"What is sepsis?\"}]}}'"}]}},"/a2a/v1/tasks/{task_id}":{"get":{"tags":["A2A"],"summary":"Get a task","description":"Retrieve a task by ID (cache then PostgreSQL fallback).","operationId":"getTask","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`task_not_found` (-32001): The task id does not exist or belongs to another key (A2A TaskNotFoundError).","content":{"application/json":{"examples":{"task_not_found":{"summary":"task_not_found","value":{"error":{"code":-32001,"type":"task_not_found","message":"Task 0b1c... not found","doc_url":"https://dnai.systems/a2a#err-task_not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Task 0b1c... not found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"`account_suspended` (-32051): The account is suspended, usually after a failed payment. Fix billing in the portal; access resumes when the invoice is paid.","content":{"application/json":{"examples":{"account_suspended":{"summary":"account_suspended","value":{"error":{"code":-32051,"type":"account_suspended","message":"Account suspended. Check billing at /api/a2a/portal.","doc_url":"https://dnai.systems/a2a#err-account_suspended","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Account suspended. Check billing at /api/a2a/portal."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"429":{"description":"`rate_limited` (-32060): Too many requests in the last 60 seconds. Wait retry_after seconds.\n\n`daily_quota_exceeded` (-32061): The daily query allowance is used up. Resets at 00:00 UTC.\n\n`monthly_quota_exceeded` (-32062): The monthly query allowance is used up. Resets on the 1st at 00:00 UTC, or upgrade the plan.\n\n`spending_cap_reached` (-32063): Estimated spend this month reached the account's cap. Resets on the 1st, or raise the cap by upgrading.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"code":-32060,"type":"rate_limited","message":"Rate limit exceeded: 10 requests/minute","doc_url":"https://dnai.systems/a2a#err-rate_limited","retry_after":60,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Rate limit exceeded: 10 requests/minute"}},"daily_quota_exceeded":{"summary":"daily_quota_exceeded","value":{"error":{"code":-32061,"type":"daily_quota_exceeded","message":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-daily_quota_exceeded","retry_after":21600,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more."}},"monthly_quota_exceeded":{"summary":"monthly_quota_exceeded","value":{"error":{"code":-32062,"type":"monthly_quota_exceeded","message":"Monthly query limit reached (50/50). Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-monthly_quota_exceeded","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Monthly query limit reached (50/50). Upgrade tier for more."}},"spending_cap_reached":{"summary":"spending_cap_reached","value":{"error":{"code":-32063,"type":"spending_cap_reached","message":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap.","doc_url":"https://dnai.systems/a2a#err-spending_cap_reached","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl https://api.askasha.org/a2a/v1/tasks/$TASK_ID \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\""}]}},"/a2a/v1/tasks":{"get":{"tags":["A2A"],"summary":"List tasks","description":"List tasks with optional filtering and pagination (PostgreSQL-backed).\n\nTasks are scoped to the caller's API key per A2A v1.0 §4.3.\nMaster key can see all tasks.","operationId":"listTasks","parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"}},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskListResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"`validation_error` (-32602): The body does not match the schema (wrong type, missing required field). error.fields lists each failing field.","content":{"application/json":{"examples":{"validation_error":{"summary":"validation_error","value":{"error":{"code":-32602,"type":"validation_error","message":"message.parts: Field required","doc_url":"https://dnai.systems/a2a#err-validation_error","param":"message.parts","fields":[{"loc":["body","message","parts"],"msg":"Field required","type":"missing"}],"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"message.parts: Field required"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"`account_suspended` (-32051): The account is suspended, usually after a failed payment. Fix billing in the portal; access resumes when the invoice is paid.","content":{"application/json":{"examples":{"account_suspended":{"summary":"account_suspended","value":{"error":{"code":-32051,"type":"account_suspended","message":"Account suspended. Check billing at /api/a2a/portal.","doc_url":"https://dnai.systems/a2a#err-account_suspended","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Account suspended. Check billing at /api/a2a/portal."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"429":{"description":"`rate_limited` (-32060): Too many requests in the last 60 seconds. Wait retry_after seconds.\n\n`daily_quota_exceeded` (-32061): The daily query allowance is used up. Resets at 00:00 UTC.\n\n`monthly_quota_exceeded` (-32062): The monthly query allowance is used up. Resets on the 1st at 00:00 UTC, or upgrade the plan.\n\n`spending_cap_reached` (-32063): Estimated spend this month reached the account's cap. Resets on the 1st, or raise the cap by upgrading.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"code":-32060,"type":"rate_limited","message":"Rate limit exceeded: 10 requests/minute","doc_url":"https://dnai.systems/a2a#err-rate_limited","retry_after":60,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Rate limit exceeded: 10 requests/minute"}},"daily_quota_exceeded":{"summary":"daily_quota_exceeded","value":{"error":{"code":-32061,"type":"daily_quota_exceeded","message":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-daily_quota_exceeded","retry_after":21600,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more."}},"monthly_quota_exceeded":{"summary":"monthly_quota_exceeded","value":{"error":{"code":-32062,"type":"monthly_quota_exceeded","message":"Monthly query limit reached (50/50). Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-monthly_quota_exceeded","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Monthly query limit reached (50/50). Upgrade tier for more."}},"spending_cap_reached":{"summary":"spending_cap_reached","value":{"error":{"code":-32063,"type":"spending_cap_reached","message":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap.","doc_url":"https://dnai.systems/a2a#err-spending_cap_reached","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/a2a/v1/tasks \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\""}]}},"/a2a/v1/tasks/{task_id}:cancel":{"post":{"tags":["A2A"],"summary":"Cancel a task","description":"Cancel a task if it has not already completed or failed.","operationId":"cancelTask","parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`task_not_found` (-32001): The task id does not exist or belongs to another key (A2A TaskNotFoundError).","content":{"application/json":{"examples":{"task_not_found":{"summary":"task_not_found","value":{"error":{"code":-32001,"type":"task_not_found","message":"Task 0b1c... not found","doc_url":"https://dnai.systems/a2a#err-task_not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Task 0b1c... not found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"409":{"description":"`task_not_cancelable` (-32002): The task already reached a terminal state (A2A TaskNotCancelableError).","content":{"application/json":{"examples":{"task_not_cancelable":{"summary":"task_not_cancelable","value":{"error":{"code":-32002,"type":"task_not_cancelable","message":"Task already in terminal state: COMPLETED","doc_url":"https://dnai.systems/a2a#err-task_not_cancelable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Task already in terminal state: COMPLETED"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"`account_suspended` (-32051): The account is suspended, usually after a failed payment. Fix billing in the portal; access resumes when the invoice is paid.","content":{"application/json":{"examples":{"account_suspended":{"summary":"account_suspended","value":{"error":{"code":-32051,"type":"account_suspended","message":"Account suspended. Check billing at /api/a2a/portal.","doc_url":"https://dnai.systems/a2a#err-account_suspended","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Account suspended. Check billing at /api/a2a/portal."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"429":{"description":"`rate_limited` (-32060): Too many requests in the last 60 seconds. Wait retry_after seconds.\n\n`daily_quota_exceeded` (-32061): The daily query allowance is used up. Resets at 00:00 UTC.\n\n`monthly_quota_exceeded` (-32062): The monthly query allowance is used up. Resets on the 1st at 00:00 UTC, or upgrade the plan.\n\n`spending_cap_reached` (-32063): Estimated spend this month reached the account's cap. Resets on the 1st, or raise the cap by upgrading.","content":{"application/json":{"examples":{"rate_limited":{"summary":"rate_limited","value":{"error":{"code":-32060,"type":"rate_limited","message":"Rate limit exceeded: 10 requests/minute","doc_url":"https://dnai.systems/a2a#err-rate_limited","retry_after":60,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Rate limit exceeded: 10 requests/minute"}},"daily_quota_exceeded":{"summary":"daily_quota_exceeded","value":{"error":{"code":-32061,"type":"daily_quota_exceeded","message":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-daily_quota_exceeded","retry_after":21600,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Daily query limit reached (10/10). Resets at midnight UTC. Upgrade tier for more."}},"monthly_quota_exceeded":{"summary":"monthly_quota_exceeded","value":{"error":{"code":-32062,"type":"monthly_quota_exceeded","message":"Monthly query limit reached (50/50). Upgrade tier for more.","doc_url":"https://dnai.systems/a2a#err-monthly_quota_exceeded","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Monthly query limit reached (50/50). Upgrade tier for more."}},"spending_cap_reached":{"summary":"spending_cap_reached","value":{"error":{"code":-32063,"type":"spending_cap_reached","message":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap.","doc_url":"https://dnai.systems/a2a#err-spending_cap_reached","retry_after":864000,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Spending cap reached ($100.00 of $100.00). Upgrade tier or increase cap."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/a2a/v1/tasks/$TASK_ID:cancel \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\""}]}},"/v1/chat/completions":{"post":{"tags":["OpenAI-compatible"],"summary":"Create a chat completion","operationId":"createChatCompletion","responses":{"200":{"description":"chat.completion (application/json) or chat.completion.chunk events (text/event-stream when stream=true).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"chatcmpl-3f9c2a1b7d6e4f0a9b8c7d6e"},"object":{"type":"string","enum":["chat.completion"]},"created":{"type":"integer"},"model":{"type":"string","example":"dnai/asha"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}},"finish_reason":{"type":"string","enum":["stop"]}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"dnai_token_counts_estimated":{"type":"boolean"}}},"dnai_meta":{"type":"object","description":"Asha extension: present on agent models; asha-apex returns the Apex panel block instead.","properties":{"depth_requested":{"type":"string","enum":["base","auto"]},"depth_served":{"type":"string","enum":["base","mid","apex"]},"evidence_count":{"type":"integer"},"citations":{"type":"array","items":{}},"task_gravity":{"type":"number","nullable":true}}}}}},"text/event-stream":{"schema":{"type":"string","description":"data: {chat.completion.chunk} frames; comment lines (: phase ..., : keep-alive) between them; the finish_reason=stop chunk carries dnai_meta; an optional usage frame; then data: [DONE]."}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"invalid_json, invalid_request, stream_unsupported (asha-apex with stream=true), or no user message. Body: {error: {message, type, code}}.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"Missing or invalid Bearer key (authentication_error).","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"Key cannot reach the model (permission_error); plan_required for asha-apex outside Enterprise.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"model_not_found.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"429":{"description":"Rate or allowance limit (rate_limit_error) with Retry-After.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"Engine not initialized.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"description":"OpenAI wire format, same pipeline as A2A message:send. Set base_url to https://api.askasha.org/v1 and api_key to your Asha key. Models: asha, asha-base, asha-auto (Enterprise), asha-apex (Enterprise, non-streaming); dnai/<id> and <id>-latest are accepted. Customer keys run Base. Non-stream responses begin with whitespace keep-alive bytes every 20 s while Asha works; stream=true returns text/event-stream chunks ending in [DONE].","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"model":{"type":"string","default":"asha","enum":["asha","asha-base","asha-auto","asha-apex"],"description":"Asha and its depth pins. Enterprise unlocks asha-auto and asha-apex."},"messages":{"type":"array","minItems":1,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"description":"String, or an array of {type: text, text} parts.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"text":{"type":"string"}}}}]}}},"description":"The last message must be a user turn. Earlier turns are passed as history; system messages become caller context."},"stream":{"type":"boolean","default":false},"stream_options":{"type":"object","properties":{"include_usage":{"type":"boolean"}}},"metadata":{"type":"object","description":"Asha options, same names as A2A.","properties":{"session_id":{"type":"string","maxLength":64,"description":"Pins a per-key memory identity for continuity."},"audience":{"type":"string","enum":["patient","caregiver","consumer","clinician","nurse","pharmacist","physician","hcp"]},"memory":{"type":"string","enum":["on","off"],"description":"off: no personal-memory read or write."},"verbosity":{"type":"string","enum":["brief","standard","detailed"]},"emoji":{"type":"string","enum":["off","none","on"]},"persona":{"type":"object","description":"White label: {name, organization, tone}, same rules as A2A."}}},"temperature":{"type":"number","description":"Accepted and ignored; the engine sets sampling."},"max_tokens":{"type":"integer","description":"Accepted and ignored."},"user":{"type":"string","description":"Pins the memory identity (same as header X-DNAI-User)."}}},"examples":{"clinician":{"summary":"Non-streaming, clinician register","value":{"model":"asha","messages":[{"role":"user","content":"Which antihypertensives are safe in pregnancy?"}],"metadata":{"audience":"clinician","session_id":"visit-2041"}}},"stream":{"summary":"Streaming with usage","value":{"model":"asha-base","stream":true,"stream_options":{"include_usage":true},"messages":[{"role":"user","content":"Red flags for pediatric fever?"}]}}}}}},"parameters":[{"name":"X-DNAI-User","in":"header","required":false,"schema":{"type":"string"},"description":"Pins the memory identity across requests."},{"name":"X-DNAI-Sources","in":"header","required":false,"schema":{"type":"string","enum":["keep"]},"description":"keep: leave the trailing sources panel in the answer text."}],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/v1/chat/completions \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\": \"asha\", \"messages\": [{\"role\": \"user\", \"content\": \"Which antihypertensives are safe in pregnancy?\"}], \"metadata\": {\"audience\": \"clinician\", \"session_id\": \"visit-2041\"}}'"}]}},"/v1/models":{"get":{"tags":["OpenAI-compatible"],"summary":"List models","description":"Models this key may call, in the OpenAI `/v1/models` shape (`dnai/<id>`).","operationId":"listModels","responses":{"200":{"description":"OpenAI model list","content":{"application/json":{"schema":{"properties":{"object":{"type":"string","enum":["list"]},"data":{"items":{"properties":{"id":{"type":"string","example":"dnai/asha"},"object":{"type":"string","enum":["model"]},"created":{"type":"integer"},"owned_by":{"type":"string","example":"dnai-systems"}},"type":"object"},"type":"array"}},"type":"object"},"example":{"object":"list","data":[{"id":"dnai/asha","object":"model","created":1760000000,"owned_by":"dnai-systems"},{"id":"dnai/asha-base","object":"model","created":1760000000,"owned_by":"dnai-systems"}]}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"Missing or invalid Bearer key.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/v1/models \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\""}]}},"/api/agents":{"get":{"tags":["Discovery"],"summary":"List agents","description":"List all active public agents.","operationId":"listAgents","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/agents"}]}},"/api/agents/{agent_id}":{"get":{"tags":["Discovery"],"summary":"Get an agent","description":"Get details for a specific agent, by domain key (`health`) or legacy id (`asha`).","operationId":"getAgent","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`agent_not_found` (-32052): No public agent has this id or domain key.","content":{"application/json":{"examples":{"agent_not_found":{"summary":"agent_not_found","value":{"error":{"code":-32052,"type":"agent_not_found","message":"Agent 'unknown' not found","doc_url":"https://dnai.systems/a2a#err-agent_not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Agent 'unknown' not found"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/agents/$AGENT_ID"}]}},"/api/agents/{agent_id}/skill":{"get":{"tags":["Discovery"],"summary":"Get an agent's skill file","description":"Serve agent SKILL.md content for public discovery (Claim H6).\n\nPublic agents only. Internal agents (dhruva, zeno, kavi, shilpa) and the\noperational skills that share `.cursor/skills/` (deploy, ingest, sentinel,\n...) carry host paths and procedures; they answer 404, same as the\ncatalog detail route, so existence is not disclosed either.","operationId":"getAgentSkill","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"string","title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"`invalid_request` (-32600): The request is malformed: empty message, message over 500,000 characters, or a signup or billing field with a value the API does not accept.","content":{"application/json":{"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":-32600,"type":"invalid_request","message":"Message must contain at least one non-empty text part","doc_url":"https://dnai.systems/a2a#err-invalid_request","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Message must contain at least one non-empty text part"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`not_found` (-32052): The account, billing record, or resource does not exist for this key.","content":{"application/json":{"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":-32052,"type":"not_found","message":"Customer not found for this API key","doc_url":"https://dnai.systems/a2a#err-not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Customer not found for this API key"}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/agents/$AGENT_ID/skill"}]}},"/api/feng/falsify":{"post":{"tags":["Falsification"],"summary":"Falsify a claim","description":"Accept a claim, run Popperian falsification, return verdict with evidence.","operationId":"falsifyClaim","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__routes__feng__FalsifyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"`permission_denied` (-32051): The key may not call this agent or operation (Asha keys reach Asha only; internal agents are never reachable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permission_denied":{"summary":"permission_denied","value":{"error":{"code":-32051,"type":"permission_denied","message":"API key does not have access to agent 'leo'","doc_url":"https://dnai.systems/a2a#err-permission_denied","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"API key does not have access to agent 'leo'"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"`validation_error` (-32602): The body does not match the schema (wrong type, missing required field). error.fields lists each failing field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validation_error":{"summary":"validation_error","value":{"error":{"code":-32602,"type":"validation_error","message":"message.parts: Field required","doc_url":"https://dnai.systems/a2a#err-validation_error","param":"message.parts","fields":[{"loc":["body","message","parts"],"msg":"Field required","type":"missing"}],"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"message.parts: Field required"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"500":{"description":"`internal_error` (-32603): Unexpected server error. Quote error.error_id to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":-32603,"type":"internal_error","message":"Internal server error","doc_url":"https://dnai.systems/a2a#err-internal_error","error_id":"3f2a9c1b7d4e","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Internal server error"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[{"dnai_session":[]}],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/api/feng/falsify \\\n  -H \"Authorization: Bearer $DNAI_SESSION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"claim\": \"Metformin is first-line therapy for most adults with type 2 diabetes.\", \"k\": 10}'"}]}},"/api/a2a/signup":{"post":{"tags":["Keys and billing"],"summary":"Create a free API key","description":"Create an A2A API account. Returns API key (shown ONCE).\n\nAnti-abuse layers (in order):\n  1. Email format validation (regex).\n  2. Optional hCaptcha verification (when HCAPTCHA_SECRET env is set).\n  3. Per-IP daily cap (A2A_SIGNUP_PER_IP_DAILY, default 10/24h).\n  4. Per-email account-exists check (409).","operationId":"createApiKey","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/api__routes__a2a_billing__SignupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"`invalid_request` (-32600): The request is malformed: empty message, message over 500,000 characters, or a signup or billing field with a value the API does not accept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":-32600,"type":"invalid_request","message":"Message must contain at least one non-empty text part","doc_url":"https://dnai.systems/a2a#err-invalid_request","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Message must contain at least one non-empty text part"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"`validation_error` (-32602): The body does not match the schema (wrong type, missing required field). error.fields lists each failing field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validation_error":{"summary":"validation_error","value":{"error":{"code":-32602,"type":"validation_error","message":"message.parts: Field required","doc_url":"https://dnai.systems/a2a#err-validation_error","param":"message.parts","fields":[{"loc":["body","message","parts"],"msg":"Field required","type":"missing"}],"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"message.parts: Field required"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"409":{"description":"`conflict` (-32053): The resource already exists, for example a second signup with the same email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"conflict":{"summary":"conflict","value":{"error":{"code":-32053,"type":"conflict","message":"Account already exists for you@example.com. Use /api/a2a/rotate-key to get a new key.","doc_url":"https://dnai.systems/a2a#err-conflict","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Account already exists for you@example.com. Use /api/a2a/rotate-key to get a new key."}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"429":{"description":"`signup_rate_limited` (-32064): Too many new keys from this network in 24 hours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"signup_rate_limited":{"summary":"signup_rate_limited","value":{"error":{"code":-32064,"type":"signup_rate_limited","message":"Too many signups from this network (10 per 24h). Retry in ~60 minutes.","doc_url":"https://dnai.systems/a2a#err-signup_rate_limited","retry_after":3600,"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Too many signups from this network (10 per 24h). Retry in ~60 minutes."}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/api/a2a/signup \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\": \"you@example.com\", \"product\": \"asha\"}'"}]}},"/api/a2a/usage":{"get":{"tags":["Keys and billing"],"summary":"Get usage and limits","description":"Get current usage stats for the authenticated API key.","operationId":"getUsage","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`not_found` (-32052): The account, billing record, or resource does not exist for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":-32052,"type":"not_found","message":"Customer not found for this API key","doc_url":"https://dnai.systems/a2a#err-not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Customer not found for this API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl https://api.askasha.org/api/a2a/usage \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\""}]}},"/api/a2a/preferences":{"get":{"tags":["Keys and billing"],"summary":"Get saved agent preferences","description":"Read the saved defaults for this key, the values in effect, and the allowed values.","operationId":"getPreferences","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`not_found` (-32052): The account, billing record, or resource does not exist for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":-32052,"type":"not_found","message":"Customer not found for this API key","doc_url":"https://dnai.systems/a2a#err-not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Customer not found for this API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/a2a/preferences \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\""}]},"put":{"tags":["Keys and billing"],"summary":"Save agent preferences","description":"Replace the saved defaults for this key. Send `{}` to reset to defaults.","operationId":"updatePreferences","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferencesRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"`invalid_params` (-32602): A parameter has a value outside its allowed set, for example metadata.depth other than base or auto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_params":{"summary":"invalid_params","value":{"error":{"code":-32602,"type":"invalid_params","message":"metadata.depth must be 'base' or 'auto'","doc_url":"https://dnai.systems/a2a#err-invalid_params","param":"metadata.depth","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"metadata.depth must be 'base' or 'auto'"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"`validation_error` (-32602): The body does not match the schema (wrong type, missing required field). error.fields lists each failing field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validation_error":{"summary":"validation_error","value":{"error":{"code":-32602,"type":"validation_error","message":"message.parts: Field required","doc_url":"https://dnai.systems/a2a#err-validation_error","param":"message.parts","fields":[{"loc":["body","message","parts"],"msg":"Field required","type":"missing"}],"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"message.parts: Field required"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`not_found` (-32052): The account, billing record, or resource does not exist for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":-32052,"type":"not_found","message":"Customer not found for this API key","doc_url":"https://dnai.systems/a2a#err-not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Customer not found for this API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X PUT https://api.askasha.org/api/a2a/preferences \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"persona\": {\"name\": \"CareBot\", \"organization\": \"Acme Health\"}, \"verbosity\": \"brief\", \"emoji\": \"off\"}'"},{"lang":"Shell","label":"asha CLI","source":"asha config set name=CareBot org=\"Acme Health\" verbosity=brief emoji=off"}]}},"/api/a2a/upgrade":{"post":{"tags":["Keys and billing"],"summary":"Start a plan upgrade","description":"Upgrade to a paid tier. Returns Stripe Checkout URL.","operationId":"createUpgradeCheckout","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"`invalid_request` (-32600): The request is malformed: empty message, message over 500,000 characters, or a signup or billing field with a value the API does not accept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":-32600,"type":"invalid_request","message":"Message must contain at least one non-empty text part","doc_url":"https://dnai.systems/a2a#err-invalid_request","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Message must contain at least one non-empty text part"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"`validation_error` (-32602): The body does not match the schema (wrong type, missing required field). error.fields lists each failing field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validation_error":{"summary":"validation_error","value":{"error":{"code":-32602,"type":"validation_error","message":"message.parts: Field required","doc_url":"https://dnai.systems/a2a#err-validation_error","param":"message.parts","fields":[{"loc":["body","message","parts"],"msg":"Field required","type":"missing"}],"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"message.parts: Field required"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`not_found` (-32052): The account, billing record, or resource does not exist for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":-32052,"type":"not_found","message":"Customer not found for this API key","doc_url":"https://dnai.systems/a2a#err-not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Customer not found for this API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"500":{"description":"`internal_error` (-32603): Unexpected server error. Quote error.error_id to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":-32603,"type":"internal_error","message":"Internal server error","doc_url":"https://dnai.systems/a2a#err-internal_error","error_id":"3f2a9c1b7d4e","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Internal server error"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/api/a2a/upgrade \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tier\": \"developer\"}'"},{"lang":"Shell","label":"asha CLI","source":"asha upgrade developer --open"}]}},"/api/a2a/topup":{"post":{"tags":["Keys and billing"],"summary":"Top up prepaid API credits","description":"Purchase prepaid pay-as-you-go API credits ($10 to $1,000). Returns Stripe Checkout URL.","operationId":"topupCredits","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"`invalid_request` (-32600): The request is malformed: empty message, message over 500,000 characters, or a signup or billing field with a value the API does not accept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":-32600,"type":"invalid_request","message":"Message must contain at least one non-empty text part","doc_url":"https://dnai.systems/a2a#err-invalid_request","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Message must contain at least one non-empty text part"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"`validation_error` (-32602): The body does not match the schema (wrong type, missing required field). error.fields lists each failing field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"validation_error":{"summary":"validation_error","value":{"error":{"code":-32602,"type":"validation_error","message":"message.parts: Field required","doc_url":"https://dnai.systems/a2a#err-validation_error","param":"message.parts","fields":[{"loc":["body","message","parts"],"msg":"Field required","type":"missing"}],"request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"message.parts: Field required"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`not_found` (-32052): The account, billing record, or resource does not exist for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":-32052,"type":"not_found","message":"Customer not found for this API key","doc_url":"https://dnai.systems/a2a#err-not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Customer not found for this API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"500":{"description":"`internal_error` (-32603): Unexpected server error. Quote error.error_id to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":-32603,"type":"internal_error","message":"Internal server error","doc_url":"https://dnai.systems/a2a#err-internal_error","error_id":"3f2a9c1b7d4e","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Internal server error"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/api/a2a/topup \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"amount_usd\": 10}'"},{"lang":"Shell","label":"asha CLI","source":"asha topup 10 --open"}]}},"/api/a2a/portal":{"get":{"tags":["Keys and billing"],"summary":"Open the billing portal","description":"Redirect to Stripe Customer Portal for billing management.","operationId":"getBillingPortal","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`not_found` (-32052): The account, billing record, or resource does not exist for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":-32052,"type":"not_found","message":"Customer not found for this API key","doc_url":"https://dnai.systems/a2a#err-not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Customer not found for this API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"500":{"description":"`internal_error` (-32603): Unexpected server error. Quote error.error_id to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"code":-32603,"type":"internal_error","message":"Internal server error","doc_url":"https://dnai.systems/a2a#err-internal_error","error_id":"3f2a9c1b7d4e","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Internal server error"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/a2a/portal \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\""}]}},"/api/a2a/rotate-key":{"post":{"tags":["Keys and billing"],"summary":"Rotate the API key","description":"Rotate API key. Returns new key (shown ONCE). Old key is invalidated.","operationId":"rotateApiKey","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"`invalid_request` (-32600): The request is malformed: empty message, message over 500,000 characters, or a signup or billing field with a value the API does not accept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_request":{"summary":"invalid_request","value":{"error":{"code":-32600,"type":"invalid_request","message":"Message must contain at least one non-empty text part","doc_url":"https://dnai.systems/a2a#err-invalid_request","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Message must contain at least one non-empty text part"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"`authentication_required` (-32050): No Authorization: Bearer header was sent.\n\n`invalid_api_key` (-32050): The key is unknown, mistyped, or was rotated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"authentication_required":{"summary":"authentication_required","value":{"error":{"code":-32050,"type":"authentication_required","message":"A2A authentication required. Provide Authorization: Bearer <api_key>","doc_url":"https://dnai.systems/a2a#err-authentication_required","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"A2A authentication required. Provide Authorization: Bearer <api_key>"}},"invalid_api_key":{"summary":"invalid_api_key","value":{"error":{"code":-32050,"type":"invalid_api_key","message":"Invalid A2A API key","doc_url":"https://dnai.systems/a2a#err-invalid_api_key","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Invalid A2A API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"`not_found` (-32052): The account, billing record, or resource does not exist for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"not_found","value":{"error":{"code":-32052,"type":"not_found","message":"Customer not found for this API key","doc_url":"https://dnai.systems/a2a#err-not_found","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Customer not found for this API key"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"`service_unavailable` (-32070): A dependency (engine, database, signup store) is temporarily down. Retry after a short wait.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_unavailable":{"summary":"service_unavailable","value":{"error":{"code":-32070,"type":"service_unavailable","message":"Database unavailable","doc_url":"https://dnai.systems/a2a#err-service_unavailable","request_id":"9b2e6c1a-4f3d-4a8e-b1c7-2d5e8f0a3c61"},"detail":"Database unavailable"}}}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/api/a2a/rotate-key \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\""}]}},"/api/a2a/baa":{"get":{"tags":["BAA"],"summary":"Read the BAA","description":"The current Business Associate Agreement with its version and SHA-256.","operationId":"getBaa","parameters":[{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"md for Markdown, html for a page; default JSON","title":"Format"},"description":"md for Markdown, html for a page; default JSON"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/a2a/baa"}]}},"/api/a2a/baa/accept":{"post":{"tags":["BAA"],"summary":"Accept the BAA","description":"Record acceptance of the current agreement for the calling key's account.\n\nBody: organization, signer_name, signer_title, signer_email, attest_authority (true),\naccept_version (must equal the current version), optional accept_sha256.","operationId":"acceptBaa","requestBody":{"content":{"application/json":{"schema":{"properties":{"organization":{"type":"string","maxLength":200},"signer_name":{"type":"string","maxLength":120},"signer_title":{"type":"string","maxLength":120},"signer_email":{"type":"string","format":"email"},"attest_authority":{"type":"boolean","enum":[true],"description":"Must be true: the signer attests authority to bind the organization."},"accept_version":{"type":"string","description":"Must equal the current version from GET /api/a2a/baa."},"accept_sha256":{"type":"string","description":"Optional; must equal the current document SHA-256 when supplied."},"source":{"type":"string","description":"Free text, max 32 chars (for example cli, console)."}},"type":"object","required":["organization","signer_name","signer_title","signer_email","attest_authority","accept_version"]},"example":{"organization":"Acme Health","signer_name":"Jane Doe","signer_title":"CTO","signer_email":"jane@acme.health","attest_authority":true,"accept_version":"0.2-draft"}}},"required":true},"responses":{"200":{"description":"Receipt","content":{"application/json":{"schema":{"properties":{"acceptance_id":{"type":"string","format":"uuid"},"accepted_at":{"type":"string","format":"date-time"},"baa_version":{"type":"string"},"baa_sha256":{"type":"string"},"document_status":{"type":"string"},"organization":{"type":"string"},"signer":{"properties":{"name":{"type":"string"},"title":{"type":"string"},"email":{"type":"string"}},"type":"object"},"phi_allowed":{"type":"boolean"},"phi_readiness":{"properties":{"document_effective":{"type":"boolean"},"document_version":{"type":"string"},"llm_path_covered":{"type":"boolean"},"llm_provider":{"type":"string"},"phi_mode_open":{"type":"boolean"},"blockers":{"items":{"type":"string"},"type":"array"}},"type":"object"},"document_url":{"type":"string"},"note":{"type":"string"}},"type":"object"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Validation failure (missing field, bad email, attest_authority not true, stale accept_version or accept_sha256), or a master/env key with no account.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"Missing or invalid Bearer key.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"404":{"description":"Customer not found for this key.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"503":{"description":"Database unavailable.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X POST https://api.askasha.org/api/a2a/baa/accept \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"organization\": \"Acme Health\", \"signer_name\": \"Jane Doe\", \"signer_title\": \"CTO\", \"signer_email\": \"jane@acme.health\", \"attest_authority\": true, \"accept_version\": \"0.2-draft\"}'"}]}},"/api/a2a/baa/status":{"get":{"tags":["BAA"],"summary":"Get BAA status","description":"Acceptance state for the calling key's account, with PHI readiness.","operationId":"getBaaStatus","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/api/a2a/baa/status \\\n  -H \"Authorization: Bearer $DNAI_API_KEY\""}]}},"/health/live":{"get":{"tags":["Discovery"],"summary":"Liveness probe","description":"Kubernetes liveness probe","operationId":"getLiveness","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/health/live"}]}},"/.well-known/agent-card.json":{"get":{"summary":"Get the fleet agent card","description":"Serve A2A Agent Card(s) for discovery by external agents and registries.","operationId":"getFleetAgentCard","parameters":[{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}},"tags":["Discovery"],"security":[],"x-codeSamples":[{"lang":"Shell","label":"curl","source":"curl -X GET https://api.askasha.org/.well-known/agent-card.json"}]}}},"components":{"schemas":{"URLIngestionRequest":{"properties":{"url":{"type":"string","title":"Url","description":"URL to ingest (web page or YouTube)"},"collection_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Name","description":"Target collection name"},"visibility":{"type":"string","title":"Visibility","description":"Collection visibility: private or shared","default":"private"}},"type":"object","required":["url"],"title":"URLIngestionRequest","description":"Request to ingest content from a URL.","examples":[{"url":"https://example.com/clinic-handbook","visibility":"private"}]},"Body_upload_knowledge_api_agents__agent_id__knowledge_post":{"properties":{"files":{"items":{"type":"string","format":"binary"},"type":"array","title":"Files"},"collection_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Name"},"visibility":{"type":"string","title":"Visibility","default":"private"}},"type":"object","required":["files"],"title":"Body_upload_knowledge_api_agents__agent_id__knowledge_post"},"SendMessageResponse":{"properties":{"task":{"$ref":"#/components/schemas/A2ATask"}},"type":"object","required":["task"],"title":"SendMessageResponse","examples":[{"task":{"artifacts":[{"index":0,"name":"response","parts":[{"text":"For most adults with type 2 diabetes, metformin is the usual first medicine, alongside diet and activity changes..."}]},{"index":1,"name":"provenance","parts":[{"data":{"citations":[],"contract_hash":"<sha256>","evidence_count":8,"model":"<model id>","predicate_scope":[],"sources":["clinical_guidelines","pubmed_abstracts"]}}]}],"created_at":"2026-10-12T21:03:51.004Z","id":"6f1c2a4e-8b3d-4c1e-9a7f-2d5b8e0c4a11","metadata":{"agent_id":"asha","caller":"dnai_a2a_Ab","depth_served":"base","domain":"health","evidence_count":8,"input_tokens":14,"output_tokens":412,"session_id":"demo-session-1"},"status":{"state":"COMPLETED","timestamp":"2026-10-12T21:04:09.512Z"},"updated_at":"2026-10-12T21:04:09.512Z"}}]},"A2ATask":{"properties":{"id":{"type":"string","title":"Id","description":"Task UUID. Retrieve it later with GET /a2a/v1/tasks/{id}."},"status":{"$ref":"#/components/schemas/A2ATaskStatus"},"artifacts":{"items":{"$ref":"#/components/schemas/A2AArtifact"},"type":"array","title":"Artifacts","default":[]},"metadata":{"type":"object","title":"Metadata","description":"agent_id, domain, caller (your key prefix), input_tokens, output_tokens, evidence_count, citations (up to 10), sources (up to 10), depth_served (base, mid, apex), task_gravity, and session_id / persona when supplied.","default":{}},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"}},"type":"object","required":["id","status","created_at","updated_at"],"title":"A2ATask"},"A2AArtifact":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"`response` (index 0, Markdown answer) or `provenance` (index 1, evidence object)."},"parts":{"items":{"$ref":"#/components/schemas/A2APart"},"type":"array","title":"Parts"},"index":{"type":"integer","title":"Index","default":0}},"type":"object","required":["parts"],"title":"A2AArtifact"},"A2APart":{"properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text","description":"Text content. Requests need at least one non-empty text part."},"data":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Data","description":"Structured content. The provenance artifact puts its object here."},"media_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Media Type","description":"Optional MIME type of the part."}},"type":"object","title":"A2APart"},"A2ATaskStatus":{"properties":{"state":{"type":"string","title":"State","description":"One of SUBMITTED, WORKING, COMPLETED, FAILED, CANCELED."},"message":{"anyOf":[{"$ref":"#/components/schemas/A2AMessage"},{"type":"null"}],"description":"On FAILED, an agent message whose text explains the failure."},"timestamp":{"type":"string","title":"Timestamp","description":"ISO 8601 UTC time of the last state change."}},"type":"object","required":["state","timestamp"],"title":"A2ATaskStatus"},"A2AMessage":{"properties":{"role":{"type":"string","title":"Role","description":"`user` on requests; `agent` on messages the service returns."},"parts":{"items":{"$ref":"#/components/schemas/A2APart"},"type":"array","title":"Parts","description":"Ordered parts. Text parts are concatenated into the question."}},"type":"object","required":["role","parts"],"title":"A2AMessage"},"api__routes__a2a_billing__SignupRequest":{"properties":{"email":{"type":"string","title":"Email","description":"Customer email"},"name":{"type":"string","title":"Name","description":"Customer or company name","default":""},"tier":{"type":"string","title":"Tier","description":"Tier: free, developer, pro, enterprise","default":"free"},"product":{"type":"string","title":"Product","description":"Minting surface that fixes the key's agent scope: 'dnai' (every public engine, dnai.systems/developers) or 'asha' (Asha only, askasha.org/developers).","default":"dnai"},"hcaptcha_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Hcaptcha Token","description":"hCaptcha response token. Required only when HCAPTCHA_SECRET is set server-side."}},"type":"object","required":["email"],"title":"SignupRequest","examples":[{"email":"you@example.com","name":"Example Health","product":"asha","tier":"free"}]},"PreferencesRequest":{"properties":{"persona":{"anyOf":[{"$ref":"#/components/schemas/PersonaPreference"},{"type":"null"}],"description":"White label. Omit or null to answer as Asha."},"audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audience","description":"patient | caregiver | clinician (and synonyms; see docs)."},"verbosity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verbosity","description":"brief | standard | detailed. Default standard."},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Emoji","description":"off (default) | none | on."},"memory":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Memory","description":"on (default) | off."}},"additionalProperties":false,"type":"object","title":"PreferencesRequest","description":"Defaults for every call made with this key. Request `metadata` overrides any of them.","examples":[{"audience":"patient","emoji":"off","persona":{"name":"CareBot","organization":"Acme Health","tone":"warm"},"verbosity":"brief"}]},"PersonaPreference":{"properties":{"name":{"type":"string","maxLength":32,"title":"Name","description":"Product name the agent answers as (up to 4 words)."},"organization":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Organization","description":"Your company or clinic (up to 8 words)."},"tone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tone","description":"warm | clinical | concise | friendly | formal"}},"type":"object","required":["name"],"title":"PersonaPreference"},"UpgradeRequest":{"properties":{"tier":{"type":"string","title":"Tier","description":"Target tier: developer, pro, enterprise"}},"type":"object","required":["tier"],"title":"UpgradeRequest","examples":[{"tier":"developer"}]},"TaskListResponse":{"properties":{"tasks":{"items":{"$ref":"#/components/schemas/A2ATask"},"type":"array","title":"Tasks"},"total":{"type":"integer","title":"Total"},"offset":{"type":"integer","title":"Offset"},"limit":{"type":"integer","title":"Limit"}},"type":"object","required":["tasks","total","offset","limit"],"title":"TaskListResponse"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorObject"},"detail":{"title":"Detail","description":"Legacy field kept unchanged for older clients. New code should read `error`."}},"type":"object","required":["error"],"title":"ErrorResponse"},"ErrorObject":{"properties":{"code":{"type":"integer","title":"Code","description":"JSON-RPC style number. Shared by related types; branch on `type`."},"type":{"type":"string","title":"Type","description":"Stable cause identifier, unique per cause. See the error table."},"message":{"type":"string","title":"Message","description":"Human-readable explanation. Wording may change; do not parse it."},"retry_after":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After","description":"Seconds until retrying can succeed (429, some 409 and 503). Also sent as the Retry-After header."},"doc_url":{"type":"string","title":"Doc Url","description":"Link to this error type in the error reference."},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"The request field or header the error is about, as a dotted path (for example `metadata.depth`)."},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"Same value as the X-Request-ID response header. Quote it to support."},"fields":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Fields","description":"validation_error only: each failing field as {loc, msg, type}."},"error_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Id","description":"internal_error only: quote this to support."}},"type":"object","required":["code","type","message","doc_url"],"title":"ErrorObject"},"api__routes__feng__FalsifyRequest":{"properties":{"claim":{"type":"string","maxLength":2000,"minLength":5,"title":"Claim"},"collections":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Collections"},"k":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"K","default":10}},"type":"object","required":["claim"],"title":"FalsifyRequest","examples":[{"claim":"Metformin is first-line therapy for most adults with type 2 diabetes.","k":10}]},"TopupRequest":{"properties":{"amount_usd":{"type":"integer","maximum":1000.0,"minimum":10.0,"title":"Amount Usd","description":"Prepaid credit top-up amount in USD ($10 to $1,000).","default":10}},"type":"object","title":"TopupRequest","examples":[{"amount_usd":25}]},"SignupResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"key_prefix":{"type":"string","title":"Key Prefix"},"email":{"type":"string","title":"Email"},"tier":{"type":"string","title":"Tier"},"monthly_limit":{"type":"integer","title":"Monthly Limit"},"daily_limit":{"type":"integer","title":"Daily Limit"},"spending_cap_usd":{"type":"number","title":"Spending Cap Usd"},"product":{"type":"string","title":"Product","default":"dnai"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"warning":{"type":"string","title":"Warning","default":"Save this API key now. It will not be shown again."}},"type":"object","required":["api_key","key_prefix","email","tier","monthly_limit","daily_limit","spending_cap_usd"],"title":"SignupResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"api__routes__a2a__SendMessageRequest":{"properties":{"message":{"allOf":[{"$ref":"#/components/schemas/A2AMessage"}],"description":"The question, as an A2A message with role `user`."},"metadata":{"properties":{"session_id":{"type":"string","maxLength":64,"description":"Continues a conversation. Longer values are truncated to 64 characters."},"audience":{"type":"string","enum":["patient","consumer","caregiver","principal","clinician","physician","nurse","pharmacist","hcp","professional","healthcare_professional"],"description":"Answer register. Unrecognized values are ignored."},"depth":{"type":"string","enum":["base","auto"],"description":"`auto` is honored on Enterprise only; other plans run `base`. Any other value is 400 invalid_params."},"persona":{"properties":{"name":{"type":"string","maxLength":32,"description":"Up to 4 words."},"organization":{"type":"string","maxLength":60,"description":"Up to 8 words."},"tone":{"type":"string","enum":["warm","clinical","concise","friendly","formal"]}},"type":"object","description":"Your name on the answer. A name shaped like a credential or an instruction is dropped."},"memory":{"type":"string","enum":["on","off"],"description":"`off` runs without conversation memory."},"verbosity":{"type":"string","enum":["brief","standard","detailed"],"description":"Answer length. Safety warnings and citations stay at every length. Default `standard`."},"emoji":{"type":"string","enum":["off","none","on"],"description":"`off` (default): no expressive emoji. `none`: plain text only (check and warning marks as text characters). `on`: up to two, never in crisis, grief, clinician, or document replies."},"agent_id":{"type":"string","description":"Alternative to the top-level agent_id."}},"additionalProperties":true,"type":"object","title":"Metadata","description":"Optional settings for this request. Keys not listed here are reserved for internal use; do not send them.","default":{}},"agent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Id","description":"Agent id or domain key (for example `asha` or `health`). Defaults to asha. Also accepted as metadata.agent_id."}},"type":"object","required":["message"],"title":"SendMessageRequest","examples":[{"agent_id":"asha","message":{"parts":[{"text":"What is the first-line treatment for type 2 diabetes in adults?"}],"role":"user"},"metadata":{"depth":"base","session_id":"demo-session-1"}}]}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"},"bearer":{"type":"http","scheme":"bearer","description":"A2A API key from POST /api/a2a/signup (free tier, no card)."},"dnai_session":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Signed-in DNAi account session (JWT). API keys are not accepted on these operations."}},"headers":{"XRequestId":{"description":"Unique id for this request; also in error.request_id. Quote it to support.","schema":{"type":"string"}}}},"security":[{"bearer":[]}],"tags":[{"name":"A2A","description":"Ask an agent, stream the answer, and manage tasks."},{"name":"Keys and billing","description":"Create, check, rotate, and upgrade API keys."},{"name":"OpenAI-compatible","description":"Drop-in `/v1` routes for OpenAI SDKs."},{"name":"Discovery","description":"Agent cards, the catalog, and health probes."},{"name":"Falsification","description":"Test a claim against the corpus."},{"name":"Agent knowledge","description":"Bring your own documents to an agent."},{"name":"BAA","description":"Read, accept, and check the Business Associate Agreement."},{"name":"Benchmarks","description":"The public benchmark register."},{"name":"Audit","description":"Cryptographic commitment to the corpus."}]}