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

Update Project

Update an existing project

PATCH/v1/projects/{projectId}Try it
Session token

Update settings and configuration for an existing project.

Note

Requires the admin or owner role and a session JWT. A member of the workspace gets 403 forbidden with details.requiredRole: "admin" — see Role errors.

Path Parameters

NameDescription
projectId:stringpathRequired
The project ID (e.g., 3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).

Request Body

All fields are optional. Only provided fields will be updated.

NameDescription
name:stringbody
Project display name, 2–100 characters.
description:stringbody
Project description, up to 500 characters.
repoUrl:string | nullbody

GitHub repository URL. Changing it removes the push webhook from the previous repository and creates one on the new repository. Set it to null to disconnect the repository, which also removes the webhook. If the old webhook can't be removed, the response carries a warning.

Setting it also sets contentSource: a repository makes the project build from GitHub, and null on a GitHub project makes it a project written in Syntext. A project written in Syntext that already has pages refuses a repository here with 409 use_connect_flow — use Connect GitHub so the pages move with it. To disconnect and keep the repository's pages, use Disconnect GitHub instead of null.

repoBranch:stringbody
Branch to build from.
repoPath:stringbody
Docs directory inside the repository. Default /.
githubInstallationId:integer | nullbody
The GitHub App installation to read and commit through. It must be an installation your workspace is connected to, or one you can access on GitHub yourself. In the second case, setting it connects the installation to the workspace. Anything else returns 403 installation_not_owned.
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.
settings:objectbody

Partial settings update, merged into the stored settings. Only the keys below can be written. Any other key — at the top level (sso, openapi, hasPassword, …) or inside a nested object (aiPersona.systemPrompt, colors.hover, …) — is dropped, never stored, and listed in an ignored_settings_keys warning; the rest of the update still succeeds. This means you can send back the whole settings object you read from Get Project. Values of the keys below are still validated, and an invalid one (for example aiPersona.tone: "rude") fails the whole request with 400. Settings that have their own endpoints (SSO, OpenAPI/AsyncAPI/GraphQL/gRPC sources) are configured there instead.

The merge is one level deep: a nested object you send (colors, aiPersona, …) replaces the stored object of that name as a whole, so send every sub-key you want to keep. That includes an object whose only keys were dropped — { "aiPersona": { "systemPrompt": "…" } } stores aiPersona: {}.

Show 10 child attributesobject

Response

Returns the updated project object. Secrets never appear in settings: the site password is reported as settings.hasPassword (boolean), and the SSO client secret as settings.sso.hasClientSecret.

Warnings

A successful update can carry a top-level warnings array. Each entry has a code and a message. warnings is omitted when there is nothing to report. There are two codes, and when both apply, ignored_settings_keys comes first.

ignored_settings_keys

Returned when settings contained keys that can't be written through this endpoint. Those keys were dropped; everything else in the request was applied. keys lists each dropped key by its dotted path:

webhook_teardown_pending

The update succeeds even if the webhook on a repository you moved away from can't be removed. This happens when your account has no GitHub connection, or GitHub returns an error. The leftover webhook is recorded and retried on later updates, and the response adds a top-level warnings array:

details.reason is no_github_token or github_error.

Error Responses

400 Bad Request

Returned when a field value is invalid — including the value of a writable settings key, or a non-boolean isPublic. Unknown settings keys do not cause a 400; they are dropped with a warning. The code is validation_error, and details.issues lists each problem — see Validation errors:

json
{
"error": {
"code": "validation_error",
"message": "settings.aiPersona.tone: Invalid enum value. Expected 'professional' | 'friendly' | 'technical' | 'casual', received 'rude'",
"details": {
"issues": [
{ "path": ["settings", "aiPersona", "tone"], "code": "invalid_enum_value", "message": "Invalid enum value. Expected 'professional' | 'friendly' | 'technical' | 'casual', received 'rude'" }
],
"target": "json",
"traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10"
}
}
}

403 Forbidden

Returned when you are a member of the workspace but not an admin or owner:

json
{
"error": {
"code": "forbidden",
"message": "Only workspace admins can change project settings.",
"details": { "requiredRole": "admin", "currentRole": "member", "traceId": "6f1c2a9e-3b7d-4c11-9a0e-2d5f8b4c7e10" }
}
}

403 forbidden without role details means you are not a member of the organization that owns the project. 403 installation_not_owned means the githubInstallationId you sent is not connected to this workspace and you can't access it on GitHub.

404 Not Found

Returned when the project does not exist or has been deleted.

409 Conflict

use_connect_flow — you set repoUrl on a project written in Syntext that has pages. A bare PATCH would leave those pages behind, unpublished, so nothing is written. details links the two endpoints that move them:

json
{
"error": {
"code": "use_connect_flow",
"message": "This project has pages written in Syntext. Link the repository with the connect flow so they move with it (push them, open a pull request, or keep the repository's pages).",
"details": {
"preview": "/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/preview",
"connect": "/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c/source/github/connect"
}
}
}

A project written in Syntext with no pages yet, a project published with stx deploy, and moving a GitHub project to another repository still use PATCH.

Was this page helpful? Yes No
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X PATCH https://api.syntext.dev/v1/projects/3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated API Docs",
"settings": {
"colors": { "primary": "#4f46e5" }
}
}'
Responseapplication/json
json
{
"data": { "id": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c", "settings": { "colors": { "primary": "#4f46e5" } } },
"warnings": [
{
"code": "ignored_settings_keys",
"message": "These settings keys cannot be changed through this endpoint and were ignored.",
"keys": ["sso", "hasPassword", "aiPersona.systemPrompt"]
}
]
}
Responseapplication/json
json
{
"data": { "id": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c", "repoUrl": null },
"warnings": [
{
"code": "webhook_teardown_pending",
"message": "The GitHub webhook on the previous repository could not be removed because your account has no GitHub connection. It has been recorded and will be retried; connect GitHub or remove it in the repository settings.",
"details": {
"repoUrl": "https://github.com/acme/old-docs",
"webhookId": 123456789,
"reason": "no_github_token"
}
}
]
}
Responseapplication/json
json
{
"data": {
"id": "3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c",
"name": "Updated API Docs",
"slug": "api-docs",
"description": "Documentation for our REST API",
"docsUrl": "https://api-docs-docs.syntext.dev",
"isPublic": true,
"settings": {
"colors": { "primary": "#4f46e5" },
"passwordEnabled": false,
"hasPassword": false
},
"createdAt": "2026-01-15T12:00:00Z",
"updatedAt": "2026-06-28T11:00:00Z"
}
}
Product
Resources
Company
© 2026 SyntextBuilt with Syntext