# API overview

Start sessions, send messages and read the results from your own scripts with the Talyn REST API and a personal access token.

The Talyn API lets a script do what you do in the app: start a session, send the agent a message, follow the transcript, read the diff and open the pull request.

The base URL is:

```
https://api.talyn.dev/v1
```

The API takes and returns JSON. Request bodies can be up to 1 MB. The full OpenAPI 3.1 document is at [api.talyn.dev/v1/openapi.json](https://api.talyn.dev/v1/openapi.json), and you can fetch it without a token.

The API is not yet available to all accounts. If it is off for your account, each request returns `403` with the code `public_api_unavailable`, and **Settings** does not show **API tokens**.

## [Create a token](/content/docs/api#create-a-token/index.html)

Every request needs a personal access token. Tokens start with `talyn_pat_`.

1. In Talyn, open **Settings**.
2. Select **API tokens**.
3. Select **Create token**.
4. Type a name, for example "CI script".
5. Choose when the token expires: 30 days, 90 days (the default), 1 year, or no expiry.
6. Choose **All workspaces** or one workspace.
7. Choose the access. **Read only** and **Full access** are shortcuts. You can also set each of Workspaces, Repositories and Sessions to None, Read, or Read & write. If spaces are on for your account, the form also shows Teams and Spaces.
8. Select **Create token**.
9. Copy the token. Talyn shows it one time only.

Talyn stores only a hash of the token. If you lose it, revoke it and create a new one.

To revoke a token, select it in the same list and confirm **Revoke token**. Anything that uses the token stops working at once.

## [Authenticate](/content/docs/api#authenticate/index.html)

Send the token in the `Authorization` header:

```
curl https://api.talyn.dev/v1/me \
  -H "Authorization: Bearer $TALYN_TOKEN"
```

`GET /me` returns the token's scopes, its workspace, its expiry and the account it acts for. Use it to check a new token.

Only `talyn_pat_` tokens work on the API. Your app sign-in and your [MCP token](/content/docs/mcp/index.html) do not.

The API sends no CORS headers, so a web page in a browser cannot call it. Call it from a server, a script or a CI job.

## [Scopes](/content/docs/api#scopes/index.html)

Each endpoint needs one scope. A write scope includes its read scope. The [endpoint reference](/content/docs/api-reference/index.html) names the scope of each endpoint.

The access you choose in the token form gives these scopes:

| Access | Scope | Allows |
| --- | --- | --- |
| Workspaces: Read | `workspaces:read` | Read workspaces. |
| Teams: Read | `teams:read` | Read the teams you are in. |
| Spaces: Read | `spaces:read` | Read team spaces and their sessions. |
| Spaces: Read & write | `spaces:write` | Start sessions in team spaces. |
| Repositories: Read | `repositories:read` | Read repositories, their settings, instructions and setup. |
| Repositories: Read & write | `repositories:write` | Change repository settings, instructions and setup. |
| Sessions: Read | `sessions:read` | Read sessions, chats and transcripts, and open the streams. |
| Sessions: Read & write | `sessions:write` | Start sessions and send messages, run scripts, open and merge pull requests. |

The form shows Teams and Spaces only when spaces are on for your account. Spaces are not yet available to all accounts. If spaces are off for your account, the team and space endpoints return `403` with the code `spaces_unavailable`.

**Read only** gives read access to workspaces, repositories and sessions. **Full access** gives read access to workspaces and repositories, and read and write access to sessions. When the form shows Teams and Spaces, **Read only** also gives read access to teams and spaces. **Full access** also gives read access to teams and read and write access to spaces.

The API also has these scopes. The token form does not offer them yet, so a token from the app cannot call these endpoints:

| Scope | Allows |
| --- | --- |
| `pull_requests:read` | Read pull requests and the merge queue. |
| `pull_requests:write` | Refresh pull requests, change auto keep mergeable, and add to or remove from the merge queue. |
| `code_reviews:read` | Read code reviews and their findings. |
| `code_reviews:write` | Start and stop code reviews, dismiss findings and post them to GitHub. |
| `memory:read` | Read workspace memory. |
| `memory:write` | Save, change and forget workspace memory. |
| `webhooks:read` | Read webhook endpoints and their deliveries. |
| `webhooks:write` | Create, change, test and delete webhook endpoints, and send deliveries again. |

A token bound to one workspace can only see that workspace. A request for anything outside it gets `404`.

## [A first session](/content/docs/api#a-first-session/index.html)

These steps start a session, follow the agent as it works, and open the pull request.

1. Find your repository's id:

```
curl "https://api.talyn.dev/v1/repositories?workspace_id=$WORKSPACE_ID" \
     -H "Authorization: Bearer $TALYN_TOKEN"
```

2. Start a session with a prompt. `agent` is `claude` or `codex`:

```
curl https://api.talyn.dev/v1/sessions \
     -H "Authorization: Bearer $TALYN_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "workspace_id": "'
