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 (minimum 8 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 an environment (requires environment_id)
  • agents/show - Get agent details (requires agent_id)
  • agents/create - Create a new agent (requires details with environment_id, 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",
      "environment_id": "env_abc123"
    },
    {
      "_type": "agents/create",
      "idempotency_key": "create-agent-2024-01-15-002",
      "details": {
        "environment_id": "env_abc123",
        "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",
        "environment_id": "env_abc123",
        "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.

object
items
required
Items

List of items to process in bulk. Each item will be processed independently in its own transaction.

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., environment_id for agents/list, details for agents/create).

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 at least 8 characters long and unique within the request. Used to identify the result in the response map.

string
>= 8 characters <= 64 characters
Example
create-agent-2024-01-15-001
key
additional properties
any
Example
{
  "_type": "agents/create",
  "details": {
    "description": "Handles customer support inquiries",
    "environment_id": "env_abc123def456",
    "name": "Customer Support Bot"
  },
  "idempotency_key": "create-agent-2024-01-15-001"
}
Example
{
  "items": [
    {
      "_type": "agents/list",
      "environment_id": "env_abc123def456",
      "idempotency_key": "list-agents-2024-01-15-001"
    },
    {
      "_type": "agents/create",
      "details": {
        "description": "Handles customer support inquiries",
        "environment_id": "env_abc123def456",
        "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.

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 output is independent - one item failing does not affect others.

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": {
      "details": {
        "description": "Handles customer support inquiries",
        "environment_id": "env_abc123def456",
        "id": "agent_new123abc456",
        "inserted_at": "2024-01-15T10:30:00Z",
        "name": "Customer Support Bot",
        "type": "agent",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      "status": "success"
    },
    "list-agents-2024-01-15-001": {
      "status": "success",
      "summaries": [
        {
          "environment_id": "env_abc123def456",
          "id": "agent_xyz789ghi012",
          "name": "Existing Agent",
          "type": "agent"
        }
      ]
    },
    "show-agent-2024-01-15-003": {
      "details": {
        "description": "An existing agent",
        "environment_id": "env_abc123def456",
        "id": "agent_xyz789ghi012",
        "inserted_at": "2024-01-10T08:00:00Z",
        "name": "Existing Agent",
        "type": "agent",
        "updated_at": "2024-01-10T08:00:00Z"
      },
      "status": "success"
    }
  },
  "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