HTTP API

AppPlugin is the shared axum runtime for Polaris HTTP products. It binds a listener, merges route fragments, and applies middleware such as CORS, request IDs, and tracing.

Import the HTTP runtime through polaris_ai::app and enable the sessions-http feature. There is no separate app-crate dependency needed.

Session endpoints come from polaris_ai::sessions::HttpPlugin. In practice:

• AppPlugin starts the server and owns the shared HttpRouter
• HttpPlugin adds /v1/sessions/... routes backed by SessionsAPI
• your own plugins can add extra routes such as /healthz or /v1/info

How it fits together

Add AppPlugin to provide the HTTP runtime, then layer SessionsPlugin and HttpPlugin on top.

[dependencies]
polaris-ai = { git = "https://github.com/RadiantAILabs/polaris", rev = "5ff84646db63589d58bf87956976d749b8c754de", features = ["sessions-http", "anthropic"] }

use polaris_ai::app::{AppConfig, AppPlugin};
use polaris_ai::plugins::PersistencePlugin;
use polaris_ai::models::AnthropicPlugin;
use polaris_ai::models::ModelsPlugin;
use polaris_ai::sessions::HttpPlugin;
use polaris_ai::sessions::{InMemoryStore, SessionsPlugin};
use polaris_ai::system::server::Server;
use polaris_ai::tools::ToolsPlugin;
use std::sync::Arc;

let mut server = Server::new();
server
    .add_plugins(ModelsPlugin)
    .add_plugins(AnthropicPlugin::from_env("ANTHROPIC_API_KEY"))
    .add_plugins(ToolsPlugin)
    .add_plugins(PersistencePlugin)
    .add_plugins(SessionsPlugin::new(Arc::new(InMemoryStore::new())))
    .add_plugins(
        AppPlugin::new(
            AppConfig::new()
                .with_host("0.0.0.0")
                .with_port(3000),
        ),
    )
    .add_plugins(HttpPlugin::new());

This assembles the runtime; it does not register an agent. Register your Agent implementation through SessionsAPI from a plugin during startup, then await server.run(). For a runnable server, start from the public HTTP example rather than sending requests to an empty agent registry.

Configuration

AppPlugin accepts an AppConfig.

use polaris_ai::app::AppConfig;

let config = AppConfig::new()
    .with_host("0.0.0.0")
    .with_port(3000)
    .with_cors_origin("http://localhost:5173");

The server starts during ready(), after all plugins have registered their routes.

Session endpoints

HttpPlugin exposes these routes:

Method	Path	Description
POST	/v1/sessions	Create a live session
GET	/v1/sessions	List live sessions
GET	/v1/sessions/stored	List persisted sessions
GET	/v1/sessions/agent-types	List registered agent names
GET	/v1/sessions/agent-types/details	Auth-protected graph signatures and contracts
POST	/v1/sessions/{id}/turns/stream	Process a turn with SSE
GET	/v1/sessions/{id}/turns	List recorded turn summaries
GET	/v1/sessions/{id}/turns/{n}	Inspect one turn
GET	/v1/sessions/{id}/uptime	Read bucketed lifecycle history
GET	/v1/sessions/{id}	Get session metadata
DELETE	/v1/sessions/{id}	Delete a session
POST	/v1/sessions/{id}/turns	Process one turn
POST	/v1/sessions/{id}/checkpoints	Create a checkpoint
GET	/v1/sessions/{id}/checkpoints	List checkpoints
POST	/v1/sessions/{id}/rollback	Roll back to a checkpoint
POST	/v1/sessions/{id}/save	Persist a session
POST	/v1/sessions/{id}/resume	Resume a persisted session

Create a session

POST /v1/sessions

Creates a new session for a registered agent type.

Request body:

{
  "agent_type": "react_agent"
}

Response (201 Created):

{
  "session_id": "user-123-conversation-1",
  "agent_type": "react_agent",
  "turn_number": 0,
  "created_at": "2026-04-08T10:12:34Z",
  "status": "active"
}

session_id is optional. If you omit it, Polaris generates one for you.

The agent_type must match an agent already registered with SessionsAPI.

Process a turn

POST /v1/sessions/{session_id}/turns

Sends one user message to the agent and returns the result of one turn.

Request body:

{
  "message": "What files are in the current directory?"
}

Response (200 OK):

{
  "messages": [
    {
      "type": "assistant_text",
      "text": "Here are the files in the current directory: ..."
    }
  ],
  "execution": {
    "nodes_executed": 5,
    "duration_ms": 1230,
    "turn_number": 1
  }
}

The handler bridges the HTTP request into agent IO with HttpIOProvider, executes one turn, then returns the emitted messages plus execution metadata.

List sessions

GET /v1/sessions

Returns metadata for live in-memory sessions.

Response (200 OK):

{
  "sessions": [
    {
      "session_id": "user-123-conversation-1",
      "agent_type": "react_agent",
      "turn_number": 1,
      "created_at": "2026-04-08T10:12:34Z",
      "status": "active"
    }
  ]
}

Get session info

GET /v1/sessions/{session_id}

Returns metadata about a specific session.

Delete a session

DELETE /v1/sessions/{session_id}

Removes the session from memory and deletes it from the backing store if one is configured.

Response (204 No Content)

Checkpoints, rollback, save, and resume

POST /v1/sessions/{session_id}/checkpoints
GET  /v1/sessions/{session_id}/checkpoints
POST /v1/sessions/{session_id}/rollback
POST /v1/sessions/{session_id}/save
POST /v1/sessions/{session_id}/resume

These routes map directly to the checkpointing and persistence methods on SessionsAPI.

Rollback a session

POST /v1/sessions/{session_id}/rollback

Request body:

{
  "turn_number": 2
}

Response (200 OK):

{
  "session_id": "user-123-conversation-1",
  "agent_type": "react_agent",
  "turn_number": 2
}

The target turn must correspond to an existing checkpoint.

Custom routes

If you want to add routes beyond the session API, register them through HttpRouter in another plugin:

use axum::{Router, routing::get};
use polaris_ai::app::{AppPlugin, HttpRouter};
use polaris_ai::system::plugin::{Plugin, PluginId, Version};
use polaris_ai::system::server::Server;

struct HealthPlugin;

impl Plugin for HealthPlugin {
    const ID: &'static str = "example::health";
    const VERSION: Version = Version::new(0, 0, 1);

    fn build(&self, server: &mut Server) {
        server
            .api::<HttpRouter>()
            .expect("AppPlugin must be added first")
            .add_routes(Router::new().route("/healthz", get(|| async { "ok" })));
    }

    fn dependencies(&self) -> Vec<PluginId> {
        vec![PluginId::of::<AppPlugin>()]
    }
}

Error responses

When a request fails, the response uses a standard error format.

{
  "error": "session_not_found",
  "message": "no session with ID 'nonexistent'"
}

HTTP status codes map to error types: 404 for missing sessions or agents, 400 for invalid request bodies, and 500 for execution failures.

Authentication and embedding

Configure an AuthProvider when your deployment requires authenticated requests. Protected agent-signature metadata is mounted only when authentication is configured. The standalone sessions_router helper carries no authentication or shared app middleware; an embedding application must apply those itself.