Asha API
Overview
The Asha API returns Asha's evidence-grounded medical answers over the open A2A v1.0 protocol (HTTP and JSON). Every answer ships with its sources. Keys created on askasha.org reach Asha only.
At a glance
| Item | Value |
|---|---|
| Base URL | https://api.askasha.org |
| Protocol | A2A v1.0 over HTTPS, JSON bodies. Every response carries the A2A-Version: 1.0 header. |
| Authentication | Authorization: Bearer <api_key> on every call except signup and health. |
| Agent | asha (alias health). Omitting agent_id defaults to Asha. |
| Key scope | Asha only. Any other agent id returns 403. |
| Input | text/plain inside JSON message parts: up to 8,000 characters (~2,000 tokens) on Free Sandbox, 100,000 characters on Pay-As-You-Go and Developer, and 500,000 characters on Pro and Enterprise. |
| Output | A task with a response artifact (Markdown text) and a provenance artifact (sources, citations, evidence count, model). |
| Free plan | 250 queries a month, 50 a day (20 RPM), no card. $10 Pay-As-You-Go top-up unlocks 1,000 evaluation queries/month through January 2027. Details in Pricing, limits, and errors. |
Endpoints
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /a2a/v1/message:send | Ask Asha; returns the completed task. | API key |
| POST | /a2a/v1/message:stream | Same request, streamed as server-sent events. | API key |
| GET | /a2a/v1/tasks/{task_id} | Fetch one task. | API key |
| GET | /a2a/v1/tasks | List your tasks (paginated, filterable). | API key |
| POST | /a2a/v1/tasks/{task_id}:cancel | Cancel a task that is still working. | API key |
| GET | /a2a/v1/health | Service health. | None |
| POST | /api/a2a/signup | Create a free key. | None |
| GET | /api/a2a/usage | Usage, limits, prepaid balance, and estimated spend for your key. | API key |
| GET, PUT | /api/a2a/preferences | Saved defaults for your key: name, tone, audience, length, emoji (Customize your agent). | API key |
| POST | /api/a2a/rotate-key | Replace your key; the old one stops at once. | API key |
| POST | /api/a2a/topup | Stripe checkout for a $10+ Pay-As-You-Go prepaid credit top-up (unlocks 1,000 evaluation queries/month through Jan 2027). | API key |
| POST | /api/a2a/upgrade | Stripe checkout for a monthly plan. | API key |
| GET | /api/a2a/portal | Stripe billing portal. | API key |
| POST | /v1/chat/completions | OpenAI Chat Completions wire format over Asha (Drop-in with OpenAI SDKs). | API key |
| GET | /v1/models | Model ids for the OpenAI-compatible endpoint. | API key |
| GET | /api/a2a/baa | Current Business Associate Agreement (JSON, Markdown, HTML). | None |
| POST | /api/a2a/baa/accept | Accept the agreement for your account (BAA, self-serve). | API key |
| GET | /api/a2a/baa/status | Acceptance state and PHI readiness. | API key |
First call
curl -X POST https://api.askasha.org/a2a/v1/message:send \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "asha",
"message": {
"role": "user",
"parts": [{"text": "Which antihypertensives are safe in pregnancy?"}]
},
"metadata": {"audience": "clinician", "session_id": "visit-2041"}
}'Four ways in
| Path | Best for |
|---|---|
A2A message:send / message:stream | Full task records, provenance artifact, pipeline phases. |
OpenAI-compatible /v1/chat/completions | Existing OpenAI SDK, LangChain, LiteLLM, or Vercel AI code: change base_url and the key. |
asha command line | Setup, settings, questions, live checks, and the BAA from a terminal; one file, no dependencies. |
MCP server (asha mcp) | Claude Code, Codex, Cursor, Gemini CLI, VS Code: your coding agent calls Asha and reads these docs as tools. |