# REST API Specs

Amigo exposes two API surfaces, each auto-generated from its OpenAPI spec:

| API                                                                 | Built for                          | Auth                       | OpenAPI Spec                                                  |
| ------------------------------------------------------------------- | ---------------------------------- | -------------------------- | ------------------------------------------------------------- |
| [**Classic**](https://docs.amigo.ai/api-reference/readme/classic)   | Text-based digital health          | Organization-scoped JWT    | [openapi.json](https://api.amigo.ai/v1/openapi.json)          |
| [**Platform**](https://docs.amigo.ai/api-reference/readme/platform) | Enterprise voice & healthcare      | Workspace-scoped API key   | [openapi.json](https://api.platform.amigo.ai/v1/openapi.json) |
| **Data-MCP**                                                        | SQL query access to workspace data | API key + workspace header | N/A (MCP protocol)                                            |

{% content-ref url="readme/classic" %}
[classic](https://docs.amigo.ai/api-reference/readme/classic)
{% endcontent-ref %}

{% content-ref url="readme/platform" %}
[platform](https://docs.amigo.ai/api-reference/readme/platform)
{% endcontent-ref %}

{% content-ref url="change-logs" %}
[change-logs](https://docs.amigo.ai/api-reference/change-logs)
{% endcontent-ref %}

{% hint style="info" %}
**Classic API** covers conversations, users, tools, simulations, and data access. Organization-scoped with per-user JWT auth. Built for consumer-facing digital health products.

**Platform API** covers workspaces, agents, skills, services, integrations, phone numbers, operators, EHR sync, FHIR, CRM, and safety monitoring. Workspace-scoped with API key auth. Built for enterprise voice deployments and healthcare operations. All list endpoints support search filtering, delete operations check for dependencies, and rate limit headers appear on every response.

**Data-MCP** provides SQL query access to workspace data tables through the Model Context Protocol, with tools for querying, profiling, and exploring workspace tables (`sql_query`, `describe_query`, `tables`, `table_schema`, `sample_data`, `table_detail`, `profile_column`). Available as a Platform API service.

See the [Developer Guide](https://docs.amigo.ai/developer-guide) for conceptual documentation on both APIs.
{% endhint %}

## SDK Ecosystem

The Classic API is available through official SDKs. Platform API: Direct HTTP.

| SDK            | Package                                                        | Version    | Docs                                                       |
| -------------- | -------------------------------------------------------------- | ---------- | ---------------------------------------------------------- |
| **TypeScript** | [`@amigo-ai/sdk`](https://www.npmjs.com/package/@amigo-ai/sdk) | 1.0.0-rc.1 | [GitHub](https://github.com/amigo-ai/amigo-typescript-sdk) |
| **Python**     | [`amigo-sdk`](https://pypi.org/project/amigo-sdk/)             | 1.0.0rc1   | [GitHub](https://github.com/amigo-ai/amigo-python-sdk)     |

### SDK Features

Both SDKs provide:

* **Automatic authentication**: API key exchange for bearer tokens with proactive refresh
* **Retry with backoff**: exponential backoff with jitter, Retry-After header support
* **NDJSON streaming**: async generators for conversation create and interact endpoints
* **Type safety**: full type definitions generated from the OpenAPI spec
* **Error hierarchy**: typed error classes mapped to HTTP status codes

### Multi-Provider LLM Support

Both APIs support multiple LLM providers with per-interaction model selection. Specify the provider and model at the interaction level. This avoids single-vendor lock-in and lets you optimize for cost, latency, and capability per task.

### Ecosystem Tools

* [**Developer Guide**](https://docs.amigo.ai/developer-guide): endpoint reference, SDK guides, and integration patterns
* [**API Coherence Check**](https://github.com/amigo-ai/api-coherence-check): automated weekly drift detection between OpenAPI spec, documentation, and SDK types
* [**SDK Examples**](https://github.com/amigo-ai/amigo-examples): production-ready examples including Next.js, FastAPI webhooks, real-time voice, batch operations, and simulation CI
* [**SDK Ecosystem Changelog**](https://docs.amigo.ai/api-reference/change-logs/sdk-ecosystem): release history for TypeScript and Python SDKs, developer tooling, and documentation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.