openapi: 3.0.3 info: title: SOAT Projects API version: 1.0.0 description: API for managing projects (Projects resource) contact: name: SOAT Team url: https://github.com/ttoss/soat servers: - url: '{baseUrl}' description: Base URL of your SOAT deployment (e.g. https://your-soat.com or http://localhost:5047) variables: baseUrl: description: The base URL of your SOAT deployment default: http://localhost:5047 tags: - name: Projects description: Manage projects security: - bearerAuth: [] paths: /api/v1/projects: get: tags: - Projects summary: List projects description: > Lists projects accessible to the caller. - JWT admin: returns all projects. - JWT regular user: returns only projects granted by the user's policies. - API key scoped to a project: returns only that project. operationId: listProjects security: - bearerAuth: [] parameters: - name: limit in: query required: false description: Maximum number of results to return schema: type: integer default: 50 - name: offset in: query required: false description: Number of results to skip schema: type: integer default: 0 responses: '200': description: List of projects content: application/json: schema: type: object required: - data - total - limit - offset properties: data: type: array items: $ref: '#/components/schemas/ProjectRecord' total: type: integer limit: type: integer offset: type: integer '401': description: Unauthorized post: tags: - Projects summary: Create a project description: Creates a new project. Requires admin role. operationId: createProject requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string example: My Project responses: '201': description: Project created successfully content: application/json: schema: type: object properties: id: type: string example: proj_V1StGXR8Z5jdHi6B name: type: string created_at: type: string format: date-time '401': description: Unauthorized '403': description: Forbidden (non-admin user) '500': description: Internal server error /api/v1/projects/{project_id}: get: tags: - Projects summary: Get a project description: Returns details of a specific project. operationId: getProject parameters: - name: project_id in: path required: true description: Project public ID (proj_ prefix) schema: type: string example: proj_V1StGXR8Z5jdHi6B responses: '200': description: Project details content: application/json: schema: $ref: '#/components/schemas/ProjectRecord' '401': description: Unauthorized '403': description: Forbidden '404': description: Project not found patch: tags: - Projects summary: Update a project description: >- Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires admin role. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail. operationId: updateProject parameters: - name: project_id in: path required: true description: Project public ID (proj_ prefix) schema: type: string example: proj_V1StGXR8Z5jdHi6B requestBody: required: true content: application/json: schema: type: object properties: name: type: string example: Renamed Project guardrail_ids: x-soat-ref: guardrails type: array nullable: true items: type: string description: Guardrails attached at the project scope. max_concurrent_runs: type: integer nullable: true minimum: 1 example: 5 description: >- Maximum orchestration runs of this project driven at once. `null` clears the limit (unlimited); otherwise an integer >= 1. Enforced at queue claim time — excess runs stay queued until a slot frees. max_chain_generations: type: integer nullable: true minimum: 1 example: 25 description: >- Generations one continuation chain in this project may hold before the platform stops resuming it. `null` clears the project's ceiling, leaving the deployment-wide `MAX_CONTINUATION_CHAIN_GENERATIONS`; otherwise an integer >= 1. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `max_chain_generations` stop condition, so an agent author can be stricter than this number but never exceed it. max_run_depth: type: integer nullable: true minimum: 1 example: 5 description: >- `loop` / `sub_orchestration` nesting levels a run tree in this project may reach before the engine refuses to start the next child. `null` clears the project's bound, leaving the deployment-wide `MAX_ORCHESTRATION_RUN_DEPTH` (default 10); otherwise an integer >= 1. The effective bound is the smaller of the two, so this can only be stricter than the deployment's — which is what makes it a bound a graph author cannot opt out of. A refused child fails its parent run with `ORCHESTRATION_RUN_DEPTH_LIMIT`. default_model_route_id: x-soat-ref: model-routes type: string nullable: true example: route_V1StGXR8Z5jdHi6B description: >- Model route inherited by consumers in this project that bind neither `model_route_id` nor `ai_provider_id`. The route must belong to this project (`400` otherwise). `null` clears the default, which is refused with `409` while any consumer inherits it — repointing it to another route is always allowed and immediately changes which targets those consumers use. audit_reads_enabled: type: boolean example: true description: >- Opt the project into read auditing. When true, `GET` requests that name this project are recorded in the audit log alongside mutations. Defaults to `false`. trace_content_retention_days: type: integer nullable: true minimum: 1 example: 90 description: >- How long trace and generation content is kept before the daily retention sweep content-purges it. `null` (the default) disables retention; otherwise an integer >= 1. The sweep uses the same purge path as `DELETE /traces/{trace_id}/content`, so the row survives as an auditable skeleton with `content_redacted_at` set. trace_content_mode: type: string enum: [full, none] example: none description: >- 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 the project. An agent may tighten this to `none` on its own but cannot loosen a `none` project back to `full`. responses: '200': description: Project updated successfully content: application/json: schema: $ref: '#/components/schemas/ProjectRecord' '400': description: Invalid request body '401': description: Unauthorized '403': description: Forbidden (non-admin user) '404': description: Project not found '409': description: >- `default_model_route_id` cannot be cleared while consumers inherit it (PROJECT_DEFAULT_ROUTE_INHERITED). delete: tags: - Projects summary: Delete a project description: > Deletes a project. Requires admin role. Fails with `409` if the project has any dependent resource, unless `force=true` is passed, in which case those resources are deleted along with the project. Every project-scoped resource counts: agents, ai providers, model routes, tools, ingestion rules, actors, chats, conversations, sessions, generations, traces, datasets, evals, workflows, tasks, triggers, orchestrations and their runs, formations, memories, secrets, files, guardrails, quotas, usage history — and the activity, approval, exception and guardrail-evaluation records a project accumulates while it runs. Audit log entries are the one exception: they outlive the project, keeping their record with `project_id` cleared. operationId: deleteProject parameters: - name: project_id in: path required: true description: Project public ID (proj_ prefix) schema: type: string example: proj_V1StGXR8Z5jdHi6B - name: force in: query required: false description: > When `true`, deletes all of the project's dependent resources instead of returning `409 PROJECT_HAS_DEPENDENTS`. schema: type: boolean default: false responses: '204': description: Project deleted successfully '401': description: Unauthorized '403': description: Forbidden (non-admin user) '404': description: Project not found '409': description: Project has dependent resources (pass `force=true` to delete anyway) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /api/v1/projects/{project_id}/prices: get: tags: - Projects summary: List a project's price rows description: > Returns the project's per-provider-slug price rows — the middle pricing tier that covers every one of the project's instances of a given provider slug. At cost time a per-provider-instance override wins over these, and these win over the global default. Authorized by the caller's access to the project. operationId: getProjectPrices parameters: - name: project_id in: path required: true description: Project public ID (proj_ prefix) schema: type: string example: proj_V1StGXR8Z5jdHi6B responses: '200': description: The project's price rows content: application/json: schema: $ref: '#/components/schemas/ProjectPricesResponse' '401': description: Unauthorized '403': description: Forbidden '404': description: Project not found put: tags: - Projects summary: Upsert a project's price rows description: > Upserts project + provider-slug price rows, keyed on (provider, model, effective_from). A row covers all of the project's instances of that provider slug. Authorized by the caller's access to the project. `effective_from` must be in the future once the (provider, model, component) is priced — past prices are immutable, so corrections ship as new future-dated rows. A first price, with no row for the project or the global default, may be dated now or earlier. operationId: updateProjectPrices parameters: - name: project_id in: path required: true description: Project public ID (proj_ prefix) schema: type: string example: proj_V1StGXR8Z5jdHi6B requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpsertProjectPricesRequest' responses: '200': description: The upserted price rows content: application/json: schema: $ref: '#/components/schemas/ProjectPricesResponse' '400': description: Bad Request (e.g. non-future effective_from) '401': description: Unauthorized '403': description: Forbidden '404': description: Project not found components: securitySchemes: bearerAuth: type: http scheme: bearer description: JWT token or sk_ api key schemas: ProjectRecord: type: object properties: id: type: string description: Public project ID (proj_ prefix) example: proj_V1StGXR8Z5jdHi6B name: type: string example: My Project guardrail_ids: x-soat-ref: guardrails type: array nullable: true items: type: string description: >- Guardrails attached at the project scope — the baseline governing every tool call by every agent in the project. example: [] max_concurrent_runs: type: integer nullable: true minimum: 1 description: >- Maximum orchestration runs of this project driven at once. `null` means unlimited (the default). Enforced at queue claim time. example: null max_chain_generations: type: integer nullable: true minimum: 1 description: >- Generations one continuation chain in this project may hold before the platform stops resuming it. `null` means no project ceiling (the default), leaving the deployment-wide one. The effective budget is the smallest of the deployment's ceiling, this one, and the agent's own `max_chain_generations` stop condition. example: null max_run_depth: type: integer nullable: true minimum: 1 description: >- `loop` / `sub_orchestration` nesting levels a run tree in this project may reach before the engine refuses to start the next child. `null` means no project bound (the default), leaving the deployment-wide one. The effective bound is the smaller of the two. example: null default_model_route_id: x-soat-ref: model-routes type: string nullable: true description: >- Model route inherited by consumers in this project that bind neither `model_route_id` nor `ai_provider_id`. `null` means no default, so every consumer must bind explicitly. example: null audit_reads_enabled: type: boolean description: >- Whether `GET` requests naming this project are recorded in the audit log. `false` by default — v1 audits mutations only. example: false trace_content_retention_days: type: integer nullable: true minimum: 1 description: >- Days of trace/generation content retention before the daily sweep purges it. `null` means retention is disabled (the default) and content is kept until purged on demand. example: null trace_content_mode: type: string enum: [full, none] description: >- Whether trace/generation content is persisted. `full` by default; `none` is zero-retention — content is never written for any agent in this project. example: full created_at: type: string format: date-time example: '2024-01-01T00:00:00.000Z' updated_at: type: string format: date-time example: '2024-01-01T00:00:00.000Z' ProjectPrice: type: object properties: id: type: string description: Public ID of the price row example: price_V1StGXR8Z5jdHi6B project_id: x-soat-ref: projects type: string description: The project this price is scoped to example: proj_V1StGXR8Z5jdHi6B ai_provider_id: type: string nullable: true description: Always null for a project + provider-slug price meter_type: type: string description: Always `llm_tokens` for project prices provider: type: string example: openai model: type: string example: gpt-4o component: type: string description: The token component this row prices (`input_tokens`, `output_tokens`, `cached_tokens`) unit: type: string description: Always `token` for token pricing unit_price: type: number description: USD per token for this component effective_from: type: string format: date-time description: The row with the latest effective_from <= now() prices a call created_at: type: string format: date-time ProjectPricesResponse: type: object properties: prices: type: array items: $ref: '#/components/schemas/ProjectPrice' UpsertProjectPricesRequest: type: object required: - prices properties: prices: type: array items: type: object required: - provider - model - component - unit - unit_price - effective_from properties: provider: type: string example: openai model: type: string example: gpt-4o component: type: string description: The token component this row prices (`input_tokens`, `output_tokens`, `cached_tokens`) unit: type: string description: Always `token` for token pricing unit_price: type: number description: USD per token for this component effective_from: type: string format: date-time description: Must be in the future; past prices are immutable ErrorResponse: type: object required: - error properties: error: type: object description: >- Structured error. Every error response uses this shape — 401, 403 and the 500 catch-all included — so `code` can be read without first checking the type of `error`. required: - code - message - hint - docs_url properties: code: type: string description: A key from the server's ERROR_CODES registry. example: RESOURCE_NOT_FOUND message: type: string example: 'Resource not found' hint: type: string description: >- What to do about this error. Resolved per code, so a caller that has never seen the code before can act on the response without leaving it. example: >- Check the id, and check that the credential can see the project that owns the resource. docs_url: type: string format: uri description: The reference-page anchor documenting this code. example: >- https://soat.ttoss.dev/docs/error-codes#resource_not_found meta: type: object description: Optional structured context for the error.