Record a pull-request preview, or update the record for that pull request.
POST/v1/projects/{projectId}/previewsTry it
Session token
Record a preview deployment for a pull request — for example from your own CI. The GitHub webhooks create these records automatically, so you only need this when your previews are built elsewhere.
Note
Any workspace member, with a session JWT. API keys are not accepted. Any plan.
A project has one record per pull request. If prNumber already has a record, it is updated instead: commitSha and previewUrl are replaced, prTitle, baseBranch and the author are replaced when you send them, and status goes back to building. branch and expiresAt keep their stored values. Both cases return 201.
Path Parameters
NameDescription
projectId:stringpathRequired
The project ID (e.g., 3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).
Request Body
NameDescription
prNumber:integerbodyRequired
Pull request number.
branch:stringbodyRequired
The pull request's head branch.
commitSha:stringbodyRequired
The head commit, at least 7 characters.
previewUrl:stringbodyRequired
Where the preview is served. Must be a URL.
prTitle:stringbody
Pull request title.
baseBranch:stringbody
The branch the pull request targets, 1–255 characters.
authorLogin:stringbody
The author's GitHub login, 1–100 characters. Returned as author.login, and as author.name unless a member of the workspace has linked that GitHub account — then author.name is that member's display name.
authorAvatarUrl:stringbody
The author's avatar URL, up to 2048 characters.
expiresAt:stringbody
ISO 8601 date-time after which the preview expires.
Response
Returns 201 Created with the preview object. Its status is building.
Error Responses
Status
error.code
When
400
—
The body is invalid, e.g. a missing field or a previewUrl that is not a URL. See below
401
unauthorized
No session JWT, an invalid or expired one, or an API key
401
session_revoked
The session has been signed out
403
forbidden
You are not a member of the project's workspace
404
not_found
The project does not exist or is deleted
400 Bad Request
validation_error — the body failed validation. details.issues lists each problem: