# HTTP API

> An overview of LangAlpha's HTTP API. The base URL, JSON requests and errors, turns streamed as server-sent events, resuming a stream, and safe retries with a request key.

Source: https://docs.langalpha.ai/api/overview/

Everything the web app and the [CLI](https://docs.langalpha.ai/cli/overview/) do goes through LangAlpha's HTTP API, and you can call it from your own code. This page covers how the API behaves in general. A full endpoint reference is coming; until then, the [CLI's source](https://github.com/ginlix-ai/langalpha/tree/main/cli/src) is a compact, working example of the routes most people need.

## Base URL

Every route lives under `/api/v1` on your LangAlpha server, for example `http://localhost:8000/api/v1/threads` on a default self-hosted install.

:::note[Hosted and self-hosted]
**Hosted:** The same routes, on the hosted server. Calls need a credential; see [Authentication](https://docs.langalpha.ai/api/authentication/).

**Self-hosted:** The server also serves interactive API documentation generated from its routes at `/docs`, for example `http://localhost:8000/docs`. In the default `HOST_MODE=oss` no credential is needed.
:::

## Requests and errors

Requests and responses are JSON. An error comes back with an HTTP status and a `detail` field, which is one of:

- a sentence, such as `{"detail": "Thread not found"}`;
- an object with a `message` and a machine-readable `type` or `code`, such as `insufficient_scope`;
- for a request that does not validate (422), a list of the problems found.

| Status | Meaning |
| --- | --- |
| 400, 422 | The request is invalid. |
| 401 | No credential, or one the server refuses. |
| 403 | The credential may not do this. |
| 404 | Not found. |
| 409 | A conflict with the current state, such as answering a thread that is waiting for nothing. |
| 429 | Too many requests; the `Retry-After` header says how many seconds to wait. |
| 503 | The server cannot answer right now; retry after `Retry-After` when it is set. |

## Turns stream as server-sent events

Sending a message runs a turn, and the response is a stream of [server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html) (`text/event-stream`) that lasts as long as the turn:

- `POST /api/v1/threads/messages` starts a new thread. The body names a `workspace_id` and `messages`, a list holding one `{"role": "user", "content": "..."}`, and optionally an `llm_model`.
- `POST /api/v1/threads/{thread_id}/messages` sends to an existing thread. If a turn is running there, the message steers it.

Each event has a name, a numbered `id`, and JSON data. Among the first is `metadata`, which names the thread and the run. `message_chunk` events carry the reply as it is written, and tool calls and their results come as events of their own. The stream ends on `interrupt` when the agent waits for an answer, on `error` or `retry` when the turn fails (each says whether to retry the run or send again, in `recovery`), and on `run_end` with the run's outcome. Comment lines keep an idle connection open every 15 seconds.

## Reconnecting and reading back

Closing the connection does not stop the turn; it keeps running on the server.

- `GET /api/v1/threads/{thread_id}/messages/stream` reconnects to the thread's latest turn, or to one run with `?run_id=`. Pass the last event id you received as the `Last-Event-ID` header (or `?last_event_id=`) and the stream resumes after it, without repeating what you already have.
- `GET /api/v1/threads/{thread_id}/messages/replay` reads back a thread's turns, finished ones included, as the same kind of events.
- `POST /api/v1/threads/{thread_id}/cancel` stops the running turn.

## Safe retries with a request key

A send can carry a `request_key`, a UUID you generate for that one message. If the connection drops before you know whether the send arrived, send the same request again with the same key: the server recognizes it and connects you to the run the first copy started, rather than starting a second turn. A send without a key is never deduplicated.

## Related

- [Authentication](https://docs.langalpha.ai/api/authentication/)
- [The LangAlpha CLI](https://docs.langalpha.ai/cli/overview/)
- [Threads and turns](https://docs.langalpha.ai/concepts/threads-and-turns/)