Note: the task's "Authoritative research for api" field was delivered empty ({}). Rather than invent details, every API fact below is sourced directly from the Socheli monorepo — packages/api/src/server.ts, packages/api/src/match.ts, packages/api/package.json, packages/sdk/src/index.ts, and docs/api.md. No endpoints, fields, env vars, or auth semantics have been invented.

---

@socheli/api

The REST control-plane backbone for Socheli — a Hono API at api.socheli.com that dispatches render jobs across a fleet over MQTT.

---

What it is

@socheli/api is the HTTP control plane for the Socheli content engine. Every first-party client — the SDK, the CLI, the MCP server — and any third-party integration talks to this service.

It is a small, fast Hono server (@hono/node-server) that does two things:

• Reads come straight from the file store (items, jobs, fleet, schedule).
• Writes either dispatch a job to a render device over MQTT or spawn the engine directly.

Generation requests are routed by a capability-aware central scheduler: each job's requirements are derived, then the best-fit online device in the live fleet is selected (preferring an idle device, with more RAM as a tie-breaker).

Auth is a single static API key, passed as a Bearer token.

---

Install

npm install @socheli/api
# or
pnpm add @socheli/api

The package exposes a socheli-api binary and a start script.

// package.json (excerpt)
{
  "name": "@socheli/api",
  "version": "0.1.0",
  "bin": { "socheli-api": "src/server.ts" },
  "scripts": { "start": "node --import tsx src/server.ts" }
}

Run it:

SOCHELI_API_KEY=sk_your_key npm start
# [socheli-api 0.1.0] listening on :8787

If SOCHELI_API_KEY is unset, the server still boots but logs a warning and answers 503 API not configured (no SOCHELI_API_KEY) on every authenticated route.

Hosted

The managed instance lives at https://api.socheli.com (version prefix /v1). You don't need to self-host to use it — point a client at the base URL with your key.

---

Authentication

A single Socheli API key, sent as a Bearer token. Every endpoint except GET /v1/health requires it.

Authorization: Bearer <SOCHELI_API_KEY>

Failure	Status	Body
Wrong / missing key	401	{ "error": "unauthorized" }
Server has no key configured	503	{ "error": "API not configured (no SOCHELI_API_KEY)" }

Clients (SDK/CLI/MCP) read the key from the SOCHELI_API_KEY environment variable. On a self-hosted deployment, set it in the server's environment (e.g. an .env file or your process manager). For the managed service, provision a key from your Socheli dashboard.

---

Quickstart

# Health (no auth required)
curl -s https://api.socheli.com/v1/health

# Inspect the fleet
curl -s https://api.socheli.com/v1/fleet \
  -H "Authorization: Bearer $SOCHELI_API_KEY"

# Generate + publish a vertical post end to end
curl -s -X POST https://api.socheli.com/v1/generate \
  -H "Authorization: Bearer $SOCHELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed":"why we procrastinate","channel":"concept_lab","type":"auto"}'

Prefer typed calls? Use the @socheli/sdk:

import { createSocheli } from "@socheli/sdk";

const socheli = createSocheli({ apiKey: process.env.SOCHELI_API_KEY });

const { devices, online } = await socheli.fleet();
const { job } = await socheli.generate({ seed: "the science of habit", channel: "concept_lab" });

---

API reference

Base URL: https://api.socheli.com · Version prefix: /v1

All responses are JSON. Errors are { "error": "message" } with conventional status codes: 400 bad input · 401 unauthorized · 404 not found · 502 broker down · 503 unconfigured.

Reads

GET /v1/health

Open (no auth). Liveness + build info.

→ { ok: true, version: string, uptime: number } — uptime in seconds.

GET /v1/items

List recent items.

Query: limit (number), channel (string).

→ ItemSummary[] — each { id, channel, status, title, createdAt, updatedAt, qa?, costUsd?, publish? }.

GET /v1/items/:id

Full item.

→ Item (extends ItemSummary, adds idea, script, storyboard, pkg, videoUrl). 404 if missing.

GET /v1/jobs

The 30 most recent fleet jobs.

→ JobRow[] — each { id, type, status, device?, itemId?, progress[], … }.

GET /v1/fleet

Devices + recent jobs + online count.

→ FleetState — { devices: Device[], jobs: JobRow[], online: number }.

GET /v1/schedule

Read the current autopilot schedule (cadence + slots).

→ Schedule.

Writes

POST /v1/generate

Dispatch a render job to the fleet. The central scheduler derives the job's capability requirements and routes it to the best-fit device over MQTT.

Body:

{
  "seed": "the science of habit",
  "channel": "concept_lab",
  "type": "new",
  "mood": "explainer",
  "voice": false
}

