Skip to main content
This page provides a quick, actionable path to authenticate, call REST endpoints, and capture streaming events from the middleware.

​
API Structure

The Praxis AI API is organized into three functional areas:

Authenticate

Sign in or authenticate to retrieve an access token.

Runtime

Endpoints for selecting a Digital Twin, creating conversations, developing assistants, and dialoguing with AI models.

Administration

Configure Digital Twins, set up permissions and entitlements, audit user history, and monitor activity.

​
Getting Started

1

Obtain an authorization token

All API requests require an authorization token issued after successful authentication. See the Authentication API for how to sign in and use the token in requests.
For automation, Admins can use a persistent API key. Interactive sign-in returns a short-lived session token that expires after a few hours — fine for a user session, awkward for a script. Instead, an Admin can create a long-lived API key (format pria_…) from their profile’s API Key settings, store it as a secret, and exchange it for a fresh session token whenever needed:
Use the returned token as the x-access-token header on subsequent requests. The API key itself never expires (rotate or revoke it from the same settings panel), so automation can re-mint a session token on demand without storing user credentials.
API keys are available to Admin accounts and are scoped to that admin’s permissions — the key stops working if the account is deactivated or loses admin access.
2

Know your Base URLs

3

Make a test request

Use your token and send a simple request to verify connectivity and headers. This endpoint returns the authenticated user’s profile:

​
Using the API

The Praxis API follows standard RESTful conventions:
  • JSON for all requests and responses
  • HTTP status codes communicate success/failure
  • Error responses return a consistent JSON shape with details
  • Rate limits protect service stability
If you’re building a browser client, ensure you include the correct auth header on every request. Session tokens are short-lived (they expire after a few hours), so be prepared to re-authenticate — or exchange an API key for a fresh token — when a request returns 401.

​
Automating with the Live API Definition

Both APIs publish a live OpenAPI 3 (Swagger) definition that always reflects the currently deployed endpoints, schemas, parameters, and auth schemes. These are the exact specs that power this API Reference — fetching them programmatically gives you a machine-readable contract you can hand to code generators, AI coding agents, and orchestration platforms.
Because these URLs serve the live definition, anything you generate from them stays aligned with the deployed API — re-fetch after a Praxis AI release to pick up new endpoints and fields automatically.

​
Why use the live definition

  • Always current — no hand-maintained endpoint lists to drift out of date.
  • Machine-readable — standard OpenAPI 3 JSON that virtually every tool and agent understands.
  • Self-describing — request/response schemas, required parameters, and auth schemes are all encoded, so tools can scaffold correct calls without guesswork.

​
Use it with AI coding agents (Claude, Claude Code)

AI coding assistants such as Claude and Claude Code can consume the OpenAPI definition directly to scaffold typed clients, write request code, or build an MCP server that exposes Pria endpoints as tools.
1

Fetch the definition

Download the spec so the agent can read it locally:
2

Point the agent at it

Give the agent the file (or the live URL) and describe what you want. For example:
“Using pria-runtime-openapi.json, generate a typed TypeScript client for the Q&A and conversation endpoints, with x-access-token auth wired in.”
“From this OpenAPI spec, build an MCP server that exposes the Runtime API as tools so I can call Pria from my agent.”
3

Wire in authentication

The spec describes the auth scheme, but the agent still needs a valid token. Supply one from the Authentication API and have the agent attach it as the x-access-token header.
For Claude tool use / function calling, transform each OpenAPI operation into a tool definition so the model can invoke Pria endpoints directly. Most agent frameworks (and Claude Code) can do this automatically from an OpenAPI file or URL.

​
Import into orchestration platforms

Low-code/iPaaS tools, API clients, and agent frameworks accept an OpenAPI URL or file to auto-generate connectors — no manual endpoint mapping required:
The OpenAPI definition describes every endpoint, but access is still governed by your token’s permissions and entitlements. Administrator API operations require admin credentials — generating a client does not grant access you don’t already hold.

​
Streaming responses

Praxis AI can stream model output token-by-token. Two mechanisms are available: HTTP Server-Sent Events (SSE) — the recommended, stateless approach for most integrations — and Socket.IO for persistent, bidirectional real-time connections. Start with SSE unless you specifically need a live socket.

Streaming Responses (SSE & Socket.IO)

Full streaming guide — SSE endpoint, headers, request/response formats, Node.js and Fetch examples, cancellation, and the Socket.IO client flow.

​
API vs SDK

While the API provides direct access to all capabilities, the TypeScript/JavaScript SDK simplifies most tasks.

API Benefits

• Direct access to all Praxis features
• Language-agnostic integration
• Fine-grained request/response control
• Ideal for custom platforms or gateways, mobile applications

SDK Benefits

• Higher-level abstractions
• Seamless SSO authentication
• Ready-to-use UI
• Supports LMS platforms such as Canvas, Moodle, and D2L via LTI
For most use cases, we recommend using our SDKs, while the API remains available for mobile applications, low-level or platform-neutral integrations.

​
Error Handling

The API uses standard HTTP status codes:
  • 2xx: Success
  • 4xx: Client error (invalid request, missing parameters, unauthorized)
  • 5xx: Server error
When an error occurs, the JSON body includes details to help diagnose and resolve issues.

​
Next Steps

Explore endpoint-specific docs:

Authentication

How to authenticate requests and attach tokens.

AI Q&A

Send conversation requests and receive streaming responses.

SSE Streaming

Stream AI responses over HTTP using Server-Sent Events.