Praesidia is built API-first: every action the dashboard takes is an API call to the same surface your team can call directly. That means anything you can do in the UI — register an agent, enforce a budget policy, export audit logs — you can automate, script, or integrate from your own tooling. The API is described by a versioned OpenAPI specification that serves as the authoritative contract between the platform and any consumer.

What API-First Actually Means in Practice

Many platforms claim "API-first" but ship a UI that calls internal undocumented endpoints. Praesidia takes a stricter interpretation: the dashboard, the generated client libraries, and any third-party integration all consume the same published, OpenAPI-described REST surface. There is no privileged internal path.

This has a practical consequence for your team. When you automate a workflow, you are not reverse-engineering hidden behavior — you are calling the same endpoints the product team uses and tests. If the UI can do it, the API can do it. The inverse is also true: if a capability exists in the API, the dashboard exposes it.

The OpenAPI Specification as Contract

Every endpoint in Praesidia is described by a Swagger/OpenAPI document. That document is the contract. It describes request and response shapes, required authentication headers, path parameters, and error codes. Generated client libraries — for the dashboard's own frontend and for any consumer you build — are regenerated from this spec whenever the API changes.

This generation discipline has a concrete benefit: type drift is caught early rather than at runtime. When the API changes, client libraries regenerate and any consumer that depends on the old shape fails at build time rather than silently in production.

For operators integrating Praesidia into their own tooling, the OpenAPI spec is the starting point. Import it into Postman, generate a client in your language of choice, or use it to validate your own automation scripts against the expected contract. The spec is available from the platform developer documentation.

How the API Is Organized

The API surface is organized around organizations. Almost every resource is scoped to an organization: an agent, a workflow, or an audit log always belongs to the organization that owns it, and access is evaluated against that boundary on every request. This reflects the multi-tenant design of the platform — a token issued to your organization can only read and write resources belonging to that organization.

A small number of routes sit outside the org scope: authentication endpoints and a limited set of intentionally public surfaces. Everything else is tenant-scoped by construction, not by convention.

Within the org scope, the surface is grouped by capability domain. Agent management endpoints cover registration, configuration, and versioning. Workflow endpoints cover canvas CRUD, run execution, and trigger management. Identity endpoints cover users, teams, roles, and SCIM provisioning. Billing endpoints cover subscriptions, credits, and invoices. Compliance endpoints cover audit logs, GDPR erasure, and EU AI Act reporting.

Each domain uses consistent naming patterns: GET /…/:id to fetch a single resource, GET /… with query parameters to list and filter, POST /… to create, PATCH /…/:id to update, DELETE /…/:id to remove. Pagination follows a consistent cursor or offset pattern across all list endpoints.

Authentication for API Consumers

The API supports two credential types for programmatic access. Bearer tokens issued by the OAuth flow work for short-lived automation and are suitable when you are acting on behalf of a user session. API keys issued from the organization settings are better suited for long-running automation, CI pipelines, and server-to-server integrations because they do not expire on the session lifecycle.

Both credential types are scoped. An API key can be created with a subset of permissions — read-only access to analytics, or write access limited to workflows — so you can issue credentials that match the principle of least privilege without sharing your full-admin credentials. See Organization API Keys and Scopes for a deeper look at scoping and rotation.

All requests require the credential in the Authorization: Bearer header. The API returns standard HTTP status codes: 401 for unauthenticated requests, 403 for requests that are authenticated but lack the required permission, and 404 when a resource does not exist within the caller's organization scope (as opposed to leaking that it exists somewhere else).

Using the API for Automation

The practical uses for direct API access fall into a few patterns.

CI/CD integration. Teams that manage agents as code can register or update agents from a deployment pipeline using API calls keyed to a scoped API key. A workflow promotion from staging to production becomes a single API call in your deployment script, not a manual click.

Data export and reporting. The audit log, analytics, and cost monitoring endpoints let you pull structured data into your own data warehouse, SIEM, or reporting tool on a schedule. Audit entries returned by the API carry the same cryptographic integrity metadata as the in-platform view, so you are exporting genuine records, not a summary.

Custom dashboards. Operators who want to embed agent status or spend data into an internal portal can call the dashboard and analytics endpoints directly. The response shapes are stable and documented, so your custom view does not break silently when platform internals change.

Governance automation. Budget policies, guardrail rules, and security settings are all writable through the API. Teams that manage these through infrastructure-as-code tooling can treat Praesidia configuration as a resource that is versioned, reviewed, and deployed alongside the rest of their stack. For the guardrail design decisions that inform those configurations, see Designing Guardrails: Block, Redact, or Warn?.

The Generated Client Libraries

For teams building tighter integrations in TypeScript or JavaScript, Praesidia's own dashboard uses a generated client built directly from the OpenAPI spec. The same spec can generate clients in any language OpenAPI Generator supports. Because the client is generated from the source-of-truth spec rather than hand-written, it stays in sync with the API without manual maintenance.

The generation approach also gives you accurate request and response types. You do not need to hand-annotate API calls with TypeScript interfaces that may drift from reality — the generated client carries the types the backend declares, keeping your integration honest.

Common questions

Does the API version its endpoints? Praesidia uses path-level versioning for breaking changes: the current surface is served under a versioned path. When a breaking change is necessary, a new version is introduced and the previous one is maintained for a deprecation window, so existing integrations have time to migrate rather than breaking silently.

Can I access the OpenAPI spec programmatically? Yes. The spec is served from the platform at runtime and can be fetched as JSON for use in tooling, client generation, or contract testing. The address is documented in the platform developer documentation.

What rate limits apply to API calls? API calls are subject to the same per-organization rate limits as UI-driven requests. Limits are returned in response headers so your client can back off cleanly rather than retrying into a wall. High-volume integrations that need elevated limits can configure this through the organization settings or contact support. For the broader picture of how rate limiting works across the platform, see How to Rate-Limit AI Agents.

How does the API enforce tenant isolation? Every protected endpoint includes the organization identifier in the path. A credential issued to one organization cannot read or write resources belonging to another — the isolation is enforced structurally, so your automation scripts cannot accidentally cross tenant boundaries even if a bug passes the wrong identifier.