Talyn tracks pull requests for each workspace: the pull requests you opened, the pull requests that wait for your review, and the pull requests you watch. The API reads these pull requests and acts on them.
Scopes: pull_requests:read and pull_requests:write for pull requests and the merge queue. code_reviews:read and code_reviews:write for code reviews. See authentication.
The token form in the app does not offer these scopes yet. See scopes in the token form.
curl -s "https://api.talyn.dev/v1/pull-requests?workspace_id=$WORKSPACE_ID&relationship=authored" \
-H "Authorization: Bearer $TALYN_TOKEN"The list holds open pull requests. Use state=closed, state=merged or state=all for others. The filters:
| Query | Values |
|---|---|
state |
open (default), closed, merged, all |
relationship |
authored (the "Mine" bucket), review_requested (the "Review" bucket), watching |
repository_id |
A repository id |
merge_queued |
true or false |
The list is newest first by the time Talyn started to track each pull request. It pages with a cursor. See pagination.
Each pull request has the facts that the app shows:
ci_status: the CI result alone.failing_requiredalso covers a failing check when Talyn does not know if the check is required.blocking_reason: the whole merge result, for examplemergeable,merge_conflictsorchecks_failed.human_gates: failing checks that only a person can clear, for example a visual review.review_decision,mergeableandmerge_state_status, lower-cased.merge_queue: the entry in the merge queue, ornull.
The API reads only what Talyn has stored. last_synced_at tells you when Talyn last read the pull request from GitHub. To read it from GitHub now, send a refresh:
curl -s -X POST https://api.talyn.dev/v1/pull-requests/$PR_ID/refresh \
-H "Authorization: Bearer $TALYN_TOKEN"A refresh uses your own GitHub rate limit. The API allows 30 GitHub calls each minute for each token. Refreshes, code review posts, and the session pull_request and merge actions count against this limit. See rate limits.
A refresh answers 409 cannot_refresh when GitHub does not return the pull request, or Talyn does not know its branch yet. A pull request that is no longer open gets its closed or merged state.
GET /pull-requests/{id} also gives session_ids (the sessions that work on the pull request) and code_review (a summary of the latest review). The full description is at GET /pull-requests/{id}/description.
curl -s -X PATCH https://api.talyn.dev/v1/pull-requests/$PR_ID \
-H "Authorization: Bearer $TALYN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "auto_keep_mergeable": true }'When auto-keep is on, Talyn starts a fix when the pull request gets conflicts or failing checks. Each fix counts against your plan.
POST /pull-requests/{id}/sessions starts a session on the head branch of the pull request. The session links to the pull request. This is the same as POST /sessions with pull_request_id. It needs sessions:write. A pull request that is not open answers 409 pull_request_not_open.
The body has agent (required), and optionally model, prompt, name and internet_access.
curl -s https://api.talyn.dev/v1/pull-requests/$PR_ID/sessions \
-H "Authorization: Bearer $TALYN_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "agent": "claude", "prompt": "Fix the failing checks and push." }'The merge queue merges a pull request when it is clean. It works on one pull request at a time for each repository and base branch. When a queued pull request has conflicts or failing checks, the queue starts a fix.
curl -s -X POST https://api.talyn.dev/v1/pull-requests/$PR_ID/merge-queue \
-H "Authorization: Bearer $TALYN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "method": "squash" }'method is squash, merge or rebase. If you leave it out, Talyn uses the last method for this pull request, else squash. If the pull request is in the queue already, the request changes only its method. A pull request that is not open answers 409 pull_request_not_open.
DELETE /pull-requests/{id}/merge-queueremoves the pull request. It also turns off a GitHub auto-merge that Talyn armed. A pull request that is not in the queue gets the same answer.GET /merge-queue?workspace_id=...lists the queue in the order the pull requests joined. The list has one page.positioncounts from 1 in each repository and base branch.GET /pull-requests/{id}/merge-queue/eventstells you what the queue did and why. It gives the newest 100 events at most, newest first.- A
blockedentry has ablocked_codeand ablocked_reason. POST /pull-requests/{id}/merge-queue/resubmitsends a parked entry again, after an external merge queue (trunk.io) gave it back. It answers409not_queued,not_parkedorno_external_queuewhen there is nothing to re-submit.
The API cannot merge a pull request directly. Use the merge queue.
A code review runs several AI reviewers on a pull request. The findings stay in Talyn. Nothing goes to GitHub until you post it.
A pull request has at most one review. Each new review is a new cycle of the same review. Findings carry over between cycles, and a dismissal stays dismissed.
curl -s https://api.talyn.dev/v1/pull-requests/$PR_ID/code-reviews \
-H "Authorization: Bearer $TALYN_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "preset": "standard" }'The body is optional. preset is quick, standard or deep. The default is the workspace setting. Send "reset": true to discard the findings on record. Else the findings carry over.
The answer is 201 with the review. If a cycle already runs, the answer is 200 with that cycle. Read GET /code-reviews/{id} until phase is at rest, for example ready, failed or cancelled. A review takes some minutes. Poll each 30 seconds or less often.
A review runs on a box. The plan limits on boxes apply, so the answer can be 402. See plan limits. Other refusals:
409pr_closed: the pull request is not open.409no_reviewers: the workspace turned off Talyn's reviewers and has none of its own for this repository.404pr_missing: Talyn does not track the pull request any more.
GET /pull-requests/{id}/code-reviewslists the review of a pull request, without findings. The list has one item at most.POST /code-reviews/{id}/cancelstops the reviewers of the running cycle. A review at rest gets an answer with no change.GET /code-reviews/{id}/eventslists each phase change and action, with the reason. It gives the newest 200 events at most, newest first.
GET /code-reviews/{id} gives the review and its findings, most severe first. Each finding has:
severity:blocker,major,minorornit.file_path,line_startandline_end.anchor_verified:truewhen the quoted code is at that place. Trust a finding withfalseless.lenses: the reviewers that found it. Two or more reviewers is agreement.verdictandverdict_reason: what the judging pass decided, and why.status:open,selected(a fix works on it),dismissed,fixedorstale.
The list leaves out the long text. GET /code-reviews/{id}/findings/{finding_id} gives body, suggestion and anchor.
curl -s https://api.talyn.dev/v1/code-reviews/$REVIEW_ID/findings/$FINDING_ID/dismiss \
-H "Authorization: Bearer $TALYN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "reason": "not_a_problem" }'The reasons are not_a_problem, already_handled, wont_fix_here and wrong_about_code. The reason is optional. DELETE on the same path undoes the dismissal. When you dismiss a blocker, a merge-queue entry that waits for it can continue.
curl -s https://api.talyn.dev/v1/code-reviews/$REVIEW_ID/post \
-H "Authorization: Bearer $TALYN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "finding_ids": ["..."] }'The API writes one GitHub review from your account. The review is always a comment. It never approves and never requests changes. Leave out finding_ids to post each open finding that is not on the pull request yet.
- A finding goes on a line of the diff only when its quoted code is there. The others go in the review body.
- A finding is never posted twice.
409code_review_post_not_ready: the review still runs.409code_review_post_nothing_to_post: no open finding is left.502code_review_post_github_failed: GitHub refused. The message has the answer from GitHub.
The API cannot start a fix run for findings. Start a session on the pull request and tell the agent what to fix.