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.
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
repoUrlThe repository, e.g.
https://github.com/acme/docs.branchThe branch. Defaults to the repository's default branch.
docsPathThe 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.installationIdThe 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
repoStateempty — no pages in the docs folder (or an empty repository). has_docs — the folder already has pages.sameFilesFiles identical in both.
differingUp to 200 files that differ, each
changed, only_in_syntext or only_in_repo. differingTotal counts them all.strategiesFor 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.skippedUp 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
Previous
Next
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" }'
const response = await fetch('https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/preview', {
method: 'POST',
headers: {
'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIs...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"repoUrl": "https://github.com/acme/docs"
}),
});
const data = await response.json();
console.log(response.status, data);
import requests
url = "https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/preview"
headers = {
"Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
}
payload = {
"repoUrl": "https://github.com/acme/docs",
}
response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
payload := []byte(`{
"repoUrl": "https://github.com/acme/docs"
}`)
req, err := http.NewRequest("POST", "https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/preview", bytes.NewReader(payload))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer eyJhbGciOiJIUzI1NiIs...")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, err := io.ReadAll(res.Body)
if err != nil {
panic(err)
}
fmt.Println(res.Status)
fmt.Println(string(body))
}
require "json"
require "net/http"
require "uri"
uri = URI("https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/preview")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer eyJhbGciOiJIUzI1NiIs..."
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"repoUrl" => "https://github.com/acme/docs",
})
response = http.request(request)
puts response.code
puts response.body
<?php
$payload = [
'repoUrl' => 'https://github.com/acme/docs',
];
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/preview',
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
echo $status, PHP_EOL, $response, PHP_EOL;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String payload = """
{
"repoUrl": "https://github.com/acme/docs"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/preview"))
.header("Authorization", "Bearer eyJhbGciOiJIUzI1NiIs...")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
using System.Net.Http;
using System.Text;
using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/preview");
request.Headers.TryAddWithoutValidation("Authorization", "Bearer eyJhbGciOiJIUzI1NiIs...");
request.Content = new StringContent(
"""
{
"repoUrl": "https://github.com/acme/docs"
}
""",
Encoding.UTF8,
"application/json");
using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
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)." }]
}
}