REST API Overview

CodeSpar exposes a REST API for programmatic access to agents, projects, audit logs, channels, memory, and organizations. The API is used internally by the agent system and can be consumed by external tools, dashboards, and CI/CD integrations.

Base URL

The API base URL is configurable via the PORT environment variable. By default, the server listens on port 3000:

http://localhost:3000

When deployed on Railway, the port is typically 8080 (auto-set by Railway). In production, you would place this behind a reverse proxy or load balancer with HTTPS.

https://api.codespar.example.com

Response Format

All API responses are JSON. Successful responses return the data directly:

{
  "id": "agent-abc123",
  "type": "project",
  "status": "ACTIVE",
  "autonomyLevel": 1
}

List endpoints return arrays:

[
  { "id": "agent-abc123", "type": "project", "status": "ACTIVE" },
  { "id": "agent-def456", "type": "task", "status": "IDLE" }
]

Paginated endpoints (like audit) return a wrapper object:

{
  "entries": [...],
  "total": 150,
  "page": 1,
  "pageSize": 20,
  "totalPages": 8,
  "hasMore": true
}

Authentication

CodeSpar does not implement authentication at the API level. Authentication is delegated to the deployment layer — your reverse proxy, API gateway, or platform (e.g., Railway private networking, Cloudflare Access, or a custom auth middleware).

This design keeps the core engine simple and allows each deployment to use its preferred auth strategy.

For multi-tenant deployments, use the x-org-id header (see below) to scope requests to a specific organization.

Multi-Tenant Scoping

CodeSpar supports multi-tenant deployments via the x-org-id header. When provided, all API operations are scoped to the specified organization:

curl http://localhost:3000/api/projects \
  -H "x-org-id: org-acme-corp"

Without the header, requests operate in the default (single-tenant) context.

Pagination

The audit endpoint supports pagination with limit and page query parameters:

Example:

curl "http://localhost:3000/api/audit?limit=10&page=3"

Response includes pagination metadata:

{
  "entries": [...],
  "total": 150,
  "page": 3,
  "pageSize": 10,
  "totalPages": 15,
  "hasMore": true
}

Error Handling

Errors follow standard HTTP status codes with a JSON error body:

Error response format:

{
  "error": "Agent not found",
  "code": "AGENT_NOT_FOUND",
  "status": 404
}

API Versioning

All endpoints are available under the /v1/ prefix. For example, GET /api/agents can also be accessed as GET /v1/api/agents. Both forms are equivalent and will remain supported.

Every API response includes the X-API-Version header indicating the current version:

X-API-Version: v1

Rate Limiting

API requests are rate-limited to protect the server:

When the limit is exceeded, the server responds with 429 Too Many Requests and a Retry-After header.

API Endpoints

Quick Start

List all agents:

curl http://localhost:3000/api/agents

Get agent details:

curl http://localhost:3000/api/agents/agent-abc123

Trigger an agent action:

curl -X POST http://localhost:3000/api/agents/agent-abc123/action \
  -H "Content-Type: application/json" \
  -d '{"action": "set_autonomy", "params": {"level": 3}}'

View recent audit entries:

curl "http://localhost:3000/api/audit?limit=5"

Next Steps

• Agent API -- Manage agents
• Project API -- Link repositories
• Scheduler API -- Recurring tasks
• Configuration -- Environment variables and setup