Companions API¶

The Companions API orchestrates multi-persona LLM modes — a single answer, several answers in parallel, or parallel answers synthesized by a lead companion — behind one simple REST interface. You send a prompt and a mode; the platform runs the personas, bills each model call on what it actually used, and returns a typed result.

Base URL      https://api.humx.ai
Version       v1   (every path is prefixed /v1)
Content type  application/json

How it works¶

Every run is asynchronous. A run-producing request (like POST /v1/completion) returns immediately with a job envelope — an id of the form job-<uuid> and a pending status. You then read the result from the unified /v1/jobs/{id} surface, either by polling or by subscribing to a live event stream.

POST /v1/completion   ──►   { "id": "job-abc…", "status": "pending" }
                                     │
GET  /v1/jobs/job-abc…  ◄────────────┘   poll until status is terminal
                             or
GET  /v1/jobs/job-abc…/stream            subscribe (Server-Sent Events)

This one envelope (JobStatus) is returned by every run-producing endpoint, so a client learns the shape once and reuses it everywhere.

Quickstart¶

# 1. Submit: name the companion that answers (GET /v1/discover lists yours).
curl https://api.humx.ai/v1/completion \
  -H "Authorization: ApiKey $COMPANIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Explain rate limiting to a new engineer.", "mode": "answer", "main": "Ada" }'
# → { "id": "job-1a2b...", "status": "pending" }

# 2. Poll that job id until its status is terminal (complete, failed or cancelled).
curl https://api.humx.ai/v1/jobs/job-1a2b... \
  -H "Authorization: ApiKey $COMPANIONS_API_KEY"
# → { "status": "complete", "content": { "shape": "answer", "response": "..." } }

import os, time, requests

headers = {"Authorization": f"ApiKey {os.environ['COMPANIONS_API_KEY']}"}

# 1. Submit: name the companion that answers (GET /v1/discover lists yours).
job = requests.post(
    "https://api.humx.ai/v1/completion",
    headers=headers,
    json={"prompt": "Explain rate limiting to a new engineer.", "mode": "answer", "main": "Ada"},
).json()

# 2. Poll that job id until its status is terminal.
while job["status"] not in ("complete", "failed", "cancelled"):
    time.sleep(1.0)
    job = requests.get(f"https://api.humx.ai/v1/jobs/{job['id']}", headers=headers).json()

print(job["content"]["response"])

const headers = {
  Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY}`,
  "Content-Type": "application/json",
};

// 1. Submit: name the companion that answers (GET /v1/discover lists yours).
let job = await (await fetch("https://api.humx.ai/v1/completion", {
  method: "POST",
  headers,
  body: JSON.stringify({ prompt: "Explain rate limiting to a new engineer.", mode: "answer", main: "Ada" }),
})).json();

// 2. Poll that job id until its status is terminal.
while (!["complete", "failed", "cancelled"].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 1000));
  job = await (await fetch(`https://api.humx.ai/v1/jobs/${job.id}`, { headers })).json();
}

console.log(job.content.response);

const headers = {
  Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY!}`,
  "Content-Type": "application/json",
};

// 1. Submit: name the companion that answers (GET /v1/discover lists yours).
let job = await (await fetch("https://api.humx.ai/v1/completion", {
  method: "POST",
  headers,
  body: JSON.stringify({ prompt: "Explain rate limiting to a new engineer.", mode: "answer", main: "Ada" }),
})).json();

// 2. Poll that job id until its status is terminal.
while (!["complete", "failed", "cancelled"].includes(job.status)) {
  await new Promise((r) => setTimeout(r, 1000));
  job = await (await fetch(`https://api.humx.ai/v1/jobs/${job.id}`, { headers })).json();
}

console.log(job.content.response);

See Authentication to mint a key, then Completion for the full request shape.

Reference¶

Errors¶

The API uses conventional HTTP status codes.

A 422 body follows FastAPI's detail convention: a list of entries, each naming the field (loc), a machine-readable type, and a human msg.

{
  "detail": [
    {
      "type": "prompt_or_messages",
      "loc": ["body"],
      "msg": "provide exactly one of prompt or messages"
    }
  ]
}