#Projects

List projects, retrieve project details, manage partner project lifecycle/profile/assignment state, update draft runtime workspaces, run controlled release operations, access legacy project billing configuration.

• Production API: https://api.aidial.ai
• Version prefix: /v1

This page omits environment-specific host names, internal topology, and deployment details.

Protected project routes use shared authentication unless the endpoint states a stricter scope. Shared authentication resolves credentials in this order:

1. X-API-Key
2. Authorization: Bearer <jwt>

Both modes resolve to an AuthContext. Bearer authentication requires ZITADEL_ISSUER, ZITADEL_AUDIENCE, and ZITADEL_JWKS_URL; these settings are required and have no fallback defaults.

Project metadata, lifecycle state, drafts, published versions, legacy project billing configuration are stored server-side. Project-secret values are handled by server-side secret writers and are not returned by project responses. Project responses are scoped to the authenticated client_id; out-of-scope projects return 404 Not Found to avoid tenant enumeration. Missing or invalid authentication returns 401 Unauthorized.

#Response Shapes

The projects router has these current response families:

• Project list/detail responses use project detail, draft, published version, pagination, and partner error envelopes.
• Partner lifecycle/profile/assignment responses use the lifecycle snapshot shape.
• Workspace subresources return safe domain snapshots or validation findings for draft configuration sections.
• Controlled release routes return validation reports, publish outcomes, safe revision diffs, or runtime drift reports.
• Project-secret routes return metadata and reference previews only; plaintext secret values are write-only.
• Legacy billing-focused endpoints use the older project and billing response models and may return the general HTTPException error shape.

#Project Detail

Used by partner/admin project lifecycle endpoints.

#Lifecycle Snapshot

Used by POST /v1/projects, lifecycle/profile routes, archive/restore, and project assignment routes.

#Legacy Project

Used by the legacy project list/detail/update response path.

#GET /v1/projects

Returns projects for the authenticated client.

Authentication: Required (X-API-Key or Authorization: Bearer <jwt>)

For partner_admin, partner_user, aidial_admin, and aidial_operator scopes, the response is paginated and uses the project detail shape. Partner read scopes are assignment-aware. Internal admin/operator scopes list projects for the resolved AuthContext.client_id. For other authenticated legacy scopes, the response is { "projects": [...] } using the legacy project shape.

#Parameters

#Partner/Admin Response

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/projects?page=1&page_size=20" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

Response (200 OK):

