palyrad) exposes a multi-surface HTTP API designed for administrative control, operator interaction via the Web Console, and third-party LLM client compatibility. These interfaces provide RESTful access to the core engine’s state, including session management, policy evaluation, and tool execution.
API Surfaces Overview
The daemon segments its HTTP routes into three primary namespaces, each with distinct authentication and authorization requirements:- Admin API (
/admin/v1/*): Low-level diagnostic and security management. Requires a staticadmin_token(Bearer auth) crates/palyra-daemon/tests/admin_surface.rs#48-60. - Console API (
/console/v1/*): Powering the React-based Web Console. Uses session-based authentication (cookies) and CSRF protection for mutating requests apps/web/src/consoleApi.test.ts#44-90. - Compatibility API (
/v1/*): Provides an OpenAI-compatible interface for existing tools and SDKs crates/palyra-daemon/src/transport/http/handlers/compat.rs#128-132.
Request Context and Security
Every request to the Admin or Console surfaces must include context headers that define the “Principal” (who is acting) and the “Device” (where the action originates).| Header | Description | Example |
|---|---|---|
x-palyra-principal | The identity string of the caller. | admin:web-console |
x-palyra-device-id | A unique identifier for the calling device. | 01ARZ3NDEKTSV4RRFFQ69G5FAV |
x-palyra-channel | The communication medium (cli, web, discord). | web |
x-palyra-csrf-token | Required for all POST/PUT/DELETE in Console API. | (Secure Hash) |
Admin API (/admin/v1/*)
The Admin API is used for system-level introspection and security auditing. It is primarily consumed by the palyra CLI.
Key Endpoints
- GET
/admin/v1/status: Returns the health of the daemon, including gRPC ports and whether admin auth is enabled crates/palyra-daemon/tests/admin_surface.rs#40-70. - GET
/admin/v1/journal/recent: Retrieves a snapshot of the most recent events from the SQLite-backedJournalStorecrates/palyra-daemon/tests/admin_surface.rs#84-106. - GET
/admin/v1/policy/explain: Interrogates the Cedar-based policy engine to explain why a specific action (e.g.,tool.execute.shell) was allowed or denied crates/palyra-daemon/tests/admin_surface.rs#119-148.
Admin Request Flow
Title: Admin Request Validation Flow Sources: crates/palyra-daemon/tests/admin_surface.rs#30-72, crates/palyra-daemon/src/app/runtime.rs#62-63Console API (/console/v1/*)
The Console API supports the Web Console (apps/web). It manages complex state transitions for agents, routines (cron jobs), and chat sessions.
Authentication & Session Lifecycle
TheConsoleApiClient in the frontend manages a multi-step bootstrap process:
- Login:
POST /console/v1/auth/loginexchanges an admin token or handoff token for aConsoleSessioncrates/palyra-daemon/src/transport/http/handlers/console/auth.rs#19-111. - Session Cookie: The daemon sets a
SET-COOKIEheader with a secure session token crates/palyra-daemon/src/transport/http/handlers/console/auth.rs#104-106. - CSRF Protection: The
ConsoleSessionobject contains acsrf_tokenwhich must be sent in thex-palyra-csrf-tokenheader for all mutating requests apps/web/src/consoleApi.test.ts#44-53.
Routine Management (/console/v1/routines)
Routines are managed via the RoutineRegistry and CronService.
- GET
/console/v1/routines: Lists all configured routines with filters fortrigger_kindandenabledstatus crates/palyra-daemon/src/transport/http/handlers/console/routines.rs#154-215. - POST
/console/v1/routines/import: Imports aRoutineExportBundlecrates/palyra-daemon/src/transport/http/handlers/console/routines.rs#146-152. - POST
/console/v1/routines/{id}/dispatch: Manually triggers a routine execution apps/web/src/consoleApi.test.ts#145-153.
Agent & Workspace Management
- GET
/console/v1/agents: Returns a list of available agents defined inpalyra.tomlcrates/palyra-control-plane/src/models.rs#193-200. - POST
/console/v1/agents/create: Creates a new agent record with specificworkspace_rootsandtool_allowlistcrates/palyra-control-plane/src/models.rs#210-226.
Compatibility API (/v1/*)
Palyra provides a compatibility layer for tools expecting an OpenAI-style API. This allows Palyra to act as a drop-in replacement for local model orchestration.
- GET
/v1/models: Lists available model profiles configured in the daemon crates/palyra-daemon/src/transport/http/handlers/compat.rs#105-126. - POST
/v1/chat/completions: Routes a chat request through theGatewayService. Supports both standard and streaming responses crates/palyra-daemon/src/transport/http/handlers/compat.rs#128-175.
API Token Security
Unlike the Console API, the Compatibility API usesApiTokenRecord managed by the AccessRegistry. Tokens can be scoped to specific permissions like compat.chat.create crates/palyra-daemon/src/access_control.rs#24-26.
Title: Compatibility API Request Processing
Sources: crates/palyra-daemon/src/transport/http/handlers/compat.rs#128-149, crates/palyra-daemon/src/access_control.rs#151-173
Data Structures
Console Session
TheConsoleSession represents an active operator session in the Web Console.
| Field | Type | Description |
|---|---|---|
principal | String | The authenticated principal (e.g., admin:web-console). |
csrf_token | String | Token used to prevent Cross-Site Request Forgery. |
issued_at_unix_ms | i64 | Timestamp of session creation. |
expires_at_unix_ms | i64 | Timestamp of session expiration. |
Deployment Posture
The/admin/v1/status endpoint returns a DeploymentPostureSummary, providing a snapshot of the daemon’s security configuration.
| Field | Type | Description |
|---|---|---|
mode | String | Deployment mode (e.g., standalone, cluster). |
admin_auth_required | bool | Whether the /admin surface requires a token. |
tls | TlsSummary | Status of Gateway TLS. |
remote_bind_detected | bool | Security warning if binding to non-loopback without auth. |
Rate Limiting
The daemon implements per-IP and per-token rate limiting to prevent brute-force attacks and resource exhaustion.- Admin Rate Limiting: Tracked in
AppState.admin_rate_limitviaAdminRateLimitEntrycrates/palyra-daemon/src/app/runtime.rs#62. - Compatibility API Rate Limiting: Enforced via
enforce_compat_rate_limitusing therate_limit_per_minutedefined in theApiTokenRecordcrates/palyra-daemon/src/transport/http/handlers/compat.rs#111.