Skip to content

Discover

GET /v1/discover returns everything you can pick from in a single read: the teams you own (each with its member companions) and the flat list of every companion you can use — your own plus every public one. Use it to populate a "who can I involve?" picker, then pass the names or ids as main / participants on a completion.

POST /v1/discover is the ask flow: describe a task and the platform's routing guide answers with a grounded, priced setup — see below.

GET /v1/discover

Return the teams and companions available to you.

curl https://api.humx.ai/v1/discover \
  -H "Authorization: ApiKey $COMPANIONS_API_KEY"

import os, requests

r = requests.get(
    "https://api.humx.ai/v1/discover",
    headers={"Authorization": f"ApiKey {os.environ['COMPANIONS_API_KEY']}"},
)
r.raise_for_status()
data = r.json()
print([c["name"] for c in data["companions"]])

const res = await fetch("https://api.humx.ai/v1/discover", {
  headers: { Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY}` },
});
const { teams, companions } = await res.json();

interface Companion {
  id: string;            // cmp_<uuid>
  name: string;
  kind: string;
  visibility: "public" | "private" | "shared";
  description: string | null;
  teams: string[];       // team_<uuid> ids
}
interface Team {
  id: string;            // team_<uuid>
  name: string;
  visibility: "public" | "private" | "shared";
  main_companion_id: string | null;
  members: { id: string; name: string; kind: string; description: string | null }[];
}
interface DiscoverResponse { teams: Team[]; companions: Companion[] }

const res = await fetch("https://api.humx.ai/v1/discover", {
  headers: { Authorization: `ApiKey ${process.env.COMPANIONS_API_KEY!}` },
});
const data = (await res.json()) as DiscoverResponse;

Response

200

Field Type Description
teams array Every team visible to you, each with its resolved members.
companions array The flat, authoritative set of companions you can use.

A team carries id (team_<uuid>), name, visibility, main_companion_id, and members[]. A companion carries id (cmp_<uuid>), name, kind, visibility, description, and the teams[] it belongs to.

{
  "teams": [
    {
      "id": "team_9f...",
      "name": "Backend Review",
      "visibility": "private",
      "main_companion_id": "cmp_1a...",
      "members": [
        { "id": "cmp_1a...", "name": "Architect", "kind": "synthetic", "description": "..." },
        { "id": "cmp_2b...", "name": "SRE", "kind": "synthetic", "description": "..." }
      ]
    }
  ],
  "companions": [
    { "id": "cmp_1a...", "name": "Architect", "kind": "synthetic", "visibility": "private", "description": "...", "teams": ["team_9f..."] },
    { "id": "cmp_3c...", "name": "Ada", "kind": "interview", "visibility": "public", "description": "...", "teams": [] }
  ]
}

The flat list is the pickable set

Team membership in the response is a grouping aid. The companions array is the authoritative list of who you can name in a completion — including companions already bound to a team.

POST /v1/discover

Ask for the best Companions setup for a concrete task. The platform's routing guide (the ferryman) answers with a recommendation — mode, companion(s), a reshaped prompt — grounded against your visible roster, plus a price band for running it.

This endpoint bills: it runs a small, capped model call, metered like any run.

curl -X POST https://api.humx.ai/v1/discover \
  -H "Authorization: ApiKey $COMPANIONS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "review my migration plan for a zero-downtime Postgres upgrade"}'

import os, requests

r = requests.post(
    "https://api.humx.ai/v1/discover",
    headers={"Authorization": f"ApiKey {os.environ['COMPANIONS_API_KEY']}"},
    json={"task": "review my migration plan for a zero-downtime Postgres upgrade"},
)
r.raise_for_status()
print(r.json()["id"])  # a job id — poll GET /v1/jobs/{id}

Body

Field Type Required Description
task string ✓ What you want to do.
context string Project or user context.
self object The asking agent's {model, harness, capabilities} portrait.
surface string Calling surface; defaults to coding_agent.
constraints object Soft hints: {"budget": "low|normal|high", "speed": "fast|normal"}.

Response

200 — the standard job envelope (status: "pending"). Collect the result via GET /v1/jobs/{id}; the terminal content is:

{
  "kind": "setup_advice",
  "recommendation": {
    "mode": "answer",
    "main": {"id": "cmp_...", "name": "..."},
    "rationale": "...",
    "reshaped_prompt": "...",
    "use_search": false,
    "attach_tools": true
  },
  "recommendation_grounded": true,
  "estimate": {"expected": 0.04, "low": 0.02, "high": 0.09, "sufficient": true}
}

Every recommended id is validated against your roster (one corrective retry server-side); recommendation_grounded: false flags a recommendation that could not be grounded — it is never silently fabricated. estimate prices the recommended run with the same estimator as POST /v1/completion/estimate and may be absent when the setup cannot be priced.