{
  "items": [
    {
      "project_id": "client_example_001-Reception_AI-a1b2c3d4",
      "client_id": "client_example_001",
      "display_name": "Reception AI",
      "timezone": "Australia/Brisbane",
      "lifecycle_state": "active",
      "has_draft": true,
      "latest_published_version_number": 2,
      "created_at": "2026-01-15T00:00:00Z",
      "updated_at": "2026-04-01T00:00:00Z",
      "created_by": "apikey:42"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_records": 1,
    "total_pages": 1
  }
}

#POST /v1/projects

Creates a new project lifecycle row for the authenticated client and creates an initial draft containing display_name and timezone.

Authentication: partner_admin scope required

#Headers

#Request Body

#Response

Returns a lifecycle snapshot. The generated project_id is based on managed_client_id, a sanitized display name, and a short random suffix.

#Example

Request:

curl -X POST "https://api.aidial.ai/v1/projects" \
  -H "Authorization: Bearer YOUR_PORTAL_JWT" \
  -H "Idempotency-Key: create-reception-ai-001" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Reception AI", "timezone": "Australia/Brisbane", "managed_client_id": "client_example_001"}'

Response (201 Created):

{
  "project": {
    "project_id": "client_example_001-Reception_AI-a1b2c3d4",
    "client_id": "client_example_001",
    "display_name": "Reception AI",
    "timezone": "Australia/Brisbane",
    "lifecycle_state": "setup",
    "revision_token": "1",
    "latest_published_version": null,
    "draft_status": "draft",
    "publish_status": "not_published"
  },
  "profile": {},
  "permissions": {
    "can_create": true,
    "can_edit": true,
    "can_archive": true,
    "can_restore": false,
    "can_manage_assignments": true,
    "read_only_reason": null
  },
  "assignments": [],
  "updated_at": "2026-04-17T02:00:00Z"
}

#GET /v1/projects/{project_id}

Returns details for a single project.

Authentication: partner_admin, partner_user, aidial_admin, or aidial_operator scope for the project detail response. Client portal scopes receive 404 Not Found from this route.

#Parameters

#Response

Returns a project detail object for partner/admin read scopes. Out-of-scope projects return 404 Not Found.

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/projects/client_example_001-Reception_AI-a1b2c3d4" \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

#GET /v1/projects/{project_id}/lifecycle

Returns the safe lifecycle/profile/assignment snapshot for a project.

Authentication: partner_admin, partner_user, aidial_admin, or aidial_operator scope required

#Response

Returns the lifecycle snapshot shape. Partner-member access is assignment-aware; out-of-scope projects return 404 Not Found.

#PATCH /v1/projects/{project_id}/lifecycle

Updates safe lifecycle/profile metadata using lifecycle revision-token concurrency.

Authentication: partner_admin scope required

#Request Body

At least one mutable field must be provided.

#Response

Returns the updated lifecycle snapshot. A stale lifecycle revision returns 409 Conflict; archived projects are read-only until restored.

#PATCH /v1/projects/{project_id}

Closed legacy partner metadata route. Current code always returns non-enumerating 404 Not Found; use PATCH /v1/projects/{project_id}/lifecycle for lifecycle/profile metadata updates.

Authentication: Required, but no scope can use this route successfully

#Parameters

#Response

Always returns 404 Not Found through the partner error envelope.

#POST /v1/projects/{project_id}/archive

Archives a project by setting lifecycle state to archived and aidial_projects.is_active=false. The operation is idempotent.

Authentication: partner_admin scope required

#Parameters

#Headers

#Request Body

#Response

Returns the updated lifecycle snapshot.

#POST /v1/projects/{project_id}/restore

Restores an archived project by setting lifecycle state back to setup and aidial_projects.is_active=true. The operation is idempotent.

Authentication: partner_admin scope required

#Parameters

#Headers

#Request Body

#Response

Returns the updated lifecycle snapshot.

#POST /v1/projects/{project_id}/assignments

Grants safe project visibility to an eligible partner member.

Authentication: partner_admin scope with partner membership context required

#Headers

#Request Body

#Response

Returns the updated lifecycle snapshot.

#DELETE /v1/projects/{project_id}/assignments/{assignment_id}

Removes a project visibility assignment.

Authentication: partner_admin scope with partner membership context required

#Headers

#Request Body

#Response

Returns the updated lifecycle snapshot.

#Project Workspace Subresources

Several project configuration areas expose safe draft/published snapshots and save validation results under /v1/projects/{project_id}. These routes update the project draft in the configuration revision store and use the same project scoping and anti-enumeration behaviour as the core project routes.

#POST /v1/projects/{project_id}/test-call/request

Records an ops-mediated request for a guided test call on a project. This endpoint only records a request to operations: it does not place a call and returns no transcripts, recordings, audio, caller data, or provider credentials.

Authentication: partner_admin scope required (partner_user and any other scope receive 404 Not Found)

#Parameters

#Request Body

The request body carries only a free-text note. The project, client, and requester are resolved server-side from the authenticated, assignment-gated scope; no other field is read or echoed.

#Response

#POST /v1/projects/{project_id}/dashboard-metadata/publish

Publishes API-managed dashboard analytics metadata for a scoped client project without exposing the generic partner runtime draft/publish surface.

Authentication: bearer client_admin scope required

#Headers

#Request Body

Only the closed analytics subset below is accepted. Unsupported fields are rejected.

At least one supported analytics field is required. The API rejects the request when the latest published runtime version is not already deployed, preserves the latest deployed runtime document, forces display_name and timezone from the project row, validates the merged config, inserts a normal published configuration-revision row, and records it as deployed because this metadata is API-managed and requires no runtime rollout.

#Response

Returns client_id, project_id, revision_id, version_number, deploy_status, source_revision, and a safe dashboard metadata snapshot derived from the committed config. The saved current snapshot refresh is attempted after commit as a best-effort side effect; refresh failure is logged and does not change the response.

#GET /v1/projects/{project_id}/draft

Returns the current draft configuration for a project.

Authentication: partner_admin, aidial_admin, or aidial_operator scope required

#Parameters

#Response Headers

#Response

If the project exists but has no draft, the route returns 404 Not Found with a contextual partner error message.

#PUT /v1/projects/{project_id}/draft

Saves or updates the draft configuration for a project.

Authentication: partner_admin scope required

#Parameters

#Headers

#Request Body

The request body must be a JSON object and must not exceed 1 MB.

Draft saves validate mirrored project metadata fields when present. config_data.display_name, if present, must be a non-empty string no longer than 255 characters. config_data.timezone, if present, must be a valid IANA timezone.

#ETag Behaviour

#Response

Returns the saved draft response and a new ETag response header.

#POST /v1/projects/{project_id}/publish

Publishes the current draft through the controlled release flow. The route requires a current successful validation report, creates a published revision with a deploy_pending publish outcome, deletes the draft, and updates the project's latest published version number.

Authentication: partner_admin scope required

#Parameters

#Headers

#Request Body

#Publish Validation

The draft config_data must be a non-empty JSON object with:

If config_data.agents is present, publish also validates the agent contract before inserting the published revision. Canonical runtime shape is an object keyed by runtime agent name, including agents.main. Portal editor list shape is accepted only when it compiles to the approved runtime contract. During compilation, an explicit portal agent_id: main is treated as the runtime entry agent even when it is not the first list item; otherwise the first portal agent becomes runtime main. mixin_keys are folded into runtime tools, and router route_targets become runtime routes with { to, when }. Portal voice_override_key values must resolve to a full runtime tts object through voice_overrides, voices, or an agent-level tts object. Route and handoff targets are resolved against the original portal agent IDs before this main renaming step. critical and high agent findings block publish and leave the draft intact. medium and low findings do not block publish by themselves and are omitted from the publish error response.

Agent publish validation covers:

Publish also runs blocking checks for raw secret references, transfer routing, provider configuration, LLM policy, plugin configuration, email delivery, SMS policy, identity verification, and outbound compliance where those sections are present in the draft. Identity verification validation expects runtime keys such as caller_lookup.plugin and sms_code.input_modes; editor aliases such as plugin_instance_id and channels are blocking findings. Blocking validation errors are returned in the standard partner validation envelope under error.details.field_errors[]. Findings are partner-safe and must not include raw prompt instructions, bearer tokens, raw secret values, ciphertext, or other secret material.

The publish background task no longer marks a version as runtime deployed by itself. A published revision remains pending until the controlled deployment path records deployment evidence or marks the deployment failed.

#Response

#POST /v1/projects/{project_id}/validate

Validates a draft or published version against active release-governance rules.

Authentication: partner_admin scope required

#Request Body

#Response

Returns a validation report with validation_report_id, status (passed, warning, or failed), is_publish_current, fingerprint, findings, and checked_at_utc.

#POST /v1/projects/{project_id}/rollback

Creates a controlled rollback release by validating and copying a completed published version into a new pending published revision.

Authentication: partner_admin scope required

#Headers

#Request Body

#Response

Returns the same controlled release outcome shape used by POST /v1/projects/{project_id}/publish, with operation set to rollback.

#POST /v1/projects/{project_id}/runtime-provenance

Records internal deploy completion or failure evidence for a controlled release outcome.

Authentication: Bearer aidial_admin only

This is an internal deploy-evidence route, not a partner integration endpoint. It requires an Idempotency-Key header and a RuntimeProvenanceRequest body. deploy_completed evidence must include supported observed revision/version, schema version, contract version, and artifact hash fields; deploy_failed evidence must include failure_code and failure_message.

#GET /v1/projects/{project_id}/versions

Returns paginated published version history for a project, sorted by version number descending.

Authentication: partner_admin, partner_user, aidial_admin, or aidial_operator scope required

#Parameters

#Response

#GET /v1/projects/{project_id}/versions/compare

Returns a safe redacted diff between a draft and/or published project revision.

Authentication: partner_admin, partner_user, aidial_admin, or aidial_operator scope required

#Query Parameters

The diff redacts sensitive values before returning before and after fields.

#GET /v1/projects/{project_id}/runtime-drift

Classifies runtime drift for the active project runtime target.

Authentication: partner_admin, partner_user, aidial_admin, or aidial_operator scope required

#Response

Returns status, expected/observed/pending version numbers where known, summary, recommended_action, checked_at_utc, and optional testing_override_summary.

#GET /v1/projects/{project_id}/versions/{version_number}

Returns full detail for a published project configuration version.

Authentication: partner_admin, partner_user, aidial_admin, or aidial_operator scope required

#Parameters

#Response

Returns the published version response shape with id, project_id, version_number, config_data, validation_status, published_at, display-safe published_by, deploy_status, optional deploy error/timestamp, release outcome status, rollback eligibility, release summary, and optional testing override summary.

#Error Semantics

#Data Scoping

All project metadata, lifecycle, draft, version, and legacy billing configuration responses are scoped to the authenticated client identity. You only see projects belonging to your organisation or assigned tenant scope.

Project paths use the API host's local API metadata store. Calls analytics endpoints use strict (client_id, data_env) routing through the tenant routing map; use the Calls Analytics and Billing pages for routed call and customer billing data. A missing tenant route is server misconfiguration and returns 500 Internal Server Error; a routed host, tunnel, or database outage returns 503 Service Unavailable.

Project responses do not expose raw encrypted fields, ciphertext, wrapped keys, plaintext secret values, or *_encrypted database fields. Version comparison responses redact secret-like fields before returning diffs.

#Related Pages

• Authentication - API key and bearer authentication
• Billing - customer billing overview and invoices
• Calls Analytics - routed call records and analytics
• Error Responses - error format details