Studio Backend

REST API

The backend’s REST API is the Studio’s API. It is not a supported public interface: external integrations talk to the engine’s API, and customers who want to operate the platform programmatically use the hosted MCP server (Hosted MCP Server and Claude Plugin). This page describes the conventions and gives a map of the endpoints; the OpenAPI description has the details.

Base Path

Every endpoint is under /api/v1 on the environment’s host, for example https://eu.promethist.ai/api/v1/project/{projectId}. The exceptions are listed in Endpoints Outside /api/v1. Locally the backend serves http://localhost:9310.

OpenAPI

springdoc generates an OpenAPI 3.1 description ("PromethistAI Platform API") from the controllers, several of which carry @Operation, @Tag and @ApiResponses annotations. The definition in PlatformApplication declares the bearer security scheme, and OpenApiConfig describes the Ref value type as a plain string.

Path Content

/api/v1/api-docs

The OpenAPI document (JSON).

/api/v1/swagger-ui

Swagger UI (redirects to /api/v1/swagger-ui/index.html).

Both are served by a locally running backend (http://localhost:9310/api/v1/swagger-ui). The deployed environments do not serve them — the preview environment answers 404 on both paths — so browse or export the description from a local backend, and pick its Local Development server (http://localhost:9310) in Swagger UI before trying a request.

Requests and Responses

Authentication

A Keycloak access token as Authorization: Bearer <token>; see Authentication and Authorization. Which role an endpoint needs is stated by its @PreAuthorize annotation, and the table below lists the typical one.

Identifiers

Entities are addressed by UUIDs. Assets inside a project (knowledge, integrations, interactive content, content navigation, skills) are addressed by their ref, a slug unique within the project. Agents are addressed by the id of a revision; the revision list is addressed by the agent’s ref.

JSON

The WebFlux codecs use the Jackson 3 JsonMapper from promethist-common, which carries the custom serializers of Ref, Locale and time values, so the API speaks the same JSON as the shared model.

Errors

ExceptionResolver maps BadRequestException and IllegalArgumentException to 400, NotFoundException to 404 and timeouts to 408, with a body of the form {"status": "404 NOT_FOUND", "message": "Project with id ... not found"}. Bean-validation failures of @Valid bodies answer 400, ResponseStatusException keeps its own status, and authorization failures answer 401 (with WWW-Authenticate: Bearer) or 403, both with an empty body. Permission checks that load the entity they guard can answer 404 before they answer 401 or 403.

Replacing writes

Several update endpoints replace the whole stored object with the request — the project PATCH, the integration, interactive-content and connector PUT`s, the skill and template `PUT`s. A client that changes one field has to read the object first and send everything back. An agent `PUT likewise takes the complete agent and saves it as a new draft revision.

Long-running writes

Knowledge ingestion reports its progress as a stream of ProgressInformation elements (stage and fraction) and ends with a Finished or Failed element; a failure is reported in the stream, not as an HTTP status. Creating a knowledge file is the exception: it answers with the new source’s ref once processing has finished, and with 422 when the document could not be parsed.

Uploads

Logos, the images and videos of interactive content and knowledge files are uploaded as multipart/form-data. A video upload answers with the element serving the file as uploaded; its re-encoded copy replaces it in the element’s url later (Re-encoding of Uploaded Videos).

Endpoint Map

Controller Paths Purpose and typical guard

TenantRestController

/tenants, /tenant/{tenantId}, /tenant/{tenantId}/context, /tenant/logo, /tenant/{tenantId}/settings/...

Accounts: list (own), create (any signed-in user), read (Viewer), edit (Editor), logo upload, the caller’s role (context), and the privacy settings (read Viewer, change Owner).

ProjectRestController

/tenant/{tenantId}/projects, /project/{projectId}, .../context, .../users, .../integrations/..., .../multimodal-interactions/..., .../navigations/..., .../identity-providers, .../terms, .../skills, /project/logo, /project/multimodality-image, /project/multimodality-video, /realtime-configurations, /integration/mcp/load-tools, /user/identity-provider

Projects, their terms and conditions and the assets embedded in them: read Viewer, write Editor, identity providers Owner. Also the voice catalog with previews, the live probe of an MCP server’s tools, and the identity provider the caller signed in with (for the login page).

AgentRestController

/project/{projectId}/agents[/latest|/published|/revisions], /agents/{id}, /agents/{ref}/revisions, /agents/{id}/{clone|preview|publish|revert|archive|archive-all}, /agents/{id}/visuals, /templates

Agents and their lifecycle (Editor for writes), the published template catalog.

EvaluationRestController

/project/{projectId}/evaluations[/{id}[/clone|/revisions|/preview|/publish|/revert]]

Evaluations with their output data elements and groups, and their revision lifecycle (Editor for writes).

KnowledgeController

/project/{projectId}/knowledgeSpecification(s)/..., /project/{projectId}/knowledge/{ref}

Knowledge sources: file and URL ingestion, metadata, stored chunks.

FeedbackSurveyRestController

/project/{projectId}/feedback-surveys/...

Feedback surveys the engine serves to end users.

TestSuiteRestController

/project/{projectId}/test-suites/...

Test suites, runs, results and their export as xlsx, csv or json (Test Suites).

SessionController

/project/{projectId}/sessions/query, /project/{projectId}/sessions/{sessionId}[/evaluations]

Conversation list, transcripts and a conversation’s evaluation results (Viewer, subject to the full-conversation-data setting).

AnalyticsRestController, AnalyticsExportController

/project/{projectId}/analytics/...

The analytics suite and its exports (Viewer), see Analytics Suite.

BillingRestController

/tenant/{tenantId}/{subscription|invoices|usage}, /project/{projectId}/subscription, /agent/{agentId}/subscription, /tenant/{tenantId}/billing/{checkout-session|portal-session}

Subscription, invoices and usage (Viewer); checkout and customer-portal sessions (Owner).

UserRestController, InvitationRestController

/{tenant|project}/{id}/members/..., /project/{projectId}/external-access, /{tenant|project}/{id}/invitations/..., /invitations/{id}[/accept|/decline]

Members, external access grants and invitations (Owner; listing invitations Editor). Accepting or declining an invitation needs only a signed-in user whose email matches.

SecretRestController

/{tenant|project}/{id}/secrets/live-avatar-api-key[/configured]

The LiveAvatar API key of an account or a project.

VisualRestController

/visual/agent/{agentRef}, /visual/live-avatar/{avatarId}

Agent thumbnails and live-avatar previews.

TranscriptionRestController

/assistant/transcribe

Speech-to-text of the AI Assistant’s voice input.

TemplateAdminRestController, SkillAdminRestController, RealtimeConfigurationAdminRestController

/admin/templates/..., /admin/skills/..., /admin/projects/{projectId}/skills/..., /admin/realtime-configurations/...

Staff-only administration of templates, skills and their project assignments, and voices.

ExportRestController, UploadRestController

/exports/{id}?token=..., /uploads/{id}?token=...

Capability links for downloads and uploads created through the MCP server (Capability URLs).

The MCP endpoint /api/v1/mcp is described in Hosted MCP Server and Claude Plugin.

Endpoints Outside /api/v1

Path Purpose

POST /api/stripe/callback

Stripe webhook (subscription created, updated, deleted), see Usage and Billing.

GET /api/vault/{name}

Staff-only read of the configured vault.

/actuator/health, /actuator/metrics

Spring Boot Actuator, see Observability.