Field	Type	Notes
seed	string	Required. 400 seed required if absent.
channel	string	Defaults to concept_lab.
type	"new" | "auto"	"new" = build only; "auto" = build + publish. Anything else coerces to "new".
mood	string	Optional render mood (e.g. explainer, cinematic).
voice	boolean	true prefers a premium-voice-capable device.

→ { dispatched: true, job, device, routing }.

• 503 with { error, requirements } if no online device satisfies the job's hard requirement (render).
• 502 broker unreachable: <message> if the MQTT broker can't be reached.

Scheduler behavior (from match.ts): every generation job hard-requires the render capability. Music (music:musicgen), b-roll (broll:sdturbo, broll:pexels), and — when voice: true — premium voice (voice:eleven) are preferences; a minimal device still renders, degrading gracefully. Among capable online devices, an idle device is strongly preferred (+100), each matched preference adds +10, and more RAM breaks ties.

POST /v1/items/:id/publish

Publish an existing item to all configured platforms (server-side). Spawns the engine's publish command detached.

Body:

{ "public": true, "aigc": true }

Field	Type	Effect
public	boolean	true adds --public.
aigc	boolean	false adds --no-aigc (AIGC disclosure on by default).

→ { dispatched: true }.

PUT /v1/schedule

Replace the autopilot schedule (cadence + slots). Persists to schedule.json and stamps updatedAt.

Body: a Schedule object. 400 bad schedule if the body isn't an object.

→ the saved Schedule.

---

SDK method ↔ endpoint map

The @socheli/sdk SocheliClient mirrors this API one-to-one. Zero runtime dependencies — just fetch (Node 18+, Bun, Deno, edge).

SDK call	HTTP
socheli.health()	GET /v1/health
socheli.items.list({ limit?, channel? })	GET /v1/items
socheli.items.get(id)	GET /v1/items/:id
socheli.items.publish(id, input?)	POST /v1/items/:id/publish
socheli.generate(input)	POST /v1/generate
socheli.jobs()	GET /v1/jobs
socheli.fleet()	GET /v1/fleet
socheli.schedule.get()	GET /v1/schedule
socheli.schedule.set(schedule)	PUT /v1/schedule

import { createSocheli, SocheliError } from "@socheli/sdk";

// apiKey  ← opts.apiKey ?? process.env.SOCHELI_API_KEY
// baseUrl ← opts.baseUrl ?? process.env.SOCHELI_API_URL ?? https://api.socheli.com
const socheli = createSocheli();

try {
  const items = await socheli.items.list({ channel: "concept_lab", limit: 10 });
} catch (e) {
  if (e instanceof SocheliError) console.error(e.status, e.message, e.body);
}

---

Configuration

The server reads everything from environment variables.

Variable	Default	Purpose
SOCHELI_API_KEY	(none)	Bearer key required by all /v1/* routes except /v1/health.
SOCHELI_API_PORT	8787	Listen port.
SOCHELI_BROKER_URL	mqtt://127.0.0.1:1883	MQTT broker for fleet dispatch.
SOCHELI_MQTT_USER	(none)	MQTT username.
SOCHELI_MQTT_PASS	(none)	MQTT password.
SOCHELI_DATA_DIR	<root>/data	File store root (items, jobs, fleet, schedule).
SOCHELI_RENDERS_DIR	<DATA_DIR>/renders	Rendered output directory.

Client-side, @socheli/sdk honors SOCHELI_API_KEY and SOCHELI_API_URL.

MQTT dispatch

POST /v1/generate connects to the broker (SOCHELI_BROKER_URL, with optional user/pass and an 8s connect timeout) and publishes the job to:

socheli/device/<device>/jobs        (QoS 1)

where <device> is the device chosen by the central scheduler.

---

Errors

All errors return JSON { "error": "message" }:

Status	When
400	Bad input (seed required, bad schedule).
401	Wrong or missing API key.
404	Item or route not found.
502	Broker unreachable during dispatch.
503	API not configured, or no online device satisfies the job.

---

The Socheli family

@socheli/api is one of four packages — pick the surface that fits your stack. All speak to the same control plane.

Package	What it is	Repo
@socheli/api	REST control plane (Hono) at api.socheli.com, with MQTT fleet dispatch.	Socheli/api
@socheli/sdk	Official zero-dependency TypeScript client.	Socheli/sdk
@socheli/cli	The socheli command-line interface.	Socheli/cli
@socheli/mcp	Model Context Protocol server — Socheli as agent tools.	Socheli/mcp

Docs: socheli.com/docs

---

Developed in the Socheli monorepo

@socheli/api is developed and released from the Socheli monorepo, alongside the engine, SDK, CLI, MCP server, and dashboard. This repo mirrors the packages/api workspace.

---

License

MIT