Graine AI
API referencePhone numbers

List inbound agents

List your inbound agents — the applications that answer incoming calls.

List your inbound agents — the applications that answer incoming calls.

An inbound agent binds one of your agents to a destination that phone numbers can be pointed at. Link a number to an application_sid and every call to that number is answered by the bound agent; the link itself is made by Graine when the number is provisioned, and GET /v2/phone-numbers shows which numbers are already routed (is_inbound).

Only applications belonging to your organisation are returned. Applications created outside this API without an organisation stamp are not listed.

The telephony service returns the set in one response, so this endpoint pages in memory, with a ceiling of 500 applications per organisation.

Rate limit: 1000 requests per minute per organization (bucket default). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

GET
/v2/inbound-agents
/v2/inbound-agents?page=1&page_size=20

The Authorization access token

Authorization

Authorization
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Query Parameters

organization_idOrganization Id

Must match the organisation the API key belongs to.

pagePage

1-indexed page number (max 10000 — narrow the window instead)

Default: 1Minimum: 1Maximum: 10000

page_sizePage Size

Items per page (max 100)

Default: 20Minimum: 1Maximum: 100

Response Body

200

A page of inbound applications.

data
Required
Data

This page of inbound applications.

pagination
Required
Pagination

Where this page sits in the result set.

400

1000 — malformed or contradictory input (bad transfer target, bad timeout).

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

402

1400 — the organisation has insufficient credits for this request.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organisation. GET /v2/scopes reports which scopes the key holds.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

422

1001 — the body or query failed validation; the message names the first offending field.

error
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

message
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — per-organisation rate limit exceeded. Carries Retry-After.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

503

1501 — the telephony service is unreachable or returned a 5xx.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

504

1502 — the telephony service did not respond in time.

error
Required
Error

Stable integer code from the /v2 error table.

message
Required
Message

Human-readable single sentence.

curl -X GET "https://api.graine.ai/v2/inbound-agents?organization_id=string&page=1&page_size=20" \
  -H "Authorization: Bearer <token>"

A page of inbound applications.

{
  "data": [
    {
      "application_sid": "817361cd-2a13-4937-b465-686d3f58eddd",
      "name": "Support line",
      "agent_id": "6c6f4cc3-f56c-479d-8422-7f76694daa29"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7,
    "has_more": true
  }
}

Previous

Delete a knowledge base DELETE

Next

List phone numbers GET