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

Create Project

Create a new documentation project

POST/v1/projectsTry it
Session token

Create a new documentation project in your organization.

Request Body

NameDescription
name:stringbodyRequired
Project display name. Used in the dashboard and as the default site title.
orgId:stringbody
The organization to create the project in. You must be a member of it, or the request returns 403 forbidden. When omitted, the project goes into the first organization you belong to.
slug:stringbody
URL-friendly identifier, 2–50 characters of a-z, 0-9 and -. Auto-generated from name if not provided. Used in the docs URL: {slug}-docs.syntext.dev. Check a slug first with Check Subdomain Availability.
description:stringbody
Brief project description. Shown in the dashboard.
repoUrl:stringbody
GitHub repository URL to connect. Example: https://github.com/acme/docs.
repoBranch:stringbody
Branch to build from. Defaults to main.
Default"main"
contentSource:stringbody
Where the pages live: hosted (written in Syntext), github (the repository in repoUrl) or upload (published with stx deploy). Defaults to github with a repoUrl and hosted without one. A repoUrl with any other source returns 400 validation_error. See Write and publish without GitHub.
template:stringbody

A starter for a project written in Syntext: help-center, product-guides, handbook, developer-docs or blank. List them with List Templates. Sending contentSource: "hosted" without a template uses blank. With any other source, a template returns 400 validation_error.

The template's pages are saved as revision 1 and published straight away, so the site is live at once. Sending neither contentSource nor template without a repoUrl creates an empty project written in Syntext, with no build.

isPublic:booleanbody
Marks the project as public or private. Any value other than a boolean returns 400. This is a stored flag only — it does not restrict who can read the doc site. To gate the site, use access control or audience gating.
Defaulttrue

Settings (branding, site password, AI persona) are not accepted here. Set them with Update Project once the project exists.

Response

Returns 201 with the created project object — see Get Project. When a template was used, it also has:

•
template — the template's id.
•
revision — { id, number } of the template's first revision.
•
initialBuild — { id, status } of the publish, or null when it couldn't start.
•
publishError — { code, message } when the publish couldn't start, for example USAGE_LIMIT_EXCEEDED when the plan's builds are used up. The project and its pages exist either way; publish later with Publish Content.

Error Responses

400 Bad Request

validation_error — required fields are missing or have invalid values. details.issues lists each problem — see Validation errors:

json
{
"error": {
"code": "validation_error",
"message": "isPublic: Expected boolean, received string",
"details": {
"issues": [
{ "path": ["isPublic"], "code": "invalid_type", "message": "Expected boolean, received string" }
],
"target": "json",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

400 bad_request ("No organization found. Create one first.") is returned when you omit orgId and belong to no organization.

409 Conflict

Returned when a project with this slug already exists.

json
{
"error": {
"code": "conflict",
"message": "Project slug already taken",
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

402 Payment Required

Returned when the organization already has as many projects as its plan allows. The code is USAGE_LIMIT_EXCEEDED, as for other usage limits.

json
{
"error": {
"code": "USAGE_LIMIT_EXCEEDED",
"message": "Project limit reached (1/1). Upgrade your plan to create more projects.",
"current": 1,
"limit": 1,
"details": { "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

403 Forbidden

Returned when orgId names an organization you are not a member of.

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X POST https://api.syntext.dev/v1/projects \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-H "Content-Type: application/json" \
-d '{
"name": "API Documentation",
"description": "REST API reference for our platform",
"repoUrl": "https://github.com/acme/api-docs",
"repoBranch": "main"
}'
Responseapplication/json
json
{
"data": {
"id": "b4c5d6e7-f8a9-4b0c-9d1e-2f3a4b5c6d7e",
"name": "API Documentation",
"slug": "api-documentation",
"description": "REST API reference for our platform",
"docsUrl": "https://api-documentation-docs.syntext.dev",
"repoUrl": "https://github.com/acme/api-docs",
"repoBranch": "main",
"isPublic": true,
"settings": { "hasPassword": false },
"createdAt": "2026-06-28T10:30:00Z",
"updatedAt": "2026-06-28T10:30:00Z"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext