# Routa API Contract and Endpoint Inventory: Complete OpenAPI 3.1 Reference

> Explore the Routa API contract and endpoint inventory. This OpenAPI 3.1 reference details REST endpoints for agents, tasks, workspaces, skills, and Git operations used by the Next.js front-end and Rust back-end.

- Repository: [Fengda Huang/routa](https://github.com/phodal/routa)
- Tags: api-reference
- Published: 2026-05-26

---

**The Routa API contract is defined in a single OpenAPI 3.1 document ([`api-contract.yaml`](https://github.com/phodal/routa/blob/main/api-contract.yaml)) that serves as the source of truth for both the Next.js front-end and Rust desktop back-end, exposing REST endpoints for agents, tasks, workspaces, skills, and Git operations across two server environments.**

Routa.js implements a dual-backend architecture where a unified API contract ensures identical request and response shapes across the Next.js web server and Rust desktop server. The complete **API contract and endpoint inventory** lives in the [`api-contract.yaml`](https://github.com/phodal/routa/blob/main/api-contract.yaml) file at the repository root, defining server configurations, shared schemas, and the full REST path specification that both backends must implement. This single source of truth guarantees consistent behavior whether the application runs in a browser at `localhost:3000` or as a Tauri desktop app at `localhost:3210`.

## OpenAPI 3.1 Contract Structure

The contract file [`api-contract.yaml`](https://github.com/phodal/routa/blob/main/api-contract.yaml) organizes the API definition into three main sections: server metadata, reusable component schemas, and path operations.

### Server Configuration

The contract declares two base URLs to support Routa's dual-runtime architecture:

- `http://localhost:3000` — Next.js development server
- `http://localhost:3210` — Rust Tauri desktop server

These endpoints are defined around lines 10-14 of the contract file, allowing clients to target the appropriate backend based on the execution context.

### Shared Component Schemas

Centralized type definitions ensure payload consistency across TypeScript and Rust implementations. Key schemas referenced throughout the endpoint inventory include:

- **Agent** — Configuration for AI agents
- **Task** — Workflow execution units
- **Workspace** — Isolated project environments
- **GitLogCommit** — Version control metadata

These definitions span approximately lines 19-400 and are referenced by both the TypeScript front-end routes and Rust back-end handlers in `crates/routa-server/src/api/`.

## Complete Endpoint Inventory

The paths section begins around line 1000 of [`api-contract.yaml`](https://github.com/phodal/routa/blob/main/api-contract.yaml) and maps directly to handler implementations in `crates/routa-server/src/api/` and `src/app/api/`.

### Health and Skills

- `GET /api/health` — Verify service availability
- `GET /api/skills` — List all available skills
- `GET /api/skills?name={skill}` — Load a specific skill definition
- `POST /api/skills` — Reload the skill catalog (UI refresh trigger)

### Agent Management

- `GET /api/agents` — List agents in a workspace
- `POST /api/agents` — Create a new agent
- `GET /api/agents/{id}` — Retrieve a single agent
- `DELETE /api/agents/{id}` — Remove an agent

### Workspace Operations

- `GET /api/workspaces` — List all workspaces
- `POST /api/workspaces` — Create a workspace
- `GET /api/workspaces/{id}` — Get a specific workspace
- `DELETE /api/workspaces/{id}` — Delete a workspace

### Task Lifecycle

- `GET /api/tasks?workspaceId={wid}` — List tasks in a workspace
- `POST /api/tasks` — Create a task
- `GET /api/tasks/{id}` — Retrieve a task
- `POST /api/tasks/{id}/status` — Update a task’s status
- `GET /api/tasks/ready?workspaceId={wid}` — Find ready-to-run tasks
- `DELETE /api/tasks/{id}` — Delete a task

### Session and Note Management

- `GET /api/sessions` — List active sessions
- `GET /api/notes?workspaceId={wid}` — List notes
- `POST /api/notes` — Create a note
- `GET /api/notes/{id}` — Retrieve a note
- `DELETE /api/notes/{id}` — Delete a note

### ACP and Specialized Operations

- `POST /api/acp` — Submit prompts to the skill/agent router (Agent-Code-Pipeline)
- `GET/POST/DELETE /api/kanban/*` — CRUD for boards, columns, and cards
- `GET/POST /api/specialists/*`, `/api/providers/*` — Query and invoke AI providers
- `GET /api/traces/*` — Retrieve execution traces for debugging

### Desktop-Only Git Integration

The following endpoints require local filesystem access and are implemented only in the Rust back-end ([`crates/routa-server/src/api/git.rs`](https://github.com/phodal/routa/blob/main/crates/routa-server/src/api/git.rs)):

- `GET/POST/DELETE /api/git/*` — Repository manipulation
- `GET/POST/DELETE /api/codebases/*` — Codebase browsing operations
- `GET/POST/DELETE /api/clone/*` — Repository cloning workflows

## Client Implementation Patterns

Routa provides unified client utilities that abstract the dual-backend complexity, ensuring consumer code works regardless of the runtime environment.

### Unified Fetch Layer

The `desktopAwareFetch` helper in [`src/client/utils/diagnostics.ts`](https://github.com/phodal/routa/blob/main/src/client/utils/diagnostics.ts) automatically routes requests to the correct backend based on the execution environment.

Fetching workspaces in any environment:

```typescript
import { desktopAwareFetch } from '@/client/utils/diagnostics';

async function listWorkspaces() {
  const resp = await desktopAwareFetch('/api/workspaces');
  if (!resp.ok) throw new Error('Failed to fetch workspaces');
  const workspaces = await resp.json();   // matches the `Workspace` schema
  console.log(workspaces);
}

```

Creating a task via the ACP endpoint:

```typescript
import { desktopAwareFetch } from '@/client/utils/diagnostics';

async function runAcp(skillName: string, prompt: string) {
  const payload = {
    skillName,
    prompt,
  };
  const resp = await desktopAwareFetch('/api/acp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
  const result = await resp.json(); // conforms to `ReviewAnalyzeResponse`
  return result;
}

```

Accessing desktop-only Git operations:

```typescript
async function listGitRefs(repoId: string) {
  const resp = await desktopAwareFetch(`/api/git/${repoId}/refs`);
  const refs = await resp.json(); // matches `GitRefsResult`
  return refs;
}

```

## Contract Validation and Testing

The `tests/api-contract/` directory contains integration tests that enforce OpenAPI compliance across both backends. These tests verify that the live server responses match the schemas defined in [`api-contract.yaml`](https://github.com/phodal/routa/blob/main/api-contract.yaml).

Key validation files include:

- **[`tests/api-contract/test-workspaces.ts`](https://github.com/phodal/routa/blob/main/tests/api-contract/test-workspaces.ts)** — Validates workspace CRUD operations (lines 4-74)
- **[`tests/api-contract/test-tasks.ts`](https://github.com/phodal/routa/blob/main/tests/api-contract/test-tasks.ts)** — Confirms task endpoint compliance
- **[`tests/api-contract/test-sessions.ts`](https://github.com/phodal/routa/blob/main/tests/api-contract/test-sessions.ts)** — Verifies session API contracts

Because the contract serves as the single source of truth, any change to an endpoint must be reflected in both the Next.js API routes (`src/app/api/...`) and the Rust handlers (`crates/routa-server/src/api/...`).

## Summary

- The **[`api-contract.yaml`](https://github.com/phodal/routa/blob/main/api-contract.yaml)** file serves as the single source of truth for Routa's entire REST API surface, using OpenAPI 3.1 specification.
- Two server environments (web at `:3000`, desktop at `:3210`) share identical contracts and component schemas.
- The endpoint inventory covers agents, tasks, workspaces, skills, notes, sessions, Kanban boards, and Git operations.
- The **`desktopAwareFetch`** utility abstracts backend selection, enabling universal client code that runs in both browser and desktop contexts.
- Integration tests in `tests/api-contract/` enforce strict compliance with the OpenAPI specification across both TypeScript and Rust implementations.

## Frequently Asked Questions

### What format does the Routa API contract use?

The Routa API contract uses the **OpenAPI 3.1** specification stored in [`api-contract.yaml`](https://github.com/phodal/routa/blob/main/api-contract.yaml) at the repository root. This YAML document defines server URLs, reusable component schemas (like `Agent` and `Task`), and complete REST path specifications with request and response structures.

### How does Routa maintain consistency between web and desktop backends?

Both the Next.js front-end (`src/app/api/`) and the Rust Tauri back-end (`crates/routa-server/src/api/`) implement the same OpenAPI contract. Shared schemas guarantee identical JSON payloads across both environments, while the `tests/api-contract/` integration test suite verifies that both servers produce responses matching the canonical specification.

### Which endpoints are exclusive to the desktop application?

Git operations under `/api/git/*`, codebase browsing at `/api/codebases/*`, and repository cloning at `/api/clone/*` are implemented only in the Rust server ([`crates/routa-server/src/api/git.rs`](https://github.com/phodal/routa/blob/main/crates/routa-server/src/api/git.rs)). These endpoints require local filesystem access and are unavailable in the browser-based web runtime.

### Where are the API contract tests located?

Integration tests validating OpenAPI compliance reside in the `tests/api-contract/` directory, including [`test-workspaces.ts`](https://github.com/phodal/routa/blob/main/test-workspaces.ts), [`test-tasks.ts`](https://github.com/phodal/routa/blob/main/test-tasks.ts), and [`test-sessions.ts`](https://github.com/phodal/routa/blob/main/test-sessions.ts). These files exercise the live server endpoints and verify that responses conform to the schemas defined in [`api-contract.yaml`](https://github.com/phodal/routa/blob/main/api-contract.yaml), ensuring both backends remain synchronized with the contract.