Agent API v1

Programmatic access to create and manage projects using an API key. All paths below are prefixed with /v1.

Base URL in production is typically https://api.solenai.ca. Self-hosted deployments use your API origin (for example NEXT_PUBLIC_API_BASE).

Authentication

Send your workspace API key on every request using one of:

• Header x-api-key: <your-key>
• Header Authorization: Bearer <your-key>

Keys are created in the product under workspace / API keys. Each key has permission scopes (for example projects:read, projects:write). Missing scope returns 403 with insufficient_permissions.

POST /v1/projects, Create a project

Creates a goal (project) from a prompt and optionally starts a deploy. Requires projects:write.

Body (JSON)

• prompt (string, required), Natural language description.
• name (string, optional), Display name; defaults from prompt.
• autoDeploy (boolean, optional), Default true. Set false to keep status draft until you deploy from the UI or API.
• config (object, optional), May include stack, db, auth hints.

POST /v1/projects HTTP/1.1
Host: api.solenai.ca
Content-Type: application/json
x-api-key: sk_live_...

{
  "prompt": "Customer CRM with deals pipeline and weekly digest email",
  "name": "Northstar CRM",
  "autoDeploy": true,
  "config": { "stack": "next", "db": "postgres", "auth": "oauth" }
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Northstar CRM",
  "status": "deploying",
  "deploymentUrl": null,
  "createdAt": "2026-04-01T12:00:00.000Z",
  "updatedAt": "2026-04-01T12:00:00.000Z",
  "spec": {
    "goalType": "backend_api",
    "stack": "next",
    "features": [],
    "requiresDatabase": true,
    "requiresAuth": true
  },
  "lastRun": null,
  "autoDeploy": true
}

GET /v1/projects, List projects

Returns up to 100 projects in your workspace, newest first. Requires projects:read.

GET /v1/projects HTTP/1.1
Host: api.solenai.ca
x-api-key: sk_live_...

{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Northstar CRM",
      "status": "deployed",
      "deploymentUrl": "https://northstar.apps.solenai.ca",
      "createdAt": "2026-04-01T12:00:00.000Z",
      "updatedAt": "2026-04-01T12:05:00.000Z",
      "spec": {
        "goalType": "backend_api",
        "stack": "next",
        "features": [],
        "requiresDatabase": true,
        "requiresAuth": true
      },
      "lastRun": {
        "runId": "…",
        "status": "SUCCEEDED",
        "startedAt": "2026-04-01T12:00:00.000Z",
        "finishedAt": "2026-04-01T12:04:30.000Z"
      }
    }
  ]
}

GET /v1/projects/:id, Get project details

Returns one project by ID. Requires projects:read.

GET /v1/projects/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.solenai.ca
x-api-key: sk_live_...

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Northstar CRM",
  "status": "deployed",
  "deploymentUrl": "https://northstar.apps.solenai.ca",
  "createdAt": "2026-04-01T12:00:00.000Z",
  "updatedAt": "2026-04-01T12:05:00.000Z",
  "spec": {
    "goalType": "backend_api",
    "stack": "next",
    "features": [],
    "requiresDatabase": true,
    "requiresAuth": true
  },
  "lastRun": {
    "runId": "…",
    "status": "SUCCEEDED",
    "startedAt": "2026-04-01T12:00:00.000Z",
    "finishedAt": "2026-04-01T12:04:30.000Z"
  }
}

POST /v1/projects/:id/deploy, Trigger deploy

Starts a new pipeline execution for the project. Requires projects:write.

{
  "runId": "…",
  "status": "PENDING",
  "estimatedTime": 300
}

POST /v1/projects/:id/rollback, Roll back to last good

Same semantics as POST /api/goals/:id/rollback-to-last-good: restores the last known-good version (Solen or spec-based). Requires scope rollback on the API key. Subject to workspace agent policy.

{
  "ok": true,
  "versionNumber": 12,
  "liveUrl": "https://myapp.apps.solenai.ca",
  "deploymentId": "…"
}

GET /v1/projects/:id/runs, List runs

Query params: limit (default 20), cursor, status. Requires runs:read.

GET /v1/runs/:runId/logs, Build logs

If the run is still PENDING or RUNNING, the response is a one-shot text/event-stream of JSON objects in data: lines. Otherwise returns JSON { logs, nextCursor, total }. Requires runs:read.

TypeScript SDK, @solenai/sdk

Install from npm (after publish) and call the v1 API with full types. Uses x-api-key automatically.

npm install @solenai/sdk

import { SolenClient } from '@solenai/sdk';

const client = new SolenClient({
  apiKey: process.env.SOLEN_API_KEY!,
  baseUrl: 'https://api.solenai.ca',
});

await client.createProject({ prompt: 'A todo app with auth' });
const { projects } = await client.listProjects();
const run = await client.deploy(projectId);
await client.rollback(projectId);
const status = await client.getStatus(projectId);

Methods: createProject, listProjects, getProject, getStatus, deploy, rollback, listRuns, getRunLogs, streamRunLogs.

CLI, @solenai/cli

Global install or run once with npx. Credentials are stored in ~/.solen/config.json after solen login.

npm install -g @solenai/cli
solen login
# paste API key; optional: solen login --url https://api.solenai.ca

solen create "a todo app with auth" [--name MyApp] [--draft]
solen deploy <project-id>
solen status <project-id>
solen logs <project-id> [--limit 200]
solen rollback <project-id>

Publishing to npm (maintainers)

1. Create an npm account and an organization/scope for @solenai (or use your org name and update package names).
2. From the repo: pnpm install, then pnpm --filter @solenai/sdk build and pnpm --filter @solenai/cli build.
3. npm publish --access public in each package directory (SDK first, then CLI). Use a CI trusted publisher or OTP as required by your npm policy.

Rate limits

The /v1 router applies per-minute limits: 100 requests per minute per API key (configurable via RATE_LIMIT_V1_KEY_PER_MIN), and 20 requests per minute per IP when no key is presented (RATE_LIMIT_V1_IP_PER_MIN). Redis-backed when REDIS_URL is set.

When exceeded, the API returns 429 Too Many Requests with a JSON body such as:

{
  "error": "rate_limit_exceeded",
  "retryAfter": 45
}

The Retry-After header is set in seconds.

Error codes