Project settings apply to your whole project. There are three: the CAPTCHA default (what new sessions and agent runs do when a CAPTCHA waits for a person and they did not say), the default model, and your choice about the Trajectories program.

In the console, only an owner or an admin of the organization can change them. An API key has no role: it can change them, which is one more reason to keep keys safe. See Organizations, projects and team members.

Read the settings

curl https://api.boxline.dev/v1/project/settings \  -H "x-api-key: $BOXLINE_API_KEY"

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst settings = await bx.project.settings();console.log(settings.captchaDefault, settings.captchaDefaultEffective, settings.updatedVia);

from boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLsettings = bx.project.settings()print(settings["captchaDefault"], settings["captchaDefaultEffective"], settings["updatedVia"])

Response (shape)

{  "captchaDefault": "ask",  "captchaDefaultEffective": "ask",  "defaultModel": null,  "trajectories": { "enabled": true, "noticeSeenAt": null, "decidedBy": null },  "updatedAt": null,  "updatedBy": null,  "updatedVia": null}

Field	Meaning
`captchaDefault`	What new sessions and agent runs do about CAPTCHAs when they do not set captcha themselves: "ask" (the default), "ignore" or "solve".
`captchaDefaultEffective`	What they get now. It is "ask" when the setting is "solve" but your plan no longer includes automatic solving.
`defaultModel`	The model used when a request names none: { provider, model }, or null. See "The default model" below.
`trajectories`	Whether your project takes part in the Trajectories program: { enabled, noticeSeenAt, decidedBy }. See "Trajectories" below.
`updatedAt`	When it last changed, or null if never.
`updatedBy`	Your project's own user who changed it in the console, or null (a change with an API key or by support).
`updatedVia`	How it last changed: "console", "api_key" or "support" (the platform's support staff), or null if never.

Change the CAPTCHA default

PUT /v1/project/settings changes only the fields you send; an unknown field is a 400, and every field is checked before any is written. In the console, “Solve CAPTCHAs automatically” is captchaDefault: "solve".

curl -X PUT https://api.boxline.dev/v1/project/settings \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{"captchaDefault": "solve"}'

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst settings = await bx.project.setSettings({ captchaDefault: "solve" });console.log(settings.captchaDefaultEffective);

from boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLsettings = bx.project.set_settings(captcha_default="solve")print(settings["captchaDefaultEffective"])

"solve" needs a plan with automatic CAPTCHA solving; without it the answer is 402 feature_not_in_plan. If your plan loses it later, the setting stays, but new sessions get "ask": captchaDefaultEffective shows what they get now.
Every change is logged with who made it and how. A change made by support also goes to the admin audit log.

The default model

defaultModel is the model used when a request names no provider and no model. The order is: the request, then this, then Boxline’s default. Send null to clear it. It does not need a key when you save it. Keys and billing are on Your own model keys.

curl -X PUT https://api.boxline.dev/v1/project/settings \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{"defaultModel": {"provider": "openai", "model": "gpt-6-luna"}}'

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLawait bx.project.setSettings({ defaultModel: { provider: "openai", model: "gpt-6-luna" } });

from boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLbx.project.set_settings(default_model={"provider": "openai", "model": "gpt-6-luna"})

How the CAPTCHA default is used

What	Uses the default?
A new session without `captcha` (or with `null`)	Yes
A new agent run without `captcha`, in its own session	Yes
An agent run in an existing session (`sessionId`)	No: that session’s own setting applies
A session or run that sets `captcha` itself	No: an explicit option always wins, and is checked against your plan as before
Sessions already running	No: they keep the setting they started with
Crawls, and fetch, screenshot, PDF and extract	No: they cannot wait for a person or solve, so they report the CAPTCHA’s kind instead

See CAPTCHAs for what "ask", "ignore" and "solve" do.

Trajectories

The Trajectories program is on by default. It decides whether sessions your project starts are eligible for datasets of agent trajectories. The choice is part of the project settings, so you read and change it with the same two calls. What the program is, and which sessions are eligible, is on Trajectories.

GET /v1/project/settings returns trajectories with three fields. To change it, send trajectories to PUT /v1/project/settings.

curl -X PUT https://api.boxline.dev/v1/project/settings \  -H "x-api-key: $BOXLINE_API_KEY" \  -H "content-type: application/json" \  -d '{"trajectories": {"enabled": false}}'

import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst before = await bx.project.settings();console.log(before.trajectories); // { enabled, noticeSeenAt, decidedBy }const settings = await bx.project.setSettings({ trajectories: { enabled: false } });console.log(settings.trajectories.enabled); // false: off for sessions started from now on

from boxline import Boxlinebx = Boxline()  # reads BOXLINE_API_KEY and BOXLINE_API_URLbefore = bx.project.settings()print(before["trajectories"])  # {"enabled", "noticeSeenAt", "decidedBy"}settings = bx.project.set_settings(trajectories={"enabled": False})print(settings["trajectories"]["enabled"])  # False: off for sessions started from now on

Field	Meaning
`enabled`	Read and send. `true` or `false`: whether the program is on for your project.
`noticeSeenAt`	Read only. When your project was shown the notice, or first made a choice. `null` means not yet, and until then no session is eligible.
`decidedBy`	Read only. The user who made the last choice, or `null` when it was made with an API key.
`source`	Send only, optional. Where the choice was made: `"settings"` (the default) or `"notice"` (an answer to the first-use notice).

The choice is logged (who, how and when) and marks the notice as seen.
A change applies to sessions that start after it. A session keeps the trajectoriesEligible it started with.
In the console, only an owner or an admin can change it. An API key can too, so keep keys safe, and read the setting back (trajectories.enabled) when your program must never take part.
See Update project settings for every field.

These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.