Skip to main content

​
Introduction

The Routa REST API provides programmatic access to manage agents, tasks, workspaces, notes, and skills. The API follows RESTful principles and returns JSON responses.

​
Base URLs

Routa has two backend implementations that share the same API contract:
  • Next.js Backend (Web): http://localhost:3000 (dev) or your deployment URL
  • Rust Backend (Desktop): http://localhost:3210
Both backends implement identical endpoints with compatible request/response shapes.

​
API Contract

The single source of truth for all API endpoints is defined in api-contract.yaml using OpenAPI 3.1 specification. Both the Next.js backend (src/app/api/) and Rust backend (crates/routa-server/) must implement all endpoints with compatible request/response shapes.

​
Authentication

Currently, the API does not require authentication for local development. For production deployments, implement authentication according to your security requirements.

​
Request Format

All requests expecting a body should use Content-Type: application/json. 
curl -X POST http://localhost:3000/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Example Task", "objective": "Complete documentation"}'

​
Response Format

All responses are returned as JSON with appropriate HTTP status codes:
  • 200 - Success
  • 201 - Created
  • 400 - Bad Request (validation error)
  • 404 - Not Found
  • 500 - Internal Server Error

​
Success Response

{
  "task": {
    "id": "task-123",
    "title": "Example Task",
    "status": "PENDING",
    "createdAt": "2026-03-03T10:00:00.000Z"
  }
}

​
Error Response

{
  "error": "Validation error: title is required"
}

​
Common Query Parameters

​
workspaceId

Many endpoints accept a workspaceId query parameter to filter results by workspace. Defaults to "default" if not provided. 
curl "http://localhost:3000/api/tasks?workspaceId=my-workspace"

​
status

Filter resources by their status field. 
curl "http://localhost:3000/api/agents?status=ACTIVE"

​
Resource Types

The API manages the following core resources:
  • Health - Service health check
  • Agents - AI agents that execute tasks
  • Tasks - Work units assigned to agents
  • Notes - Collaborative documentation
  • Workspaces - Project containers
  • Skills - Reusable agent capabilities
  • Sessions - ACP session management

​
Rate Limiting

No rate limiting is enforced on local development. For production deployments, implement rate limiting according to your requirements.

​
Pagination

The current API does not implement pagination. All list endpoints return complete result sets. Consider implementing pagination for production use with large datasets.

​
Timestamps

All timestamps are returned in ISO 8601 format (UTC): 
"createdAt": "2026-03-03T10:00:00.000Z"

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us