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

Preview GitHub Link

See what linking a project written in Syntext to a GitHub repository would do, before anything is written.

POST/v1/projects/{projectId}/source/github/previewTry it
Session token

Compare the project's pages in Syntext with a repository's, and see which connect strategies are possible. Nothing is written — this is the dashboard's Connect GitHub › Preview step.

Note

Requires the admin or owner role and a session JWT. The Syntext GitHub App must be installed on the repository for the project's workspace.

Request Body

NameDescription
repoUrl:stringbodyRequired
The repository, e.g. https://github.com/acme/docs.
branch:stringbody
The branch. Defaults to the repository's default branch.
docsPath:stringbody
The docs folder in the repository. Omit it to use docs/, or the folder the repository already keeps pages in. / is the repository root. Builds read pages from docs/ or the root, so a move that writes pages needs one of those.
installationId:integerbody
The GitHub App installation to use. Omit it and Syntext finds one of the workspace's installations that can see the repository.

Response — 200 OK

NameDescription
repoState:string
empty — no pages in the docs folder (or an empty repository). has_docs — the folder already has pages.
sameFiles:integer
Files identical in both.
differing:object[]
Up to 200 files that differ, each changed, only_in_syntext or only_in_repo. differingTotal counts them all.
strategies:object
For each of push, pull_request and use_repo, whether Connect would accept it, and if not, reason — the error code and message connect would return.
skipped:object[]
Up to 50 repository files that are in the docs folder but can't come into Syntext, with the reason. Files that aren't pages, config or images are left out without being listed.

Error Responses

The same as Connect GitHub, except the strategy errors, which are reported in strategies instead.

Was this page helpful? Yes No
Request
bashJavaScriptPythonGoRubyPHPJavaC#bash
curl -X POST https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/preview \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{ "repoUrl": "https://github.com/acme/docs" }'
Responseapplication/json
200OK
{
"data": {
"repoUrl": "https://github.com/acme/docs",
"repoState": "has_docs",
"repoPages": 12,
"syntextPages": 14,
"sameFiles": 9,
"differing": [
{ "path": "guides/quickstart.mdx", "status": "changed", "syntextSha": "c2a8e4…", "repoSha": "3f1c9a…" },
{ "path": "guides/webhooks.mdx", "status": "only_in_syntext", "syntextSha": "7b3d5f…" }
],
"differingTotal": 6,
"branch": "main",
"defaultBranch": "main",
"docsPath": "docs",
"installationId": 51234567,
"strategies": {
"push": { "allowed": false, "reason": { "code": "repo_has_docs", "message": "The repository already has pages under docs. Open a pull request instead, or use the repository's pages." } },
"pull_request": { "allowed": true },
"use_repo": { "allowed": true }
},
"skipped": [{ "repoPath": "docs/public/logo.png", "reason": "public/ is reserved: store images at the path they are served from (images/logo.png is served at /images/logo.png)." }]
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext