REST API reference

Open the live OpenAPI reference, authenticate requests, and use the generated schema as the source of truth for endpoints and payloads.

Noveum publishes an interactive reference generated from the running API:

The schema includes the current /api/v1 routes for traces, projects, datasets, scorers, ETL jobs, eval jobs, NovaPilot, NovaSynth, providers, roles, usage, and related workflows. Prefer it over copied request shapes because route schemas evolve with the product.

Authenticate

Create an API key under Organization Settings → API Keys, then send it as a Bearer token:

Code

curl https://noveum.ai/api/v1/status \
  --header "Authorization: Bearer $NOVEUM_API_KEY"

API keys are bound to one organization. A key with an assigned role receives that role's permissions; a role-less key inherits the creating user's current organization permissions. See Roles and permissions before using a key in CI or another shared system.

OAuth access tokens issued by Noveum also use the Bearer header. Their noveum.read, noveum.write, and noveum.execute scopes narrow access further, while the user's organization role still applies. See MCP OAuth connector mode for the authorization model.

Treat API keys like passwords. Store them in a secrets manager or environment variable, never in source control, screenshots, logs, client-side code, or documentation examples.

Organization and project identifiers

The authenticated credential determines the organization. Routes may additionally require an organization slug, project ID, dataset slug, job ID, or run ID. Retrieve identifiers from list endpoints rather than constructing them from display names.

Project IDs are not always UUIDs - the seeded demo project, for example, uses demo. Dataset display names and slugs are also distinct.

Responses, errors, and pagination

Response and error shapes are documented per endpoint in the live reference. Common failures include:

Status	Meaning
`400`	Request validation failed or the operation is incompatible with current state.
`401`	Bearer token is missing, invalid, or expired.
`403`	The credential is valid but lacks the required role permission or OAuth scope.
`404`	The resource is absent or not visible in the authenticated organization.
`409`	The requested state conflicts with an existing resource or active operation.
`429`	A plan, credit, rate, or concurrency limit was reached.

List endpoints use their documented limit, offset, cursor, filter, or date parameters; there is no single pagination shape shared by every route. Follow the OpenAPI definition for the endpoint you call.

Asynchronous operations

ETL, evaluation, scorer recommendation, NovaPilot, NovaSynth generation, synthetic runs, and report generation can return before background work finishes. Keep the returned job or run ID and poll its status route until a documented terminal state. Do not treat the kickoff response as completion.

The MCP server exposes the allowed, non-sensitive subset of live OpenAPI actions as agent tools and adds workflow resources and prompts for polling-heavy operations. Authentication, credential-management, webhook, and other sensitive routes can be intentionally omitted from MCP even when they appear in the REST schema.