Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

REST API Reference

Complete reference for the Archia server REST API endpoints.

📖 Interactive Documentation: View the Swagger/OpenAPI Documentation for an interactive API explorer.

Overview

The Archia server exposes a REST API for managing agents, tools, chats, and system operations. All endpoints are prefixed with /v1/.

Base URL: http://localhost:8080/v1

Authentication: Most endpoints require authentication. Include your credentials in the request headers.

API Sections

SectionDescription
Responses APIRecommended - Generate model responses with streaming and tool support
Supported ModelsList of all supported models and their capabilities
Agents APIManage agent configurations and chat sessions
Tools APIConfigure and manage MCP tools
System APISystem endpoints for health, metrics, and models

Quick Start

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "input": "What is the capital of France?"
  }'

Use an Agent

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent:assistant",
    "input": "Help me analyze this data"
  }'

List Available Agents

curl http://localhost:8080/v1/agent/config

List Available Tools

curl http://localhost:8080/v1/tool

Error Responses

All endpoints return standard error responses:

{
  "error": {
    "code": "not_found",
    "message": "Agent 'unknown' not found"
  }
}

Common HTTP Status Codes:

CodeDescription
200Success
201Created
204No Content (successful delete)
400Bad Request (invalid input)
401Unauthorized
404Not Found
500Internal Server Error

OpenAPI / Swagger Documentation

Interactive API documentation is generated from the source code using OpenAPI/Swagger.

View Interactive API Documentation (Redoc) →

To generate the documentation locally:

# Generate OpenAPI spec and HTML docs
cargo run --package manage -- document server

This generates:

  • target/doc/archiad.json - OpenAPI specification (machine-readable)
  • target/doc/archiad.html - Redoc HTML documentation (interactive)

You can also get just the OpenAPI JSON:

cargo run --package archiad -- document > archiad.json

Next Steps