Core HTTP reference

The API base URL is https://api.auvy.ai (/v1/...). JSON request and response bodies; standard HTTP status codes.

For TypeScript apps, start with First SDK call. For assistants and terminals, see First harness call.

Authentication

JWT-only routes (API keys management, session bootstrap, MCP toolkit admin) are not in the published OpenAPI file — use the Cortex dashboard with a signed-in user.

Issue API keys under Admin → API keys.

import { fromApiKey } from '@auvy-os/client'
const auvy = await fromApiKey(process.env.AUVY_API_KEY!)

curl https://api.auvy.ai/v1/receptors \
  -H "Authorization: Bearer YOUR_API_KEY"

Resources vs invoke routes

Errors

{ "message": "Human-readable error", "code": "ERROR_CODE" }

See Jobs, streaming, and errors.

Pagination

List endpoints accept limit and offset. The SDK provides paginate() helpers — SDK resources.

Streaming

Invoke with stream: true, then GET /v1/jobs/:jobId/stream (SSE). See Jobs, streaming, and errors.

Health

GET /v1/health (or GET /health) returns service status. With an API key, the response includes workspace context when available:

const health = await auvy.health.check()

Unauthenticated checks return { "status": "healthy", "version": "..." }. fromApiKey() uses GET /v1/session/context for bootstrap, not health.

OpenAPI

openapi.json — OpenAPI 3.1 spec generated from auvy-os (matches live GET /openapi on the API).

Core endpoints (this reference)

Skills, interventions, voice, meetings, usage, and other advanced HTTP topics are covered on the SDK resources page or via SDK namespaces — not duplicated in this slim reference.