--- title: "Create a project" method: POST path: "/v1/projects" tags: ["Projects"] --- # Create a project `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`) 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. ## Request body - ProjectCreate - `name` string, required: Human-readable project name. - `idempotency_key` string: 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`. ## Response `201` Project created. - Project - `id` string, required: Public project ID (proj_ prefix). - `name` string, 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_id` string, 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_id` string, 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_days` integer, 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_runs` integer, 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_generations` integer, 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_depth` integer, 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_model` boolean, 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](/docs/modules/projects#requiring-a-priced-model). - `guardrail_ids` string[], 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](/docs/modules/guardrails#attaching-one). - `paused_at` string, date-time, nullable, required: When the project was paused; `null` while it runs. See [Pausing a project](/docs/modules/projects#pausing-a-project). - `pause_reason` string, nullable, required: The reason the pause named; `null` while the project runs, or when the pause named none. - `managed_conversion` boolean, required: Whether scanned PDFs, images and audio are converted to text on ingest with no setup. `true` by default. See [Managed conversion](/docs/modules/documents#managed-conversion). - `created_at` string, date-time, required - `updated_at` string, date-time, required ## Other responses - `400`: The request was malformed or failed validation. - `401`: Missing or invalid credentials. - `403`: The credential is scoped to a different project, or the caller's role in the project does not carry this action. - `409`: The `idempotency_key` is already claimed by a different request (`idempotency_key_reused`), or by one still in flight (`idempotency_request_in_progress`). --- [API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)