Projects

Create a project

Creates a project (one per client or per environment).

Your plan limits how many projects you may own. At the limit this responds 403 with plan_limit_reached, whose details carry the plan and the limit. An archived project still counts — archiving keeps every resource, so it frees nothing; deleting a project does.

A new project starts at the content-retention window your plan sets (trace_content_retention_days); PATCH it to anything shorter.

post/v1/projects

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects
  • 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

namestring required

Human-readable project name.

idempotency_keystring

Deduplication key, unique within your account, that makes a retry of an ambiguous failure safe. The first request under a key performs the write and answers 201; any later request carrying the same key answers 200 with that same result, so a timeout you cannot interpret can simply be retried.

The key is claimed for as long as the record exists and never silently expires. Reusing one with a different request body is 409 idempotency_key_reused — a key names one request, so changing the body and keeping the key is a bug rather than a retry. A retry that arrives while the original is still in flight is 409 idempotency_request_in_progress.

Example request

{
  "name": "acme-perpetual",
  "idempotency_key": "signup-2026-09-18-acct-42"
}

Response

Project created.

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.