Skip to main content

Your Key and Agents

Two calls tell an integration, or an AI assistant, what it can do before it does anything: GET /v1/me describes the key you hold, and GET /v1/agents lists the agents it can act on. Every agent endpoint takes an agent's id from that list as its agentId.

How do I check that my key works?​

Call GET /v1/me. It describes the key you hold, its organization and its rate limit; every field is in the Describe the calling key reference.

curl https://api.mojeeb.app/v1/me \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

Any valid key can call it, whatever its scopes, so it is the first call to make with a new key. A 401 with code invalid_api_key means the key is missing, wrong, revoked or expired. A 401 with code internal_server_error means Mojeeb couldn't check the key: retry with backoff, and don't rotate it. See Authentication. The key itself never comes back: the response shows only the fragments of it that the API Keys page shows, so you can tell your keys apart.

How do I find an agent's ID?​

Call GET /v1/agents. It lists the agents your key can act on, newest first.

curl https://api.mojeeb.app/v1/agents \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"

Use an agent's id as the agentId of every agent endpoint, for example /v1/agents/{agentId}/leads. The same id is the agent_id the WhatsApp send endpoints take in the body. See the List agents reference and the Get an agent reference. Getting one agent also returns its settings; see Agent Settings.

You can also copy agent IDs from Your agent IDs on the API Keys page of the dashboard.

Common questions​

Why is an agent missing from the list?​

The key is limited to some agents, the agent was deleted, or it belongs to another organization. A key limited to some agents lists only those, and GET /v1/me shows its agent list as agent_ids; null there means every agent in your organization, including agents added later. A key reaches only the organization shown as organization on GET /v1/me. Deleted agents are never listed.

Is agent_ids on /v1/me the same as the agent list?​

No. agent_ids is the key's setting as stored, so it can still name an agent that was deleted since. GET /v1/agents is the live answer: the agents the key can act on now.

Does /v1/me need a scope?​

No. Its reference page shows x-scope: none: any valid key may call it, because it returns only the key's own details and your organization's id and name. Listing and reading agents needs agents:read, and changing their settings agents:write; every key holds both today.

Can I read or change an agent's instructions through the API?​

Yes. GET /v1/agents/{agentId} returns an agent with its Main Instructions, time zone and AI handoff, and PATCH /v1/agents/{agentId} changes them; see Agent Settings. The list from GET /v1/agents keeps only basic details. Channel switches and follow-up settings have their own endpoints; see Channels and Follow-ups.

Why is there no agent status?​

The status stored on an agent, draft or active, doesn't change how it works today, so the API doesn't show it, and a key can't change it: sending status in PATCH /v1/agents/{agentId} returns 422 field_not_writable. Deleted agents are never listed, and getting one with GET /v1/agents/{agentId} returns 404 agent_not_found.