Agents

GET /agents

List agents

The workspace's agents (live assistants), newest first. A key with an agent allowlist sees only those agents.

Scope: agents:read

Parameters

• limit optional in the query · integer

  Rows per page, 1 to 100.

• cursor optional in the query · string

  The next_cursor of the previous page.

Returns Agent

• id required string

  Id

• name required string

  The agent's display name.

• status required string

  live, paused or retired.

• language required string

  english, arabic or bilingual.

• public_key required string

  The key in the website snippet (pk_...). Not a secret.

• allowed_origins required string[]

  The websites the widget answers on.

• conversations_per_month required integer

  The plan's monthly allowance for this agent.

• created_at optional string

  Created At

• updated_at optional string

  Updated At

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl https://www.bidii.ai/api/v2/agents \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

GET /agents/{agent_id}

Get an agent

One agent by id. An id from another workspace is not found.

Scope: agents:read

Parameters

• agent_id required in the path · string

Returns Agent

• id required string

  Id

• name required string

  The agent's display name.

• status required string

  live, paused or retired.

• language required string

  english, arabic or bilingual.

• public_key required string

  The key in the website snippet (pk_...). Not a secret.

• allowed_origins required string[]

  The websites the widget answers on.

• conversations_per_month required integer

  The plan's monthly allowance for this agent.

• created_at optional string

  Created At

• updated_at optional string

  Updated At

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl https://www.bidii.ai/api/v2/agents/AGENT_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

PATCH /agents/{agent_id}

Update an agent

Change the agent's name or the websites its widget answers on. Other fields (plan, status, prompt) are not writable through the API. The website list follows the dashboard's rules: the same cleaning, the same cap of changes per hour (429 past it), and the same audit entry.

Scope: agents:write

Parameters

• agent_id required in the path · string

Request body

• name optional string

  The agent's display name (1 to 120 characters).

• allowed_origins optional string[]

  The websites the widget answers on, as origins (https://shop.example). An internationalised domain is stored in its DNS form (xn--...).

Returns Agent

• id required string

  Id

• name required string

  The agent's display name.

• status required string

  live, paused or retired.

• language required string

  english, arabic or bilingual.

• public_key required string

  The key in the website snippet (pk_...). Not a secret.

• allowed_origins required string[]

  The websites the widget answers on.

• conversations_per_month required integer

  The plan's monthly allowance for this agent.

• created_at optional string

  Created At

• updated_at optional string

  Updated At

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl -X PATCH https://www.bidii.ai/api/v2/agents/AGENT_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Front desk"}'