Routa API Contract and Endpoint Inventory: Complete OpenAPI 3.1 Reference

The Routa API contract is defined in a single OpenAPI 3.1 document (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 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 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 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):

• 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 automatically routes requests to the correct backend based on the execution environment.

Fetching workspaces in any environment:

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:

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:

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.

Key validation files include:

• tests/api-contract/test-workspaces.ts — Validates workspace CRUD operations (lines 4-74)
• tests/api-contract/test-tasks.ts — Confirms task endpoint compliance
• 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 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 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). 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, test-tasks.ts, and test-sessions.ts. These files exercise the live server endpoints and verify that responses conform to the schemas defined in api-contract.yaml, ensuring both backends remain synchronized with the contract.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}