Update project settings
Only the fields you send change. solve needs a plan with automatic CAPTCHA solving (402 feature_not_in_plan). An explicit captcha on a session or agent run always wins. Changes apply to sessions started afterwards. A change made by an admin acting as you is recorded in the admin audit log.
PUT
/v1/project/settingsRequest
| Method and path | PUT/v1/project/settings |
|---|---|
| Base URL | https://api.boxline.dev |
| Authentication | Your API key in the x-api-key header (or Authorization: Bearer). The examples read it from BOXLINE_API_KEY. |
Body
JSON with content-type: application/json. Required.
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
captchaDefault | string | – | ask, ignore, solve | What happens when a CAPTCHA waits for a person. ask (default): agent runs and steps pause and hand over. ignore: they carry on. solve (opt-in, paid plans): the platform tries to solve it first. |
trajectories | object | – | – | |
trajectories.enabledrequired | boolean | – | – | |
trajectories.source | string | – | notice, settings | Where the choice was made (logged; also marks the notice as seen). |
defaultModel | object | null | – | – | |
defaultModel.provider | string | – | anthropic, openai, xai, google | Anthropic Claude, OpenAI, Grok (xAI), Google Gemini. Grok and Gemini have no computer use (mode computer is 400). |
defaultModel.model | string | – | – |
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", "defaultModel": {"provider": "openai", "model": "gpt-6-luna"} }'import { Boxline } from "@boxline/sdk";const bx = new Boxline(); // reads BOXLINE_API_KEY and BOXLINE_API_URLconst settings = await bx.project.setSettings({ captchaDefault: "solve", defaultModel: { provider: "openai", model: "gpt-6-luna" },});console.log(settings.captchaDefaultEffective);// The Trajectories choice is a setting too:await bx.project.setSettings({ trajectories: { enabled: false } });from boxline import Boxlinebx = Boxline() # reads BOXLINE_API_KEY and BOXLINE_API_URLsettings = bx.project.set_settings( captcha_default="solve", default_model={"provider": "openai", "model": "gpt-6-luna"},)print(settings["captchaDefaultEffective"])# The Trajectories choice is a setting too:bx.project.set_settings(trajectories={"enabled": False})Responses
200 OK
The settings now.
Fields
| Name | Type | Default | Allowed values | Description |
|---|---|---|---|---|
captchaDefault | string | – | ask, ignore, solve | What happens when a CAPTCHA waits for a person. ask (default): agent runs and steps pause and hand over. ignore: they carry on. solve (opt-in, paid plans): the platform tries to solve it first. |
captchaDefaultEffective | string | – | ask, ignore, solve | What happens when a CAPTCHA waits for a person. ask (default): agent runs and steps pause and hand over. ignore: they carry on. solve (opt-in, paid plans): the platform tries to solve it first. |
defaultModel | object | null | – | – | The model used when a request names no provider and no model (explicit request, then this, then the server default). |
defaultModel.provider | string | – | anthropic, openai, xai, google | Anthropic Claude, OpenAI, Grok (xAI), Google Gemini. Grok and Gemini have no computer use (mode computer is 400). |
defaultModel.model | string | – | – | |
trajectories | object | – | – | |
trajectories.enabled | boolean | – | – | |
trajectories.noticeSeenAt | string | null | – | – | Format: date-time. |
trajectories.decidedBy | string | null | – | – | The user who made the last choice (null for an API key). |
updatedAt | string | null | – | – | Format: date-time. |
updatedBy | string | null | – | – | The project's own user who changed it last in the console (null for an API key or support). |
updatedVia | string | null | – | console, api_key, support, null | How it was changed last (support means the platform's support staff); null if never. |
{ "captchaDefault": "ask", "captchaDefaultEffective": "ask", "defaultModel": { "provider": "anthropic", "model": "claude-sonnet-5-5" }, "trajectories": { "enabled": false, "noticeSeenAt": "2026-09-29T10:00:00.000Z", "decidedBy": "…" }, "updatedAt": "2026-09-29T10:00:00.000Z", "updatedBy": "…", "updatedVia": "console"}Errors
Errors have a matching HTTP status and the same body. code is stable, so check it in your code; message is for people. See Errors and request ids.
| Status | Codes | When |
|---|---|---|
| 400 Bad Request | invalid_request, invalid_json, invalid_cursor, invalid_idempotency_key, invalid_extension, variables_with_extensions, terms_not_accepted, invalid_reset_token, invalid_confirmation_code, wrong_password, no_password, invalid_next, invalid_oauth_token | The request is not valid. |
| 401 Unauthorized | unauthorized | Missing or invalid API key. |
| 402 Payment Required | feature_not_in_plan, spend_limit, out_of_credit, plan_limit, spend_limit, out_of_credit, organization, project, plan, credit | The plan does not include this, a monthly allowance or spending limit is used up, the organization has no credit left, or the plan allows no more of this. spend_limit and out_of_credit carry error.details.limit: organization, project, plan or credit. |
{ "error": { "code": "not_found", "message": "session not found", "requestId": "req_4fJx0aQm2Lk9Pz7N" }}Learn more
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.