How do I authenticate to the Plexara REST API?

OIDC with required JWT claims is the primary path. OAuth 2.1 with PKCE and Dynamic Client Registration is supported for new client types. API key management (X-API-Key header) is available for service accounts that cannot do interactive auth. Your IdP provides the identity; Plexara provides the persona resolution.

What is the difference between the REST API and the MCP server?

They expose the same governed surface (assets, collections, knowledge, memory, prompts, personas, audit, tool execution). Choose REST when you need a service-to-service call with a stable contract. Choose MCP when an AI agent needs the same operations through a protocol it already understands. Both share one identity, audit, and persona model.

Are there client SDKs?

The MCP server works with any MCP-compatible client SDK (Anthropic, OpenAI, the open-source MCP libraries in TypeScript and Python). The REST API ships an OpenAPI specification, so generated clients work with the standard openapi-generator tooling for whichever language your service is in.

How are rate limits and quotas handled?

Tool calls and queries are bounded per persona, with hard limits on result size to keep responses inside agent context windows. Customer-specific quotas (concurrent agents, queries per minute, storage) are negotiated as part of the engagement. The audit log records throttling events so capacity tuning is data-driven, not guesswork.

Can we extend Plexara with custom tools?

Yes. Custom tools can be registered through the Portal or via the management API, with persona-scoped visibility. They appear in the agent's tool list like any other Plexara tool, with the same audit and authorization treatment.

Developers

Build on Plexara

Plexara exposes every portal capability as a typed, authenticated, audited REST API. Assets, collections, knowledge capture, memory, personas, prompts, audit, governance, and tool execution. The same endpoints the portal uses are available to your integrations, agents, and pipelines.

Full API Reference Get API Access

Why it Matters

Not an Afterthought API

The Plexara REST API is the canonical surface of the platform. The portal is a SPA that consumes it. Admin tooling, user workflows, and automated pipelines all speak the same HTTP. Whatever the portal can do, your code can do, under the same governance.

Fail-Closed Authentication

Every request is authenticated against your identity provider before any tool or data access occurs. No anonymous mode. No permissive fallback.

Persona-Enforced Authorization

Each call is evaluated against the caller persona. Unauthorized tools, connections, and resources are not just blocked; they are not visible.

Audit on Every Call

Tool calls, queries, and errors flow into structured audit with indexed fields for user, tool, timestamp, status, and latency. Query the same log the platform does.

Typed Schemas, Live Catalog

Every tool exposes a JSON schema. Every endpoint returns typed responses. The catalog is live: new tools appear the moment they are registered.

Authentication

Three Methods, One Identity Model

Every method resolves to the same persona system. Whether a request arrives from a human, a service, or an MCP client, Plexara evaluates it against the same policy graph and writes the same audit record.

API Key

Service accounts, CI pipelines, scheduled jobs.

Minted per service with explicit persona scope, expiration, and rotation. Revocable in one click. Usage is audited.

X-API-Key: <key>

Bearer Token (OIDC)

Interactive human users via your identity provider.

Tokens validated against your upstream IdP with JWKS auto-discovery. Roles map to personas through your existing identity infrastructure.

Authorization: Bearer <id_token>

OAuth 2.1 + PKCE

MCP clients, desktop agents, third-party integrations.

The built-in OAuth 2.1 server bridges MCP clients to your upstream IdP with PKCE, rotating refresh tokens, and bcrypt-hashed client secrets.

Authorization: Bearer <access_token>

Quickstart

Your First Request

List the tools your persona has access to. No SDK required. Any HTTP client works.

List tools (Admin)

curl https://api.plexara.io/api/v1/admin/tools \
  -H "X-API-Key: $PLEXARA_API_KEY" \
  -H "Accept: application/json"

Get current session (Portal)

curl https://api.plexara.io/api/v1/portal/me \
  -H "Authorization: Bearer $PLEXARA_TOKEN" \
  -H "Accept: application/json"

Execute a tool

curl https://api.plexara.io/api/v1/admin/tools/call \
  -X POST \
  -H "X-API-Key: $PLEXARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "trino.query",
    "arguments": { "sql": "SELECT 1" }
  }'

API Surface

Three Namespaces, One Platform

The full API is organized into three top-level namespaces. A representative subset of each is shown below. The complete endpoint catalog with request and response schemas lives in the API reference.

Portal

/api/v1/portal

Practitioner-scoped endpoints. Everything the portal SPA calls on behalf of a signed-in user. Scoped to the caller and their persona.

