Completion¶

POST /v1/completion is the engine's front door. You give it an input and a mode; it enqueues a run and returns a job envelope. The run itself is asynchronous — read the result from /v1/jobs/{id}.

POST /v1/completion¶

Enqueue an engine run. Returns a pending JobStatus with an id of the form job-<uuid>.

Input: prompt or messages¶

Provide exactly one of these (supplying both or neither is a 422):

For messages, role is one of system, user, or assistant; the summed length of all content is capped at 500,000 characters (1–256 turns).

Body¶

Modes¶

Settings¶

settings is the single per-call override object. Every field is optional.

Examples¶

curl https://api.humx.ai/v1/completion \
  -H "Authorization: ApiKey $COMPANIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "prompt": "What are the trade-offs of optimistic locking?",
        "mode": "answer",
        "settings": { "temperature": 0.4 }
      }'

import os, requests

r = requests.post(
    "https://api.humx.ai/v1/completion",
    headers={"Authorization": f"ApiKey {os.environ['COMPANIONS_API_KEY']}"},
    json={
        "prompt": "What are the trade-offs of optimistic locking?",
        "mode": "answer",
        "settings": {"temperature": 0.4},
    },
)
r.raise_for_status()
job = r.json()
print(job["id"], job["status"])   # job-... pending

const res = await fetch("https://api.humx.ai/v1/completion", {
  method: "POST",
  headers: {
    Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "What are the trade-offs of optimistic locking?",
    mode: "answer",
    settings: { temperature: 0.4 },
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const job = await res.json();
console.log(job.id, job.status); // job-... pending

interface JobStatus {
  id: string;
  kind: "completion" | "companion" | "team" | "forensics";
  status: "pending" | "running" | "complete" | "failed" | "requires_action";
  content?: unknown;
}

const res = await fetch("https://api.humx.ai/v1/completion", {
  method: "POST",
  headers: {
    Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY!}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "What are the trade-offs of optimistic locking?",
    mode: "answer",
    settings: { temperature: 0.4 },
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const job = (await res.json()) as JobStatus;

A multi-persona example — a parallel run across three companions:

{
  "prompt": "Should we adopt event sourcing for the orders service?",
  "mode": "parallel",
  "participants": ["architect", "sre", "product-lead"]
}

Response¶

200 — a pending job envelope. The answer arrives later via /v1/jobs/{id}.

{
  "type": "status",
  "id": "job-1a2b3c4d-...",
  "kind": "completion",
  "status": "pending",
  "mode": "answer"
}

Once complete, the same job carries a typed content keyed by shape:

{
  "id": "job-1a2b3c4d-...",
  "kind": "completion",
  "status": "complete",
  "content": {
    "shape": "answer",
    "companion": "Ada",
    "response": "Optimistic locking trades..."
  }
}

See Jobs → Result shapes for every mode's content.

Client tools¶

Attach a tools array to declare functions the model can call on your machine (available for answer and answer_crumbs). When the model calls one, the run pauses and hands the call back — the server never executes your tools. You run them and return the results via POST /v1/jobs/{id}/tool_outputs.

{
  "prompt": "What's in my workspace?",
  "mode": "answer",
  "tools": [
    {
      "name": "read_user_file",
      "description": "Read a file from the user's local workspace.",
      "parameters": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "Path relative to workspace root" }
        },
        "required": ["path"]
      }
    }
  ]
}

parameters is plain, provider-neutral JSON Schema. Bounds: up to 32 tools; each name matches ^[a-zA-Z_][a-zA-Z0-9_]*$ (1–64 chars, unique per request); parameters ≤ 16 KiB serialized. The full pause/resume loop lives on the Jobs page.

Validation¶

A 422 is returned before any run is enqueued when, for example:

Insufficient balance surfaces as 402 when the run is charged.