API Spec

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

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:

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:

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 and 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:

{
  "error": "unauthorized"
}

Scope failures include the missing route or tool scope:

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

Validation failures include field-level details:

{
  "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:

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.