The Pull Requests API provides comprehensive endpoints for managing pull requests, reviews, comments, and code suggestions.
Overview
All pull request endpoints are available through the tRPC API at /trpc/pulls.*.
List Pull Requests
List pull requests for a repository.
// GET /trpc/pulls.list
{
repoId: string; // UUID of the repository
state?: 'open' | 'closed' | 'merged';
authorId?: string; // Filter by author UUID
limit?: number; // 1-100, default 20
offset?: number; // Default 0
}
Response
Array<{
id: string;
number: number;
title: string;
body?: string;
state: 'open' | 'closed' | 'merged';
sourceBranch: string;
targetBranch: string;
headSha: string;
baseSha: string;
authorId: string;
author: { id: string; username: string; name?: string } | null;
labels: Array<{ id: string; name: string; color: string }>;
isDraft: boolean;
createdAt: string;
updatedAt: string;
mergedAt?: string;
closedAt?: string;
}>
Get Pull Request
Get a single pull request by repository and number.
// GET /trpc/pulls.get
{
repoId: string;
number: number;
}
Response
Includes full PR details plus stack information if part of a stacked diff:
{
...pr,
author: User | null;
labels: Label[];
stack?: {
id: string;
name: string;
baseBranch: string;
branches: Array<{
branchName: string;
position: number;
pr: { id: string; number: number; title: string; state: string } | null;
isCurrent: boolean;
}>;
};
}
Create Pull Request
Create a new pull request.
// POST /trpc/pulls.create
{
repoId: string;
title: string; // 1-256 characters
body?: string;
sourceBranch: string;
targetBranch: string;
headSha: string;
baseSha: string;
isDraft?: boolean; // Default false
sourceRepoId?: string; // For cross-repo PRs (forks)
}
Creating a non-draft PR automatically triggers an async AI review.
Update Pull Request
Update PR title, body, or draft status.
// POST /trpc/pulls.update
{
prId: string;
title?: string;
body?: string;
isDraft?: boolean;
}
Check Mergeability
Check if a PR can be merged without conflicts.
// GET /trpc/pulls.checkMergeability
{
prId: string;
}
Response
{
canMerge: boolean;
conflicts: string[]; // List of conflicting file paths
behindBy: number; // Commits behind target
aheadBy: number; // Commits ahead of target
error?: string;
}
Merge Pull Request
Merge a pull request using the specified strategy.
// POST /trpc/pulls.merge
{
prId: string;
strategy?: 'merge' | 'squash' | 'rebase'; // Default: merge
message?: string; // Custom merge commit message
}
Response
{
...mergedPr,
mergeSha: string; // SHA of the merge commit
}
Close / Reopen
// POST /trpc/pulls.close
{ prId: string }
// POST /trpc/pulls.reopen
{ prId: string }
Reviews
Add Review
Submit a review on a pull request.
// POST /trpc/pulls.addReview
{
prId: string;
state: 'approved' | 'changes_requested' | 'commented';
body?: string;
commitSha: string; // SHA being reviewed
}
List Reviews
// GET /trpc/pulls.reviews
{ prId: string }
Add a comment to a pull request. Supports inline file comments.
// POST /trpc/pulls.addComment
{
prId: string;
body: string;
path?: string; // File path for inline comments
line?: number; // Line number
side?: 'LEFT' | 'RIGHT';
startLine?: number; // For multi-line selection
endLine?: number;
commitSha?: string;
reviewId?: string;
replyToId?: string; // For threaded replies
}
// GET /trpc/pulls.comments
{ prId: string }
// GET /trpc/pulls.getFileComments
{
prId: string;
path: string;
}
// POST /trpc/pulls.updateComment
{ commentId: string; body: string }
// POST /trpc/pulls.deleteComment
{ commentId: string }
// POST /trpc/pulls.resolveComment
{ commentId: string }
// POST /trpc/pulls.unresolveComment
{ commentId: string }
Code Suggestions
Add Suggestion
Add a comment with a code suggestion that can be applied directly.
// POST /trpc/pulls.addSuggestion
{
prId: string;
body: string; // Comment explaining the suggestion
suggestion: string; // The suggested code
path: string;
line: number;
side?: 'LEFT' | 'RIGHT';
startLine?: number;
endLine?: number;
commitSha?: string;
reviewId?: string;
}
Apply Suggestion
Apply a code suggestion, creating a commit with the change.
// POST /trpc/pulls.applySuggestion
{ commentId: string }
Response
{
success: boolean;
commitSha: string;
message: string;
}
Labels
Get Labels
// GET /trpc/pulls.labels
{ prId: string }
Add / Remove Label
// POST /trpc/pulls.addLabel
{ prId: string; labelId: string }
// POST /trpc/pulls.removeLabel
{ prId: string; labelId: string }
Reviewer Management
Request Review
Request a review from a user.
// POST /trpc/pulls.requestReview
{
prId: string;
reviewerId: string;
}
Remove Review Request
// POST /trpc/pulls.removeReviewRequest
{
prId: string;
reviewerId: string;
}
List Reviewers
// GET /trpc/pulls.reviewers
{ prId: string }
Inbox Endpoints
Get Inbox Summary
Get counts for each inbox section.
// GET /trpc/pulls.inboxSummary
{ repoId?: string }
Response
{
awaitingReview: number;
myPrs: number;
participated: number;
}
PRs Awaiting Review
Get PRs where you’ve been requested as a reviewer.
// GET /trpc/pulls.inboxAwaitingReview
{
limit?: number;
offset?: number;
repoId?: string;
}
My Open PRs
Get your own open PRs awaiting reviews from others.
// GET /trpc/pulls.inboxMyPrs
{
limit?: number;
offset?: number;
repoId?: string;
}
Participated PRs
Get PRs you’ve commented on or reviewed.
// GET /trpc/pulls.inboxParticipated
{
limit?: number;
offset?: number;
state?: 'open' | 'closed' | 'all';
repoId?: string;
}
Diff & Commits
Get PR Diff
Get parsed file changes with hunks.
// GET /trpc/pulls.getDiff
{ prId: string }
Response
{
files: Array<{
oldPath: string;
newPath: string;
status: 'added' | 'deleted' | 'modified' | 'renamed';
additions: number;
deletions: number;
hunks: Array<{
oldStart: number;
oldLines: number;
newStart: number;
newLines: number;
lines: Array<{
type: 'context' | 'add' | 'delete';
content: string;
}>;
}>;
}>;
totalAdditions: number;
totalDeletions: number;
totalFiles: number;
}
Get PR Commits
Get commits included in the pull request.
// GET /trpc/pulls.getCommits
{ prId: string }
Response
{
commits: Array<{
sha: string;
message: string;
author: string;
authorEmail: string;
date: string;
}>;
totalCommits: number;
}
AI Review
Get AI Review
Get the most recent AI-generated review.
// GET /trpc/pulls.getAIReview
{ prId: string }
Response
{
id: string;
type: 'review' | 'comment';
body: string;
state?: 'approved' | 'changes_requested' | 'commented';
createdAt: string;
} | null
Trigger AI Review
Manually trigger an AI review (useful for drafts or re-reviews).
// POST /trpc/pulls.triggerAIReview
{ prId: string }
Conflicts
Get Conflict Details
Get detailed conflict information for a PR.
// GET /trpc/pulls.getConflicts
{ prId: string }
Response
{
hasConflicts: boolean;
files: Array<{
path: string;
ours: string; // Your version
theirs: string; // Their version
base: string; // Common ancestor
}>;
}
Usage Examples
TypeScript Client
import { createTRPCClient } from '@trpc/client';
import type { AppRouter } from './api';
const client = createTRPCClient<AppRouter>({
url: 'http://localhost:3000/trpc',
});
// List open PRs
const prs = await client.pulls.list.query({
repoId: 'repo-uuid',
state: 'open',
});
// Create a PR
const newPr = await client.pulls.create.mutate({
repoId: 'repo-uuid',
title: 'Add new feature',
body: 'This PR adds...',
sourceBranch: 'feature/new-feature',
targetBranch: 'main',
headSha: 'abc123...',
baseSha: 'def456...',
});
// Add a review
await client.pulls.addReview.mutate({
prId: newPr.id,
state: 'approved',
body: 'LGTM!',
commitSha: 'abc123...',
});
// Merge the PR
const merged = await client.pulls.merge.mutate({
prId: newPr.id,
strategy: 'squash',
});
