# API Spec

Canonical URL: https://texttree.ai/docs/api-spec/
Markdown URL: https://texttree.ai/docs/api-spec.md

## Summary

Machine-readable OpenAPI and client-facing REST API contract for TextTree.

## GEO role

Supports client integration, code generation, and API contract review.

## Documentation content

# API Spec

TextTree publishes a static OpenAPI 3.1 contract for the current REST API:

- [OpenAPI JSON](/openapi.json)
- Production server: `https://api.texttree.ai`
- Local Phoenix server: `http://localhost:4001`

The spec is based on the Phoenix route map and the MCP protocol registry. It is
intended for client review, code generation, and integration planning.

## Authentication

Authenticated REST API and MCP requests require a TextTree-issued bearer access
token:

```http
Authorization: Bearer $TEXTREE_ACCESS_TOKEN
```

Current bearer access tokens start with `txt_...` and carry scopes such as
`messages:write`, `campaigns:read`, `campaigns:write`, `numbers:read`,
`numbers:write`, `onboarding:read`, `onboarding:write`, `mcp:read`, and
`mcp:execute`.

Legacy `txk_...` API keys are retained as internal records for historical
workflows. They are not accepted by `/api/v1/messages`, `/api/v1/numbers`,
`/api/v1/campaigns`, `/mcp`, or `/mcp/tools`.

## Legacy key migration

If a client still has a legacy `txk_...` key, exchange it once for a current
`txt_...` bearer token:

```bash
curl https://api.texttree.ai/api/v1/auth/migrate-legacy-key \
  -H "Authorization: Bearer $TEXTREE_LEGACY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production bearer token"}'
```

On success, TextTree returns the new bearer token once and revokes the legacy
key. If token creation fails, the legacy key is not revoked.

## Current REST surfaces

The OpenAPI file covers:

- public health checks
- headless account bootstrap
- outbound message queueing and status lookup
- campaign, snippet, and contact-list routes
- number list and provisioning routes
- programmatic onboarding and funding routes
- MCP OAuth client management routes
- OAuth registration, token exchange, and revocation
- webhook receiver endpoints for Dial and Peer
- native MCP JSON-RPC transport and legacy REST MCP tool routes

For native MCP method details, use the [OpenAI MCP compatibility](/docs/openai-mcp/)
and [MCP](/docs/mcp/) docs. OpenAPI documents the HTTP transport endpoints;
the MCP tool descriptors and schemas live in the MCP docs because they are
returned through JSON-RPC `tools/list`.

## Error envelopes

Most API failures return a JSON object with an `error` string:

```json
{
  "error": "unauthorized"
}
```

Scope failures include the missing route or tool scope:

```json
{
  "error": "insufficient_scope",
  "required_scope": "messages:write"
}
```

Validation failures include field-level details:

```json
{
  "error": "validation_failed",
  "details": {
    "phone_number": ["should be at least 7 character(s)"]
  }
}
```

## Idempotency

`POST /api/v1/messages` accepts an optional `idempotency_key`. Reusing the same
key with the same recipient, body, and cost returns the existing message with
`"replayed": true`. Reusing the same key with a different payload returns
`409 idempotency_conflict`.

## Verification

The public live checks for this contract are:

```bash
curl https://api.texttree.ai/health
curl https://api.texttree.ai/api/v1/health
curl https://api.texttree.ai/mcp/health
curl https://api.texttree.ai/.well-known/oauth-protected-resource/mcp
curl https://api.texttree.ai/.well-known/oauth-authorization-server/mcp
```

Authenticated endpoint behavior is covered by the Phoenix controller and MCP
tests because this repository does not use customer or production bearer tokens
for documentation verification.