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: - $ref: './pagination.yaml#/components/parameters/Limit' - $ref: './pagination.yaml#/components/parameters/Offset' 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 additionalProperties: false 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_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), 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 additionalProperties: false 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_orchestration_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`. require_priced_model: type: boolean example: true description: >- Refuse a generation whose model carries no price row for every billable token component, with `409 MODEL_NOT_PRICED`. Defaults to `false`, where an unpriced model runs and meters at `cost_usd: null`. The check runs before the provider is called, so a refused turn spends nothing, and covers every target of a model route the turn may fail over to. default_conversation_retrieval: type: string enum: [embed, none] example: none description: >- What a conversation that names no `retrieval` of its own does. `none` by default: a turn is embedded because someone asked for the conversation to be retrievable, never merely because it was said. Turns are stored and chunked on both settings. 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, memory stores, 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: './errors.yaml#/components/schemas/ErrorResponse' /api/v1/projects/{project_id}/pause: post: tags: - Projects summary: Pause a project description: >- Stops everything the project runs, with one call. From the moment it answers, nothing new starts in the project: agent, session and conversation generations, tool-output continuations, chat completions, direct tool calls, orchestration runs, eval runs and trigger firings are refused with `409 PROJECT_PAUSED`, and so is resuming a single run or task the pause holds. What is already in motion is parked rather than discarded: every live orchestration run is paused the way pause-orchestration-run pauses it (a running one parks at its next checkpoint), every open task's automation is paused, schedule triggers stop firing, and queued eval items wait unclaimed. A generation or node already in flight finishes. Reads and configuration writes keep working. Idempotent: pausing a paused project answers it unchanged and keeps the first `reason`. Emits `projects.paused`. operationId: pauseProject parameters: - name: project_id in: path required: true description: Project public ID (proj_ prefix) schema: type: string example: proj_V1StGXR8Z5jdHi6B requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/PauseProjectRequest' responses: '200': description: The paused project content: application/json: schema: $ref: '#/components/schemas/ProjectRecord' '400': description: Bad Request (reason is not a string of at most 256 characters) '401': description: Unauthorized '403': description: Forbidden '404': description: Project not found /api/v1/projects/{project_id}/resume: post: tags: - Projects summary: Resume a project description: >- Lifts the project's pause and hands back exactly what it held: the runs and tasks the pause parked are resumed (a run the way resume-orchestration-run resumes it, in the background; a task's suppressed dispatch runs as the caller), and schedule triggers fire again from their next occurrence after now — an occurrence that fell due while paused is not fired late. A run or task an operator paused before the project was paused keeps its own pause. Eval runs continue from the item they stopped at. Emits `projects.resumed`. operationId: resumeProject x-soat-agent-exclude: true parameters: - name: project_id in: path required: true description: Project public ID (proj_ prefix) schema: type: string example: proj_V1StGXR8Z5jdHi6B responses: '200': description: The resumed project content: application/json: schema: $ref: '#/components/schemas/ProjectRecord' '401': description: Unauthorized '403': description: Forbidden '404': description: Project not found '409': description: The project is not paused content: application/json: schema: $ref: './errors.yaml#/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 x-soat-agent-exclude: true 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_orchestration_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 require_priced_model: type: boolean description: >- Whether a generation whose model carries no price row is refused with `409 MODEL_NOT_PRICED`. `false` by default, where an unpriced model runs and meters at `cost_usd: null`. example: false default_conversation_retrieval: type: string enum: [embed, none] description: >- What a conversation that names no `retrieval` of its own does. `none` by default. example: none 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 paused_at: type: string format: date-time nullable: true description: >- When the project was paused. `null` while it runs. While set, nothing new starts in the project — see pause-project. example: null pause_reason: type: string nullable: true maxLength: 256 description: >- The reason the pause was requested with, echoed as `pause_reason` on every run and task the pause parked. `null` while the project runs, or when the pause named none. example: null 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' PauseProjectRequest: type: object additionalProperties: false properties: reason: type: string maxLength: 256 description: >- Why the project is paused. Stored as `pause_reason` and carried onto every run and task the pause parks. example: anomaly detected by the spend monitor 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: "`llm_tokens` for a token row or an agent's resource row, `tool_execution` for a tool's" resource: type: string nullable: true description: The tool or agent SRN a resource row prices; null for a SKU row quantity: type: object nullable: true additionalProperties: true description: A resource row's quantity expression; null prices one per call 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`, `cache_write_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 additionalProperties: false properties: prices: type: array items: type: object required: - component - unit - unit_price - effective_from additionalProperties: false properties: meter_type: type: string enum: [llm_tokens, tool_execution] default: llm_tokens description: >- `llm_tokens` for a token row naming `provider` and `model`, or for an agent's resource row; `tool_execution` for a tool's resource row. resource: type: string description: >- The SRN of one tool or agent, `srn:::`, for a resource row; omit `provider` and `model`. A tool's row prices its `tool_execution` events, beside `tool_call`; an agent's prices its `llm_tokens` events, beside the provider cost. A client tool has no execution of its own and cannot be priced. example: srn:proj_V1StGXR8Z5jdHi6B:tool:tool_V1StGXR8Z5jdHi6B quantity: type: object additionalProperties: true description: >- On a resource row only: JSON Logic giving the quantity `unit_price` multiplies, over `{ input, action, response, outcome, duration_ms }` for a tool and `{ response: { usage, cost_usd, steps, tool_calls, stop_reason }, outcome }` for an agent. Omit to price one per call. A result that is not a finite number >= 0 records quantity `0` and no cost. example: { var: response.page_count } provider: type: string description: The provider slug of a token row example: openai model: type: string description: The model of a token row example: gpt-4o component: type: string description: >- The component this row prices: a token component (`input_tokens`, `output_tokens`, `cached_tokens`, `cache_write_tokens`), or a resource row's own (`page`) unit: type: string description: "`token` for token pricing; the resource component's unit otherwise" unit_price: type: number description: USD per `unit` effective_from: type: string format: date-time description: Must be in the future; past prices are immutable