API overview

The SAT REST API is what the web app, the sat CLI and runners use. Everything you can do in the product, you can do with it: manage companies, agents, tasks, goals, projects, runs, approvals and routines, read costs and the audit trail, and subscribe to live changes. This page covers the conventions every endpoint shares. The endpoint pages under Endpoints are generated from the OpenAPI spec.

Base URLsCopy Anchor Link

All paths start with /api, for example https://app.yarlis.com/api/companies. The health check is /health.

VersioningCopy Anchor Link

The API is not versioned yet. Paths carry no version, and there is no version header. The spec reports 2.1.0 as its version, which is informational. Changes are made in place, so pin to a commit of @sat/api-client if you need a stable contract, and watch the changelog.

AuthenticationCopy Anchor Link

Send a bearer credential on every request except registration, sign-in, token refresh, password reset and /health:

GET /api/companies HTTP/1.1
Host: app.yarlis.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The credential is either:

• an access token from POST /api/login, valid for 30 minutes and renewed with the refresh token, or
• a personal API key (sat_live_...) for scripts, CI and runners. It does not expire unless you set an expiry.

Both authenticate as a person (a member). Company endpoints then check that this person is a member of the company. See Authentication.

Requests and responsesCopy Anchor Link

Lists and paginationCopy Anchor Link

List endpoints return a JSON array, not an envelope. There is no cursor pagination, except for the activity log.

ErrorsCopy Anchor Link

Errors use one envelope:

{"error": {"code": "RUN_LEASE_LOST", "message": "Run is cancelled", "details": {}}}

Branch on code, not on message. Framework errors use the same envelope: request validation errors are 422 VALIDATION_ERROR, unknown paths 404 NOT_FOUND, wrong methods 405 METHOD_NOT_ALLOWED, a missing bearer credential 401 AUTH_REQUIRED, rate limiting 429 RATE_LIMITED and unexpected failures 500 INTERNAL_ERROR. Company resources you cannot see answer 404, never 403. See Errors for every code.

Rate limitsCopy Anchor Link

Most endpoints have no rate limit. These are limited per client IP address:

Over the limit, the API answers 429 with the error envelope, code RATE_LIMITED and a message such as Too many requests: 5 per 1 minute. Sign-in is not rate limited; instead, five wrong passwords in a row lock the account for 30 minutes. See Authentication.

CORSCopy Anchor Link

Browsers can call the API from the origins listed in the API's ALLOWED_ORIGINS environment variable (comma separated). If it is unset, every origin is allowed. Production sets it to the web app's origins. Allowed methods are GET, POST, PUT, PATCH, DELETE and OPTIONS, with any request header. If you serve a web client from your own origin, or read live events from the API's direct origin, that origin must be in the list.

OpenAPI specCopy Anchor Link

The spec is checked in at libs/api-client/openapi.json. It is exported from the FastAPI app:

bun run --cwd libs/api-client generate   # writes openapi.json and the TypeScript types

A running API serves the spec at /openapi.json and interactive docs at /docs only when it runs with DEBUG=true. The production API does not serve them.

The checked-in spec also contains legacy routes (/api/agents, /api/sessions, /api/users/..., /api/monitoring/..., /api/websocket/...). They are not part of the supported API, and this reference leaves them out.

Typed clientCopy Anchor Link

@sat/api-client (libs/api-client) is a TypeScript client generated from the spec, used by the web app and the CLI. It is a workspace package in the SAT repository, not published to npm. It wraps openapi-fetch with bearer authentication, a single shared token refresh on 401, and the error envelope as an ApiError.

import { createApiClient, type TokenStore } from '@sat/api-client';

const tokens: TokenStore = {
  getAccessToken: () => process.env.SAT_API_KEY ?? null,
  getRefreshToken: () => null,
  setTokens: () => {},
  clear: () => {},
};

const api = createApiClient({ baseUrl: 'https://app.yarlis.com', tokens });

const tasks = await api.call(() =>
  api.client.GET('/api/companies/{company_id}/tasks', {
    params: { path: { company_id: process.env.SAT_COMPANY_ID! }, query: { status: ['blocked'] } },
  })
);
console.log(tasks.map((t) => `${t.key} ${t.title}`));

api.call returns the data or throws ApiError with status, code and message. api.authedFetch is a plain fetch with the same authentication and refresh. For live events, see subscribeToCompanyEvents in Live events.

Endpoint groupsCopy Anchor Link