GET/api/v1/portal/meCurrent session identity and persona.
GET/api/v1/portal/assetsList personal assets.
POST/api/v1/portal/assets/{id}/copyCopy a shared asset.
GET/api/v1/portal/assets/{id}/versionsAsset version history.
GET/api/v1/portal/collectionsList personal collections.
PUT/api/v1/portal/collections/{id}/sectionsReorder collection sections.
POST/api/v1/portal/assets/{id}/sharesShare an asset.
GET/api/v1/portal/shared-with-meAssets shared with me.
GET/api/v1/portal/activity/overviewUser activity metrics.
GET/api/v1/portal/knowledge/insightsInsights captured by me.
GET/api/v1/portal/memory/recordsMy memory records.
GET/api/v1/portal/promptsPersonal and accessible prompts.

Admin

/api/v1/admin

Platform administration. Audit, personas, connections, knowledge governance, memory, configuration, tools catalog, and tool execution.

GET/api/v1/admin/system/infoPlatform identity and features.
GET/api/v1/admin/audit/eventsStructured audit log search.
GET/api/v1/admin/audit/metrics/overviewLatency and success rates.
GET/api/v1/admin/toolsFull tool catalog.
POST/api/v1/admin/tools/callExecute a tool.
GET/api/v1/admin/tools/schemasJSON schemas for all tools.
GET/api/v1/admin/personasPersona definitions.
PUT/api/v1/admin/personas/{name}Update persona policy.
GET/api/v1/admin/connectionsUpstream data-source inventory.
GET/api/v1/admin/knowledge/changesetsPending and applied changesets.
POST/api/v1/admin/knowledge/changesets/{id}/rollbackReverse a changeset.
POST/api/v1/admin/auth/keysMint a service API key.
GET/api/v1/admin/config/changelogPlatform change history.

Resources

/api/v1/resources

MCP resource CRUD. The same resource surface exposed to AI agents, directly accessible for tooling, validation, and automation.

GET/api/v1/resourcesList visible resources.
POST/api/v1/resourcesCreate a resource.
GET/api/v1/resources/{id}Get resource metadata.
GET/api/v1/resources/{id}/contentGet resource content.
PATCH/api/v1/resources/{id}Update resource.
DELETE/api/v1/resources/{id}Delete resource.

Open Full API Reference

Conventions

Predictable by Design

Versioned, stable paths: Every route is rooted at /api/v1. Breaking changes are versioned, never patched in place.
Pagination: List endpoints accept page and per_page query parameters. Responses include total.
Content types: JSON request and response bodies. Binary asset content is returned with the original content type. Errors use application/problem+json.
Idempotency: PUT and DELETE are idempotent. POST creation endpoints accept an Idempotency-Key header when deduplication matters.

Errors

RFC 7807 Problem Details

Errors are never a wall of HTML or a terse string. Every failure returns a structured problem response with a machine-readable type, a human-readable title, an HTTP status, and a detail line that explains what went wrong in the context of this specific call.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "persona 'analyst' does not allow tool 'trino.admin.drop_table'",
  "instance": "/api/v1/admin/tools/call"
}

Common questions

Developer FAQ

: OIDC with required JWT claims is the primary path. OAuth 2.1 with PKCE and Dynamic Client Registration is supported for new client types. API key management (X-API-Key header) is available for service accounts that cannot do interactive auth. Your IdP provides the identity; Plexara provides the persona resolution.
: They expose the same governed surface (assets, collections, knowledge, memory, prompts, personas, audit, tool execution). Choose REST when you need a service-to-service call with a stable contract. Choose MCP when an AI agent needs the same operations through a protocol it already understands. Both share one identity, audit, and persona model.
: The MCP server works with any MCP-compatible client SDK (Anthropic, OpenAI, the open-source MCP libraries in TypeScript and Python). The REST API ships an OpenAPI specification, so generated clients work with the standard openapi-generator tooling for whichever language your service is in.
: Tool calls and queries are bounded per persona, with hard limits on result size to keep responses inside agent context windows. Customer-specific quotas (concurrent agents, queries per minute, storage) are negotiated as part of the engagement. The audit log records throttling events so capacity tuning is data-driven, not guesswork.
: Yes. Custom tools can be registered through the Portal or via the management API, with persona-scoped visibility. They appear in the agent's tool list like any other Plexara tool, with the same audit and authorization treatment.

Reference

Full API Reference

Browse every endpoint, request and response schema, and authentication detail in the complete reference.

Open Reference