# API Integration Guide

How to integrate with ows-coda from another service or tool.

## Integration options

| Method         | Best for                             | Protocol                 | Auth                       |
| -------------- | ------------------------------------ | ------------------------ | -------------------------- |
| **REST API**   | Web clients, custom integrations     | HTTP/1.1 + SSE           | Bearer token (Auth0 JWT)   |
| **MCP Server** | Claude Code, Claude Desktop, Cursor  | stdio JSON-RPC           | Bearer token (forwarded)   |
| **ConnectRPC** | Internal services (search, platform) | HTTP/1.1 + protobuf/JSON | Internal VPC (no auth yet) |

---

## REST API quickstart

### Authentication

All `/api/v1/` endpoints require `Authorization: Bearer <token>`. Tokens are Auth0 JWTs validated against the ows-grass JWKS endpoint. Obtain a token by authenticating through the web UI and copying it from browser devtools (Network tab → any API request → `Authorization` header).

### Key endpoints

| Endpoint                     | Method | Purpose                                         |
| ---------------------------- | ------ | ----------------------------------------------- |
| `/api/v1/chats`              | GET    | List conversations (cursor-paginated)           |
| `/api/v1/chats`              | POST   | Create a new conversation                       |
| `/api/v1/chats/:id/stream`   | POST   | Send a query and receive streaming SSE response |
| `/api/v1/chats/:id/messages` | GET    | Retrieve message history (cursor-paginated)     |
| `/api/v1/models`             | GET    | List available AI models                        |
| `/api/v1/tools/execute`      | POST   | Execute a single tool by name                   |
| `/api/v1/me/permissions`     | GET    | Get the user's effective permission set         |
| `/health`                    | GET    | Liveness probe (no auth)                        |
| `/health/ready`              | GET    | Readiness probe (no auth)                       |

See the full [API Reference](../api/server.md) for request/response schemas, SSE event types, and pagination.

### Streaming response

The `/api/v1/chats/:id/stream` endpoint returns Server-Sent Events. Key event types:

- `chunk` — streamed text token (the AI's answer)
- `progress` — tool execution progress (what the agent is doing)
- `sources` — entity deep-links cited in the response
- `done` — stream complete with final message IDs
- `error` — fatal error

### Rate limits

| Scope       | Limit       | Applies to                      |
| ----------- | ----------- | ------------------------------- |
| General API | 100 req/min | All `/api/` routes              |
| Streaming   | 10 req/min  | `POST /api/v1/chats/:id/stream` |

Both limits are per user, enforced via Redis sliding window. Responses include standard `RateLimit-*` headers.

### Error handling

| Status | Meaning                  | Action                                        |
| ------ | ------------------------ | --------------------------------------------- |
| 400    | Invalid request          | Check request body against the API schema     |
| 401    | Token expired or invalid | Re-authenticate and retry                     |
| 403    | Permission denied        | Check user's effective permissions            |
| 404    | Resource not found       | Verify the conversation/resource ID           |
| 429    | Rate limit exceeded      | Respect `Retry-After` header                  |
| 500    | Internal error           | Report to `#abacus-devs` with the `requestId` |

All error responses include a JSON body with `{ error, message }`.

---

## MCP Server integration

The MCP server exposes Coda's tools to AI coding assistants (Claude Code, Claude Desktop, Cursor) via the stdio transport.

### Quick setup

```bash
# Automatic — writes .mcp.json for your client
pnpm mcp:setup              # Claude Code
pnpm mcp:setup --desktop    # Claude Desktop
pnpm mcp:setup --cursor     # Cursor
```

### What's available via MCP

- **37+ tools** across account, royalties, revenue, product, ledger, file generation, GraphQL, and adjustment domains
- **4 prompt templates** for common workflows (search account, revenue overview, explore GraphQL, create adjustment)
- **3 resources** for introspection (tool catalog, domain guide, server metrics)

### What's NOT available via MCP

Snowflake, Notion, and Runner tools are excluded — they require per-request infrastructure (identity-scoped connection pools, OAuth tokens) that the MCP transport doesn't support.

See the full [MCP Server guide](mcp-server.md) for environment variables, troubleshooting, and end-to-end traces.

---

## Tool execution API

For programmatic access to individual tools without the full chat loop, use `POST /api/v1/tools/execute`:

```bash
curl -X POST http://localhost:8080/api/v1/tools/execute \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "search_accounts", "input": {"search_term": "Sony Music"}}'
```

Response:

```json
{
  "data": { "accounts": [{ "id": 123, "name": "Sony Music Entertainment" }] },
  "error": null
}
```

See the [Tool Catalog](../api/tool-catalog.md) for all available tools, their parameters, and which infrastructure they require.

---

## ConnectRPC (internal services)

Internal services communicate via ConnectRPC with protobuf-defined contracts:

| Service  | Package            | Port | Purpose                                |
| -------- | ------------------ | ---- | -------------------------------------- |
| Search   | `@coda/search-api` | 8081 | Schema search (BM25 + HNSW + glossary) |
| Platform | `@coda/admin-api`  | 8082 | Auth, permissions, tenancy, audit      |
| Runner   | `@coda/runner-api` | 8083 | Datasource execution                   |

Proto definitions live in `packages/<name>-api/proto/`. Clients are generated via `buf generate` and committed. See the [Proto Codegen guide](proto-codegen.md) for regeneration.

---

## See also

- [API Reference](../api/server.md) — full endpoint documentation
- [Platform RPC API](../api/platform.md) — ConnectRPC service definitions
- [Tool Catalog](../api/tool-catalog.md) — all tools with parameters
- [MCP Server guide](mcp-server.md) — MCP setup and troubleshooting