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_.

  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

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.

  1. Find your repository's id:
curl "https://api.talyn.dev/v1/repositories?workspace_id=$WORKSPACE_ID" \
     -H "Authorization: Bearer $TALYN_TOKEN"
  1. 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": "'