/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
API Reference Create Preview

Create Preview

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

Statuserror.codeWhen
400—The body is invalid, e.g. a missing field or a previewUrl that is not a URL. See below
401unauthorizedNo session JWT, an invalid or expired one, or an API key
401session_revokedThe session has been signed out
403forbiddenYou are not a member of the project's workspace
404not_foundThe project does not exist or is deleted

400 Bad Request

validation_error — the body failed validation. details.issues lists each problem:

json
{
"error": {
"code": "validation_error",
"message": "authorAvatarUrl: Invalid url",
"details": {
"issues": [
{ "path": ["authorAvatarUrl"], "code": "invalid_string", "message": "Invalid url" }
],
"target": "json",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}
Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/previews \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-H "Content-Type: application/json" \
-d '{
"prNumber": 42,
"prTitle": "Document the new endpoints",
"branch": "feature/new-endpoints",
"baseBranch": "main",
"commitSha": "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5",
"previewUrl": "https://feature-new-endpoints--api-docs.syntext.dev",
"authorLogin": "ada",
"authorAvatarUrl": "https://avatars.githubusercontent.com/u/1234567"
}'
Responseapplication/json
201Created
{
"data": {
"id": "prv_abc123",
"projectId": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c",
"prNumber": 42,
"prTitle": "Document the new endpoints",
"branch": "feature/new-endpoints",
"baseBranch": "main",
"commitSha": "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5",
"previewUrl": "https://feature-new-endpoints--api-docs.syntext.dev",
"status": "building",
"author": {
"name": "ada",
"login": "ada",
"avatarUrl": "https://avatars.githubusercontent.com/u/1234567"
},
"expiresAt": null,
"createdAt": "2026-11-07T15:30:00Z",
"updatedAt": "2026-11-07T15:30:00Z"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext