Skip to main content
bidiDocs Dashboard

API reference

Actions

What an agent can do beyond answering, and what its forms gathered.

All endpoint groups

GET /agents/{agent_id}/actions

List an agent's actions

What the agent can do beyond answering: HTTP calls on verified hosts, collect-data forms, client tools the host page runs, integrations. The headers an HTTP action sends are never returned, only their names.

Scope: agents:read

Parameters

  • agent_id required in the path · string

Returns ActionOut

  • id required string

    Id

  • agent_id required string

    Agent Id

  • name required string

    Name

  • kind required string

    http, collect_data, client_tool or integration.

  • description_en required string

    Description En

  • description_ar required string

    Description Ar

  • method required string

    Method

  • url_template required string

    Url Template

  • host required string

    Host

  • host_verified required boolean

    Host Verified

  • input_schema required object

    Input Schema

  • output_pick required string[]

    Output Pick

  • data_access required string

    Data Access

  • requires_approval required boolean

    Requires Approval

  • enabled required boolean

    Enabled

  • has_headers required boolean

    Has Headers

  • header_names required string[]

    Header Names

  • 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
curl https://www.bidii.ai/api/v2/agents/AGENT_ID/actions \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

POST /agents/{agent_id}/actions

Create an action

A new action, switched off unless enabled is true (an HTTP action switches on only once its host is verified). The plan caps actions per agent (402 plan_required beyond it).

Scope: agents:write

Parameters

  • agent_id required in the path · string

Request body

  • name optional string

    Name

  • kind optional string

    Kind

  • description_en optional string

    Description En

  • description_ar optional string

    Description Ar

  • method optional string

    Method

  • url_template optional string

    Url Template

  • headers optional object

    Headers

  • input_schema optional object

    Input Schema

  • output_pick optional []

    Output Pick

  • data_access optional string

    Data Access

  • requires_approval optional boolean

    Requires Approval

  • enabled optional boolean

    Enabled

  • config optional object

    Config

Returns ActionOut

  • id required string

    Id

  • agent_id required string

    Agent Id

  • name required string

    Name

  • kind required string

    http, collect_data, client_tool or integration.

  • description_en required string

    Description En

  • description_ar required string

    Description Ar

  • method required string

    Method

  • url_template required string

    Url Template

  • host required string

    Host

  • host_verified required boolean

    Host Verified

  • input_schema required object

    Input Schema

  • output_pick required string[]

    Output Pick

  • data_access required string

    Data Access

  • requires_approval required boolean

    Requires Approval

  • enabled required boolean

    Enabled

  • has_headers required boolean

    Has Headers

  • header_names required string[]

    Header Names

  • created_at optional string

    Created At

  • updated_at optional string

    Updated At

Responses

  • 201 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.
  • 402 plan_required: the agent already has as many actions as its plan allows, or the action waits for approval and the plan has no helpdesk; required_plan names the plan to move to. On the plan that holds the most actions there is none: required_plan is absent and the way out is removing one.
  • 409 name_taken: another action of this agent has that name.
curl
curl -X POST https://www.bidii.ai/api/v2/agents/AGENT_ID/actions \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "open_cart", "kind": "client_tool", "description_en": "Open the cart on this page.", "description_ar": "يفتح سلة المشتريات في هذه الصفحة."}'

PATCH /agents/{agent_id}/actions/{action_id}

Update an action

Any field, enabled, or headers (they replace the stored ones; {} removes them).

Scope: agents:write

Parameters

  • agent_id required in the path · string
  • action_id required in the path · string

Request body

  • name optional string

    Name

  • kind optional string

    Kind

  • description_en optional string

    Description En

  • description_ar optional string

    Description Ar

  • method optional string

    Method

  • url_template optional string

    Url Template

  • headers optional object

    Headers

  • input_schema optional object

    Input Schema

  • output_pick optional []

    Output Pick

  • data_access optional string

    Data Access

  • requires_approval optional boolean

    Requires Approval

  • enabled optional boolean

    Enabled

  • config optional object

    Config

Returns ActionOut

  • id required string

    Id

  • agent_id required string

    Agent Id

  • name required string

    Name

  • kind required string

    http, collect_data, client_tool or integration.

  • description_en required string

    Description En

  • description_ar required string

    Description Ar

  • method required string

    Method

  • url_template required string

    Url Template

  • host required string

    Host

  • host_verified required boolean

    Host Verified

  • input_schema required object

    Input Schema

  • output_pick required string[]

    Output Pick

  • data_access required string

    Data Access

  • requires_approval required boolean

    Requires Approval

  • enabled required boolean

    Enabled

  • has_headers required boolean

    Has Headers

  • header_names required string[]

    Header Names

  • 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.
  • 402 plan_required: the action would wait for approval and the plan has no helpdesk; required_plan names the plan to move to.
  • 409 name_taken: another action of this agent has that name.
curl
curl -X PATCH https://www.bidii.ai/api/v2/agents/AGENT_ID/actions/ACTION_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

DELETE /agents/{agent_id}/actions/{action_id}

Delete an action

The action is gone; what its forms gathered goes with it.

Scope: agents:write

Parameters

  • agent_id required in the path · string
  • action_id required in the path · string

Responses

  • 204 Deleted.
  • 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
curl -X DELETE https://www.bidii.ai/api/v2/agents/AGENT_ID/actions/ACTION_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

GET /agents/{agent_id}/actions/{action_id}/calls

List an action's calls

The action's calls in conversations, newest first: when, the outcome, why it failed or was not run, how long it took and the conversation it came from. A request the team approved is one call, with who decided it (their user id). Preview calls are left out. failures_only keeps what failed, was not run, or expired. What it was asked is the names of the action's inputs only, never their values; where the owner's system lives is not here (GET /agents/{agent_id}/actions, agents:read).

Scope: conversations:read

Parameters

  • agent_id required in the path · string
  • action_id required in the path · string
  • 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.

  • failures_only optional in the query · boolean

Returns CallOut

  • id required string

    Id

  • at required string

    At

  • outcome required string

    worked, failed, refused (not run), waiting (for the team's approval), approved, rejected, expired, or sent (asked for approval before this record kept the request).

  • reason optional string

    Why it failed, was refused or expired, as a stable code (timeout, http_status, invalid_input, conversation_cap, closed, ...); null when the record names none.

  • detail required object

    What the reason names: the status a system answered, the inputs that did not fit, the vendor.

  • latency_ms optional integer

    Latency Ms

  • conversation_id optional string

    The conversation it came from, while it exists.

  • ticket_id optional string

    The ticket the team approves a request on.

  • inputs required string[]

    The names of the action's inputs it was called with, never their values.

  • approval optional CallApproval
  • result optional CallResult

    An approved request: how the call went.

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
curl https://www.bidii.ai/api/v2/agents/AGENT_ID/actions/ACTION_ID/calls \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

GET /agents/{agent_id}/submissions

List form submissions

What the agent's collect-data actions gathered in conversations, newest first, each with the conversation it came from.

Scope: leads:read

Parameters

  • agent_id required in the path · string
  • 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.

  • action_id optional in the query · string

Returns SubmissionOut

  • id required string

    Id

  • action required SubmissionAction
  • conversation_id optional string

    Conversation Id

  • data required object

    Data

  • created_at required string

    Created 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
curl https://www.bidii.ai/api/v2/agents/AGENT_ID/submissions \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"