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.

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.