API Reference Update Custom Code Switches
Update Custom Code Switches
Turn CSS, head tags and scripts from your docs (_syntext/) on or off.
Session token
Changes the three switches at the top of Integrations › Custom code, which decide what your live site applies from the _syntext/ folder in your docs. Every change is recorded in the audit log.
Nothing is rebuilt: a change applies on your next publish. Previews never run head tags or scripts, whatever the switches say.
Note
Requires a session JWT, and the admin or owner role in the organization that owns {projectId}. API keys are rejected with 401. The AI connector can't call this.
Path Parameters
NameDescription
projectIdThe project ID, a UUID.
Request Body
Send only the switches you want to change; the others stay as they are.
NameDescription
cssCSS from your docs —
_syntext/*.css and every page's css: file. On by default.headHead tags from your docs —
_syntext/head.html. Off by default.scriptsScripts from your docs —
_syntext/*.js. Off by default.confirmPrivateRequired as
true to turn head or scripts on for a private site (behind a password, invites or SSO): scripts there can read everything a signed-in reader sees. Without it the request returns 409 confirmation_required.Response
NameDescription
data.docsCodeThe switches after the change — the same object as
docsCode in Get Custom Code.Response — 409 on a private site
Send the same request with "confirmPrivate": true to go ahead.
Errors
| Status | Code | When |
|---|---|---|
| 400 | validation_error | A value that isn't a boolean, or a key other than css, head, scripts and confirmPrivate |
| 401 | unauthorized | No session token, an invalid or expired one, or an API key |
| 403 | forbidden | You're not an admin or owner: "Only workspace admins can change custom code switches." |
| 404 | not_found | The project doesn't exist |
| 409 | confirmation_required | Turning on head or scripts for a private site without confirmPrivate: true. details.switches names them |
Was this page helpful? Yes No
Previous
Request
cURLJavaScriptPythonGoRubyPHPJavaC#cURL
curl -X PUT https://api.syntext.dev/v1/projects/$PROJECT_ID/custom-scripts/docs-code \
-H "Authorization: Bearer $SYNTEXT_JWT" \
-H "Content-Type: application/json" \
-d '{ "head": true, "scripts": true }'
// A browser has no environment variables: set these to your values.
const PROJECT_ID = '<PROJECT_ID>';
const SYNTEXT_JWT = '<SYNTEXT_JWT>';
const response = await fetch(`https://api.syntext.dev/v1/projects/${PROJECT_ID}/custom-scripts/docs-code`, {
method: 'PUT',
headers: {
'Authorization': `Bearer ${SYNTEXT_JWT}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"head": true,
"scripts": true
}),
});
const data = await response.json();
console.log(response.status, data);
import os
import requests
url = f"https://api.syntext.dev/v1/projects/{os.environ['PROJECT_ID']}/custom-scripts/docs-code"
headers = {
"Authorization": f"Bearer {os.environ['SYNTEXT_JWT']}",
}
payload = {
"head": True,
"scripts": True,
}
response = requests.put(url, headers=headers, json=payload)
print(response.status_code)
print(response.json())
package main
import (
"bytes"
"fmt"
"io"
"net/http"
"os"
)
func main() {
payload := []byte(`{
"head": true,
"scripts": true
}`)
req, err := http.NewRequest("PUT", "https://api.syntext.dev/v1/projects/"+os.Getenv("PROJECT_ID")+"/custom-scripts/docs-code", bytes.NewReader(payload))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("SYNTEXT_JWT"))
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/#{ENV.fetch("PROJECT_ID")}/custom-scripts/docs-code")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"
request = Net::HTTP::Put.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("SYNTEXT_JWT")}"
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"head" => true,
"scripts" => true,
})
response = http.request(request)
puts response.code
puts response.body
<?php
$payload = [
'head' => true,
'scripts' => true,
];
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => 'https://api.syntext.dev/v1/projects/' . getenv('PROJECT_ID') . '/custom-scripts/docs-code',
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SYNTEXT_JWT'),
'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 = """
{
"head": true,
"scripts": true
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.syntext.dev/v1/projects/" + System.getenv("PROJECT_ID") + "/custom-scripts/docs-code"))
.header("Authorization", "Bearer " + System.getenv("SYNTEXT_JWT"))
.header("Content-Type", "application/json")
.method("PUT", 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.Put, "https://api.syntext.dev/v1/projects/" + Environment.GetEnvironmentVariable("PROJECT_ID") + "/custom-scripts/docs-code");
request.Headers.TryAddWithoutValidation("Authorization", "Bearer " + Environment.GetEnvironmentVariable("SYNTEXT_JWT"));
request.Content = new StringContent(
"""
{
"head": true,
"scripts": true
}
""",
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": {
"docsCode": {
"css": true,
"head": true,
"scripts": true,
"updatedAt": "2026-11-15T10:04:11.000Z",
"updatedBy": "8f6a2c1e-3b4d-4e5f-9a0b-1c2d3e4f5a6b",
"privateConfirmedAt": null
}
}
}
Responseapplication/json
409on a private site
{
"error": {
"code": "confirmation_required",
"message": "This site is private. Turning on head tags and scripts lets those scripts read everything a signed-in reader sees on the site. Confirm to turn them on.",
"details": { "switches": ["head", "scripts"] }
}
}