# Projects > Multi-tenant namespaces in SOAT; every document, file, actor, and conversation belongs to a project. # Projects The Projects module provides multi-tenant namespaces in SOAT. Every resource ([document](./documents.md), [file](./files.md), [actor](./actors.md), [conversation](./conversations.md)) belongs to a project. Projects are identified by an `id` prefixed with `proj_`. ## Overview A Project is a top-level container that scopes all resources. Users access projects through policy-based authorization — there is no separate membership table. Whether a user can access a project is determined entirely by the [policies](./policies.md) attached to their account and the SRN patterns those policies contain. For a project creation walkthrough, see [Chat with an LLM - Step 2 (Create a project)](/docs/tutorials/chat-with-llm#step-2--create-a-project). > See the [Permissions Reference](../permissions.md) for the IAM action strings for this module. ## Related Tutorials - [Chat with an LLM - Step 2 (Create a project)](/docs/tutorials/chat-with-llm#step-2--create-a-project) - [Permissions in Practice - Step 3 (Create the Analytics project)](/docs/tutorials/permissions#step-3--create-the-analytics-project) - [Deploy a Multi-Agent App with Agent Formation - Step 2 (Create a project)](/docs/tutorials/formations#step-2--create-a-project) - [Data Retention and Zero-Retention - Step 7 (Automate it with a retention window)](/docs/tutorials/data-retention-and-zero-retention#step-7--automate-it-with-a-retention-window) ## Data Model | Field | Type | Description | | ------------ | ------ | --------------------------------------- | | `id` | string | Public identifier prefixed with `proj_` | | `name` | string | Human-readable project name | | `guardrail_ids` | array | Guardrails attached at the project scope — the baseline governing every tool call by every agent in the project. See [Guardrails — Attachment](./guardrails.md#attachment) | | `default_model_route_id` | string \| null | [Model route](./model-routes.md#project-default-route) inherited by consumers in this project that bind neither `model_route_id` nor `ai_provider_id`. `null` (default) means no default, so every consumer must bind explicitly. Settable/clearable via `update-project`. | | `max_concurrent_runs` | integer \| null | Maximum [orchestration runs](./orchestrations.md#concurrency-limits) of this project driven at once. `null` (default) means unlimited; otherwise an integer ≥ 1. Settable/clearable via `update-project`. | | `max_chain_generations` | integer \| null | Generations one [continuation chain](./chains.md#bounding-a-chain) in this project may hold before the platform stops resuming it. `null` (default) means no project ceiling, leaving the deployment-wide one; otherwise an integer ≥ 1. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `maxChainGenerations`. Settable/clearable via `update-project`. | | `max_orchestration_run_depth` | integer \| null | `loop` / `sub_orchestration` [nesting levels](./orchestrations.md#nesting-depth) a run tree in this project may reach before the engine refuses to start the next child. `null` (default) means no project bound, leaving the deployment-wide one; otherwise an integer ≥ 1. The effective bound is the smaller of the two. Settable/clearable via `update-project`. | | `audit_reads_enabled` | boolean | Opts the project into [read auditing](./audit-log.md#read-auditing): when `true`, `GET` requests naming this project are recorded in the audit log alongside mutations. `false` by default. Settable via `update-project`. | | `trace_content_retention_days` | integer \| null | Days of [trace/generation content retention](./traces.md#retention-policy) before the daily sweep purges it. `null` (default) disables retention; otherwise an integer ≥ 1. Settable/clearable via `update-project`. | | `trace_content_mode` | string | `full` (default) or `none`. `none` is [zero-retention](./traces.md#zero-retention-mode): trace and generation content is never written for any agent in the project. Settable via `update-project`. | | `created_at` | string | ISO 8601 creation timestamp | | `updated_at` | string | ISO 8601 last-updated timestamp | ## Key Concepts ### Project Access via Policies Project access is entirely policy-driven; there is no membership list to maintain. Access is granted by attaching a [Policy](./policies.md) to the user (or their API key) that contains an `Allow` statement covering the relevant project's SRN pattern: ```json { "statement": [ { "effect": "Allow", "action": ["projects:GetProject", "files:ListFiles", "files:GetFile"], "resource": ["srn:proj_ABC:*:*"] } ] } ``` For a complete scoped-access walkthrough, see [Permissions in Practice - Step 3 (Create the Analytics project)](/docs/tutorials/permissions#step-3--create-the-analytics-project). To grant a user access to all projects, use a wildcard project segment: ```json { "resource": ["srn:*:*:*"] } ``` ### Visibility Rules - **Admin users** see all projects. - **API key callers** scoped to a project see only that project. - **Regular users** see only the projects covered by the SRN patterns in their attached policies. Authorization is policy-only: all access decisions are evaluated through the policy engine against the requested action and resource SRN, and a project-scoped grant is honored by every project endpoint, including [`GET /projects/{id}`](/docs/api/projects/get-project). See [IAM](./iam.md) for details. ### Default Model Route `default_model_route_id` names the [model route](./model-routes.md) every consumer in the project inherits when it binds neither `model_route_id` nor `ai_provider_id` — a single project-scoped switch that gives agents, chats, and memory completions provider failover without editing each one. ```bash soat update-project --project-id proj_… --default_model_route_id route_… ``` The route must belong to this project. An explicit binding on a consumer always wins, so the default can never override a deliberate pin. Repointing the default to another route is free; **clearing** it returns `409 PROJECT_DEFAULT_ROUTE_INHERITED` while any consumer inherits it, and deleting the route itself returns `409 MODEL_ROUTE_HAS_DEPENDENTS`. Governed by `projects:UpdateProject`. ### Deletion Deleting a project that has any dependent resource returns `409 Conflict` with error code `PROJECT_HAS_DEPENDENTS`. "Any" is literal — every project-scoped resource counts, including the ones a project accumulates on its own while it runs: - agents, AI providers, [model routes](./model-routes.md), tools, [ingestion rules](./ingestion-rules.md) - actors, chats, conversations, sessions, [generations](./generations.md), [traces](./traces.md) - [datasets and evals](./evaluations.md), [workflows and tasks](./workflows.md), [triggers](./triggers.md), [orchestrations](./orchestrations.md) and their runs - [formations](./formations.md), [memories](./memories.md), [secrets](./secrets.md), [files](./files.md), [guardrails](./guardrails.md), [quotas](./quotas.md) - [usage](./usage.md) history, and the [activity](./activity.md), [approval](./approvals.md), [exception](./exceptions.md) and guardrail-evaluation records of past runs Pass `?force=true` to delete all dependents along with the project in a single transaction — including the billing/usage history, and the stored bytes of the project's [files](./files.md), so a force-deleted project leaves nothing behind in storage. The [audit log](./audit-log.md) is the one deliberate exception: its entries outlive the project, keeping the record of who did what with `project_id` cleared instead of the row deleted. ### Common Errors | Status | Body | Cause | What to do | | ------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `403` | `{ "error": "Forbidden" }` | Caller isn't the `admin` role — creating, renaming, and deleting a project are admin-only | Authenticate as the admin user, or have an admin perform the operation | | `403` | `{ "error": "Forbidden" }` | [`GET /projects/{id}`](/docs/api/projects/get-project) (or a nested resource route) with a policy/API key that doesn't cover this project's SRN — e.g. a project key created for a **different** project | Check the caller's attached policies cover `srn::*:*`, or use a key scoped to this project — see [Project Access via Policies](#project-access-via-policies) | | `404` | — | The project ID doesn't exist, or the caller can't see it because no policy grants access to it (existence isn't leaked) | Verify the ID; if it should exist, confirm a policy grants visibility — see [Visibility Rules](#visibility-rules) | | `409` | `{ "error": { "code": "PROJECT_HAS_DEPENDENTS" } }` | Deleting a project that still has dependent resources | Pass `?force=true`, or delete the dependent resources first — see [Deletion](#deletion) | | `409` | `{ "error": { "code": "PROJECT_DEFAULT_ROUTE_INHERITED" } }` | Clearing `default_model_route_id` while consumers that bind nothing inherit it — they would be left with no resolvable model | Bind those consumers explicitly (`meta.sample` names some), or repoint the default to another route, which is always allowed — see [Project default route](./model-routes.md#project-default-route) | ## Examples ### Create a project ```bash soat create-project --name "My Project" ``` ```ts // SDK const soat = new SoatClient({ baseUrl: 'https://api.example.com', token: 'sk_...', }); const { data, error } = await soat.projects.createProject({ body: { name: 'My Project' }, }); if (error) throw new Error(JSON.stringify(error)); ``` ```bash curl -X POST https://api.example.com/api/v1/projects \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"name": "My Project"}' ``` ### Get a project ```bash soat get-project --project-id proj_ABC ``` ```ts // SDK const { data, error } = await soat.projects.getProject({ path: { project_id: 'proj_ABC' }, }); if (error) throw new Error(JSON.stringify(error)); ``` ```bash curl https://api.example.com/api/v1/projects/proj_ABC \ -H "Authorization: Bearer " ``` ### Delete a project ```bash soat delete-project --project-id proj_ABC # Force-delete a project along with all of its dependent resources soat delete-project --project-id proj_ABC --force true ``` ```ts // SDK const { error } = await soat.projects.deleteProject({ path: { project_id: 'proj_ABC' }, query: { force: true }, }); if (error) throw new Error(JSON.stringify(error)); ``` ```bash curl -X DELETE "https://api.example.com/api/v1/projects/proj_ABC?force=true" \ -H "Authorization: Bearer " ```