Skip to main content
HUMΛN
HUMΛN
←Community
Developer
Developer

An API designed for builders (and the AIs that help them)

HUMΛN Team··12 min·Technical (Developers)

It is 11 p.m. Your coding assistant hits POST /v1/humanos/call with a stale token. The response is 401 Unauthorized and a body that says, essentially, “no.” No pointer to discover. No OpenAPI URL. No hint that a delegation exists. The assistant stops. You open three tabs and start guessing.

That silence is not a docs problem. It is a product defect—and HUMΛN treats it as one.

Exquisite failures are Canon: the platform should orient you toward the next action, not just deny the current one. So that builders—and the AIs helping them—recover without inventing vendor folklore.

Scroll-stopper: An error that only returns a status code has shifted the burden to every integrator, forever.

Three surfaces that make the API self-describing

  1. GET /v1/discover — public “first contact” with authentication guidance, OpenAPI pointer, and common entry routes.
  2. Enriched 401 responses — RFC 7807 ProblemDetails with a discovery block (where to authenticate, where the spec lives).
  3. Global 404 handler — suggestions for nearby routes so typos don’t become archaeology.

Together, they reduce the time from “something broke” to “I know exactly what to do.”

Why first contact matters

Agents and developers share the same onboarding problem: they need a stable map before they can navigate. OpenAPI is that map—but you have to know it exists and where to fetch it.

GET /v1/discover answers “what is this API?” without credentials. It points to /v1/openapi.json, documents bearer-style authentication formats at a high level, and links human-oriented guides where policy requires the long form.

For autonomous tooling, discovery is composable: fetch discover → follow api_reference → generate or validate calls against the spec.

When authentication fails, teach—not just reject

A naked 401 says “no.” A teaching 401 says “no, and here is the keyring.”

Extended ProblemDetails for authentication failures include discovery, for example:

  • platform_info — try GET /v1/discover (no auth).
  • api_reference — GET /v1/openapi.json.
  • authenticate — session or delegation path reminders.
  • guide — human-readable auth documentation.

Coding assistants can parse this block and propose the fix: obtain a delegation token, refresh a session, or open the guide—all without inventing URLs.

404 as a routing hint engine

Typos in paths are universal: pluralization, swapped segments, missing version prefix.

The global not-found handler returns RFC ProblemDetails plus suggestions: a small set of method + path pairs that plausibly match what the caller meant, plus discovery pointers back to OpenAPI and /v1/discover.

It does not pretend to read minds—it narrows search space honestly. That is often enough for humans; for machines, it is structured input to a repair loop (“retry with suggested path”).

Practice: a minimal client recovery loop

  1. On 401, read discovery.authenticate and discovery.guide; never guess vendor-specific OAuth dance from scratch.
  2. On 404, inspect suggestions before broad search.
  3. On cold start, GET /v1/discover once per environment and cache the result with your OpenAPI snapshot version.

Closing

Self-describing APIs are not vanity—they are throughput. They keep humans sovereign (clear escalation to real auth flows) and keep automation honest (verifiable next steps). Ship errors that teach. Ship discovery that needs no secret handshake. The boring integrations become reliable—and the clever ones become possible.

Go deeper

Code & Docs

ctx.call

Agent SDK reference

Capability Routing

Pattern