Agents & channels

Four endpoints on this API do not do anything — they tell you about the workspace you are pointed at. They exist because of a gap the console cannot fill.

Everything else on this API takes an identifier you have to have got from somewhere. POST /messages takes a sender_id. GET /conversations takes an agent_id filter. POST /calls takes an agent_id to assert against. In the console those are things you click. In a deployment script running at 3 a.m. against a customer's workspace, there is no console open and nobody to copy a value out of one.

None of them has a side effect. All four are safe to call on every process start.

Listing agents #

Requires the agents:read scope, which the Create an API key dialog ticks by default. No query parameters.

{
  "items": [
    {
      "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH5",
      "name": "Veloria Support",
      "status": "live",
      "channels": ["web"]
    },
    {
      "agent_id": "bot_01JQRS4T8XZ0AB1CD2EF3GH4",
      "name": "AMC Renewals",
      "status": "draft",
      "channels": []
    }
  ],
  "next_cursor": null
}

Archived agents are left out. The newest agent comes first.

Nothing else is returned. There is no persona, no model configuration, no knowledge base list, no version history, and no deployment detail — those live in the console and have no public REST equivalent. This endpoint answers "which agents exist and what are they called", and that is its whole job.

The envelope, and why it never paginates #

The response uses the same {items, next_cursor} shape as conversations, but next_cursor is always null and there is no limit or cursor parameter. You get every agent in the workspace in one response.

That is deliberate — a workspace has agents in the tens, not the thousands — and it means a generic pagination helper works here without a special case: one page, a null cursor, done. Pagination has that helper written out.

What you use agent_id for #

Two places, and they behave very differently:

• GET /conversations?agent_id=… filters the list to one agent's conversations. A straightforward filter.
• POST /calls with agent_id is an assertion, not a selection. The agent that speaks on an outbound call is resolved from the caller-ID number, not from this field. Sending an agent_id that is not the one deployed to that number returns 412 agent_number_mismatch, and details.deployed_agent_id names the agent that actually is. See Calls.

What this deployment can do #

Requires a valid key and no particular scope. No query parameters.

{
  "message_channels": ["whatsapp"],
  "call_channels": ["voice"],
  "senders": [
    {
      "channel": "whatsapp",
      "sender_id": "was_9f2c41ab77de1063c8a4b512",
      "display_number": "+918047261935",
      "verified_name": "Veloria Home",
      "is_default": true,
      "status": "live"
    }
  ]
}

Senders are listed default first, then by number.

Two different questions #

The two arrays and the sender list answer different things, and conflating them is a real source of confusion:

• message_channels and call_channels are about the deployment. They tell you which capabilities this service carries at all. Asking for a channel that is not in these lists returns 412 failed_precondition with details.reason of unsupported_channel and details.supported naming what is available.
• senders is about the workspace. whatsapp can be in message_channels while senders is empty, which means the capability exists and this workspace has not connected a number to it. A send in that state returns 412 with channel_not_connected.

Both are configuration states, not transient ones. Retrying either is pointless — see Errors.

Checking your key #

Requires a valid key and no particular scope. No parameters, no body, no side effects.

curl https://services.amomic.in/api/v1/ping \
  -H "Authorization: Bearer $AMOMIC_API_KEY"

{
  "ok": true,
  "workspace_id": "ten_01JQRS4T8XZ0AB1CD2EF3GH4",
  "key_name": "Service desk (production)",
  "environment": "live",
  "scopes": ["agents:read", "conversations:read", "messages:send"]
}

This is the first call every integration should make, and it is worth wiring into more than a one-off:

• On deploy. A 200 here proves the secret reached the process, the workspace is in good standing, and the key is not revoked. Three of the most common launch failures are ruled out before any customer-visible request.
• When a 403 surprises you. scopes is the authoritative list. Comparing it against the scope named in details.required_scope turns "permission denied" from a mystery into a one-line diff. See Scopes.
• When a 401 surprises you. details.reason says which check failed: missing_api_key, malformed_api_key, invalid_api_key, revoked_api_key, expired_api_key (a rolled key past its 24 hours) or wrong_environment. See Authentication.

The machine-readable contract #

No key required. This is the only route on /api/v1 that answers an unauthenticated request, because a contract is not a secret and needing a credential to read one makes tooling harder for no security benefit.

curl https://services.amomic.in/api/v1/openapi.json -o amomic-openapi.json

It returns an OpenAPI 3.1 document containing:

• info — title Amomic-AI API, and a description that repeats the two auth header forms and the no-CORS rule.
• servers — the host you fetched it from. Every path in the document already starts with /api/v1. Call the host over https:// whatever scheme this entry shows; the copy published with these docs at https://docs.amomic.in/openapi.json already says https://services.amomic.in.
• paths — every /api/v1 route and nothing else. Console-only routes are filtered out of the document entirely, so what you see is exactly the public surface.
• components.schemas — the request and response models. The list endpoints declare their items without an item schema, so a generated client types them loosely; the item shapes are documented on each endpoint page.
• securitySchemes — ApiKeyBearer (HTTP bearer) and ApiKeyHeader (X-Api-Key), with both offered at the document level.

Two things to do with it:

Generate a client. There are no official SDKs in any language — deliberately, since the API is plain HTTP and JSON. If you want a typed client, generate one from this document rather than hand-rolling models that drift.

Give it to a coding agent. An agent that has the OpenAPI document plus these docs writes a working integration on the first attempt instead of inventing endpoints from a model's memory of "some WhatsApp API". Use with coding agents has the setup for Claude Code, Codex, Cursor, and anything that speaks MCP — including a documentation MCP endpoint and a single-file corpus.

A startup check worth having #

Fifteen lines that turn every configuration failure into one clear log line at boot instead of a confusing 412 during a customer's checkout.

const BASE = "https://services.amomic.in/api/v1";
const HEADERS = { Authorization: `Bearer ${process.env.AMOMIC_API_KEY}` };

async function get(path) {
  const response = await fetch(`${BASE}${path}`, { headers: HEADERS });
  const body = await response.json();
  if (!response.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body;
}

export async function preflight({ requiredScopes = ["messages:send"] } = {}) {
  // 1. Is the credential live, and is it the one we think it is?
  const ping = await get("/ping");
  console.info("amomic_ready", {
    workspace: ping.workspace_id,
    key: ping.key_name,
    environment: ping.environment,
  });

  const missing = requiredScopes.filter((s) => !ping.scopes.includes(s));
  if (missing.length) {
    throw new Error(`API key "${ping.key_name}" is missing scopes: ${missing.join(", ")}`);
  }

  // 2. Can this deployment send at all, and is a sender connected?
  const channels = await get("/channels");
  if (!channels.message_channels.includes("whatsapp")) {
    throw new Error("This deployment cannot send WhatsApp messages.");
  }

  const sender = channels.senders.find((s) => s.channel === "whatsapp" && s.is_default);
  if (!sender) {
    // Enumeration is best-effort — warn, do not crash the process.
    console.warn("amomic_no_default_sender", { senders: channels.senders.length });
  } else if (sender.status !== "live") {
    console.warn("amomic_sender_not_live", { sender_id: sender.sender_id, status: sender.status });
  }

  return { workspaceId: ping.workspace_id, senderId: sender?.sender_id ?? null };
}

Note what it does and does not treat as fatal. A missing scope is fatal — it will fail every send, loudly, forever. A missing sender is a warning, because enumeration is best-effort and refusing to start over a transient provider lookup is worse than starting.

Failures #

There is no 412 on any of them. GET /channels in particular is designed to be the thing you call instead of discovering a missing capability through a 412 on a real send.

Related #