Skip to content
Prefactor Docs

Execute multiple queries/actions in a single request

POST
/api/v1/bulk

Execute multiple API queries and actions in a single HTTP request. This endpoint allows you to batch multiple operations together, reducing the number of round trips to the API.

Key Features:

  • Each item in the request is processed independently in its own database transaction
  • Processing stops early if any item returns an error
  • All successfully processed items up to the error are returned
  • Any unprocessed items (after the first error) are excluded from the result
  • All items must include a unique idempotency_key (8–128 characters)
  • Results are returned as a map keyed by idempotency_key
  • Each item can be a different type of query or action (e.g., list agents, create agent, show agent)

Supported Types:

  • agents/list - List agents for the account (no extra parameters beyond idempotency_key)
  • agents/show - Get agent details (requires agent_id)
  • agents/create - Create a new agent (requires details with name, optional description)
  • agents/update - Update an agent (requires agent_id and details)
  • environments/list - List environments for an account (requires account_id)
  • environments/show - Get environment details (requires environment_id)
  • environments/create - Create a new environment (requires details with account_id, name)
  • environments/update - Update an environment (requires environment_id and details)
  • And other query/action types as documented in their respective endpoints

Example Request:

{
  "items": [
    {
      "_type": "agents/list",
      "idempotency_key": "list-agents-2024-01-15-001"
    },
    {
      "_type": "agents/create",
      "idempotency_key": "create-agent-2024-01-15-002",
      "details": {
        "name": "Customer Support Bot",
        "description": "Handles customer support inquiries"
      }
    },
    {
      "_type": "agents/show",
      "idempotency_key": "show-agent-2024-01-15-003",
      "agent_id": "agent_xyz789"
    }
  ]
}

Example Response:

{
  "status": "success",
  "outputs": {
    "list-agents-2024-01-15-001": {
      "status": "success",
      "summaries": [...]
    },
    "create-agent-2024-01-15-002": {
      "status": "success",
      "details": {
        "type": "agent",
        "id": "agent_new123",
        "name": "Customer Support Bot",
        "description": "Handles customer support inquiries",
        "inserted_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    },
    "show-agent-2024-01-15-003": {
      "status": "success",
      "details": {...}
    }
  }
}

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Bulk request containing items to process

BulkRequest

Request body for bulk query/action operations. Allows executing multiple API operations in a single request. Each item runs in its own transaction, processing stops at the first error, and any items after the failing item are omitted from the response.

object
items
required
Items

List of items to process in bulk. Each item is processed sequentially in its own database transaction. Processing stops immediately on the first error: the failing item is included in the response as an error entry, and any items after it are not processed and are omitted from the response.

Array<object>
>= 1 items
BulkItem

A single item in a bulk request. Each item must include _type and idempotency_key, plus any additional parameters required by the specific query/action type (e.g., details for agents/create, agent_id for agents/show).

object
_type
required
Type

The type of query/action to execute (e.g., ‘agents/list’, ‘agents/create’)

string
Example
agents/list
idempotency_key
required
IdempotencyKey

Required unique idempotency key for this item. Must be 8–128 characters and unique within the request. Used to identify the result in the response map.

string
>= 8 characters <= 128 characters
Example
create-agent-2024-01-15-001
key
additional properties
any
Example
{
  "_type": "agents/create",
  "details": {
    "description": "Handles customer support inquiries",
    "name": "Customer Support Bot"
  },
  "idempotency_key": "create-agent-2024-01-15-001"
}
Example
{
  "items": [
    {
      "_type": "agents/list",
      "idempotency_key": "list-agents-2024-01-15-001"
    },
    {
      "_type": "agents/create",
      "details": {
        "description": "Handles customer support inquiries",
        "name": "Customer Support Bot"
      },
      "idempotency_key": "create-agent-2024-01-15-002"
    },
    {
      "_type": "agents/show",
      "agent_id": "agent_xyz789ghi012",
      "idempotency_key": "show-agent-2024-01-15-003"
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Success

BulkResponse

Response from bulk query/action operations. Contains a map of results keyed by the idempotency_key from each request item. Processing stops on the first error, so the map includes successful items up to the error plus an error entry for the failing item; items after the failing item are omitted because they were not processed.

object
outputs
Outputs

Map where keys are the idempotency_key values from the request, and values are the corresponding query/action outputs or error responses. Each item is executed in its own transaction and processing stops immediately on the first error: outputs include successful items up to the error plus an error entry for the failing idempotency_key, and items after the failing item are not processed and are omitted from this map.

object
key
additional properties
Output

Output from a query or action. Contains either a success response (with ‘status’: ‘success’ and operation-specific data) or an error response (with ‘status’: ‘error’, ‘code’, ‘message’, and optionally ‘errors’).

object
key
additional properties
any
status
Status

Response status, always ‘success’ when the request is processed

string
Allowed values: success
Example
success
Example
{
  "outputs": {
    "create-agent-2024-01-15-002": {
      "code": "bad_request",
      "message": "Invalid agent details",
      "status": "error"
    },
    "list-agents-2024-01-15-001": {
      "status": "success",
      "summaries": [
        {
          "environment_id": "env_abc123def456",
          "id": "agent_xyz789ghi012",
          "name": "Existing Agent",
          "type": "agent"
        }
      ]
    }
  },
  "status": "success"
}

default

Section titled “default ”

Error

One of:
object
code
string
Allowed values: bad_request bad_authtoken not_authenticated not_permitted not_implemented unknown not_found unexpected_ref_type unexpected invalid_action invalid_value required_value idempotency_key_already_used
Example
bad_request
message
string
status
string
Allowed values: error
Example
error