Update settings and configuration for an existing project.
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
projectId3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c).Request Body
All fields are optional. Only provided fields will be updated.
namedescriptionrepoUrlGitHub 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.
repoBranchrepoPath/.githubInstallationId403 installation_not_owned.isPublic400. 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.settingsPartial 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: {}.
settings.logo{ light?, dark? } — image URLs, up to 2048 characters each.settings.colors{ primary?, accent?, background? } — CSS colour strings, up to 64 characters each.settings.navigation{ tabs? } — up to 50 tab labels.settings.faviconsettings.passwordEnabledsettings.passwordsettings.passwordHash is accepted as a legacy alias for the same plaintext value — it is hashed too, never stored as given.settings.aiPersona{ name?, tone?, customInstructions?, bannedTopics?, fallbackMessage?, welcomeMessage?, suggestedQuestions?, memory?, sharing? }. tone is one of professional, friendly, technical, casual. memory is on (the default when unset) or off: with off, the assistant keeps no memory about visitors — nothing is extracted or used, and visitors don't get memory controls. sharing is on (the default when unset) or off: with off, readers can't share conversations and links already shared stop working until you turn it back on. Because aiPersona is replaced as a whole, send memory and sharing along with the other persona keys you want to keep.settings.support{ email?, webhook? } — where agent mode's Send to support goes. email is an email address (up to 254 characters) or null; it's only used when it belongs to a verified member of your organization, and any other address is ignored. webhook: true also sends the support.handoff webhook. With neither usable, readers aren't offered Send to support. support is replaced as a whole, so send both keys.settings.agent{ gatedDetection?, gatedDetectionShowAudiences?, runRequests? }, all booleans, all false when unset. gatedDetection turns on agent mode's gated pages notice, and gatedDetectionShowAudiences lets it name up to three audiences. runRequests lets the assistant prepare API requests readers run with their own key. They take effect immediately, without a rebuild. agent is replaced as a whole, so send all three keys.settings.aiRateLimit{ maxPerMinute?, maxPerHour? } — per-visitor limits for the AI assistant.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:
403 Forbidden
Returned when you are a member of the workspace but not an admin or owner:
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:
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.