API overview · Talyn docs
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, 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
Every request needs a personal access token. Tokens start with talyn_pat_.
- In Talyn, open Settings.
- Select API tokens.
- Select Create token.
- Type a name, for example "CI script".
- Choose when the token expires: 30 days, 90 days (the default), 1 year, or no expiry.
- Choose All workspaces or one workspace.
- 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.
- Select Create token.
- 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
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 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
Each endpoint needs one scope. A write scope includes its read scope. The endpoint reference 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
These steps start a session, follow the agent as it works, and open the pull request.
- Find your repository's id:
curl "https://api.talyn.dev/v1/repositories?workspace_id=$WORKSPACE_ID" \
-H "Authorization: Bearer $TALYN_TOKEN"
- Start a session with a prompt.
agentisclaudeorcodex:
curl https://api.talyn.dev/v1/sessions \
-H "Authorization: Bearer $TALYN_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"workspace_id": "'