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

ItemValue
Base URLhttps://api.askasha.org
ProtocolA2A v1.0 over HTTPS, JSON bodies. Every response carries the A2A-Version: 1.0 header.
AuthenticationAuthorization: Bearer <api_key> on every call except signup and health.
Agentasha (alias health). Omitting agent_id defaults to Asha.
Key scopeAsha only. Any other agent id returns 403.
Inputtext/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.
OutputA task with a response artifact (Markdown text) and a provenance artifact (sources, citations, evidence count, model).
Free plan250 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

MethodPathPurposeAuth
POST/a2a/v1/message:sendAsk Asha; returns the completed task.API key
POST/a2a/v1/message:streamSame request, streamed as server-sent events.API key
GET/a2a/v1/tasks/{task_id}Fetch one task.API key
GET/a2a/v1/tasksList your tasks (paginated, filterable).API key
POST/a2a/v1/tasks/{task_id}:cancelCancel a task that is still working.API key
GET/a2a/v1/healthService health.None
POST/api/a2a/signupCreate a free key.None
GET/api/a2a/usageUsage, limits, prepaid balance, and estimated spend for your key.API key
GET, PUT/api/a2a/preferencesSaved defaults for your key: name, tone, audience, length, emoji (Customize your agent).API key
POST/api/a2a/rotate-keyReplace your key; the old one stops at once.API key
POST/api/a2a/topupStripe 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/upgradeStripe checkout for a monthly plan.API key
GET/api/a2a/portalStripe billing portal.API key
POST/v1/chat/completionsOpenAI Chat Completions wire format over Asha (Drop-in with OpenAI SDKs).API key
GET/v1/modelsModel ids for the OpenAI-compatible endpoint.API key
GET/api/a2a/baaCurrent Business Associate Agreement (JSON, Markdown, HTML).None
POST/api/a2a/baa/acceptAccept the agreement for your account (BAA, self-serve).API key
GET/api/a2a/baa/statusAcceptance state and PHI readiness.API key

First call

bash
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

PathBest for
A2A message:send / message:streamFull task records, provenance artifact, pipeline phases.
OpenAI-compatible /v1/chat/completionsExisting OpenAI SDK, LangChain, LiteLLM, or Vercel AI code: change base_url and the key.
asha command lineSetup, 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.
Back to the API page