Projects

Pause a project

Stops everything the project runs, with one call. From the moment it answers, nothing new starts: generations, tool calls, orchestration runs, eval runs and trigger fires in the project respond 409 with PROJECT_PAUSED, and so does resuming a single run or task the pause holds. A channel keeps receiving messages and answers each with a neutral "can't reply right now" line. What is already in motion is parked, not discarded: live orchestration runs pause at their next checkpoint, open tasks stop dispatching, schedule triggers stop firing and queued eval items wait. A generation already running finishes. Reads and configuration changes keep working. Idempotent: pausing a paused project answers it unchanged and keeps the first reason. Emits project.paused. Requires the admin role.

post/v1/projects/{project_id}/pause

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/pause
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

reasonstring

Why the project is paused. Stored as pause_reason and carried onto every run and task the pause parks.

Example request

{
  "reason": "anomaly detected by the spend monitor"
}

Response

The paused project.

idstring required

Public project ID (proj_ prefix).

namestring required
status'active' | 'archived' required
role'owner' | 'admin' | 'member' required

What the member may do in this project. owner — everything, including deleting it and paying for it; exactly one per project. admin — everything a member may do, plus managing who else is in the project and how the project itself is configured. member — every read and write on the project's own resources, including minting project API keys. When returned on a Project, this is your role, not a property of the project: it is what lets a client hide an action the request would refuse.

owner_user_idstring required

The user who pays for the project — its billing owner, and the one member holding the owner role. Membership decides who may act in a project; this decides who is charged for it.

transfer_to_user_idstring nullable required

The member a pending transfer would make the owner, until they accept or decline it; null when none is pending.

trace_content_retention_daysinteger nullable required

How long trace and generation content is kept before a daily sweep purges it. null (the default) disables retention, so content is kept until purged on demand. A swept record is content-purged the same way an on-demand purge does it — the row survives as an auditable skeleton with content_redacted_at set.

trace_content_mode'full' | 'none' required

Whether trace and generation content is persisted at all. full (the default) stores it; none is zero-retention — content is never written, for every agent in this project. none is a floor, not a default: an agent may tighten itself to none, but cannot loosen a none project back to full.

max_concurrent_runsinteger nullable required

Orchestration runs of this project driven at once. null (the default) is unlimited. Enforced when a run is claimed — runs past the limit wait for a slot rather than failing.

max_chain_generationsinteger nullable required

Generations one continuation chain in this project may hold before it stops being resumed. null (the default) leaves the platform-wide ceiling in force. The budget actually applied is the smallest of that ceiling, this number, and the agent's own — an agent author can be stricter than this, never looser.

max_orchestration_run_depthinteger nullable required

Nesting levels a run tree in this project may reach before the next child is refused. null (the default) leaves the platform-wide bound in force; the bound applied is the smaller of the two.

require_priced_modelboolean required

Whether a generation whose model carries no price is refused before the provider is called. false by default, which runs the model and meters it at no cost. Mainly of use with your own providers — see Requiring a priced model.

guardrail_idsstring[] required

Guardrails attached at the project scope — the floor under every tool call by every agent in the project, including tools added later. Empty by default. See Attaching one.

paused_atstring date-time nullable required

When the project was paused; null while it runs. See Pausing a project.

pause_reasonstring nullable required

The reason the pause named; null while the project runs, or when the pause named none.

managed_conversionboolean required

Whether scanned PDFs, images and audio are converted to text on ingest with no setup. true by default. See Managed conversion.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "proj_V1StGXR8Z5jdHi6B",
  "name": "acme-perpetual",
  "status": "active",
  "role": "owner",
  "owner_user_id": "user_V1StGXR8Z5jdHi6B",
  "trace_content_mode": "full",
  "guardrail_ids": [],
  "managed_conversion": true,
  "created_at": "2026-07-17T00:00:00.000Z",
  "updated_at": "2026-07-17T00:00:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.