https://api2.rulebase.co (or https://eu.api2.rulebase.co on EU) and require a Rulebase API key in the Authorization: Bearer <key> header.
The canonical paths are versioned: /v1/work_items. The older unversioned paths (/work_items) still work, but they answer with Deprecation and Sunset headers and will be removed. Move to /v1 when you next touch the integration.
If you are scripting this from an agent or a CI job, the Rulebase CLI wraps every endpoint below with JSON in and JSON out.
Rate limits
Work item endpoints allow about 5,000 requests per minute per organization. Over that, the API responds with429 Too Many Requests and a Retry-After header giving the seconds to wait. For large volumes, use bulk CSV upload, which carries many rows in one request.
When to use work items vs conversations
Work items preserve the source work record, the responsible employee, customer-specific attributes, and the source-system events. Uploading a work item stores the record and its events; it does not score or evaluate it.
Upload methods
Pick based on how your source system exports data.- Single work item.
POST /v1/work_itemswith a JSON body. For systems that push individual items in real time. It is create-only: a second push of the sameexternal_idreturns409. - JSON batch apply.
POST /v1/work_items/batchwith up to 100 work items in one request. Each item is created, updated, or restored byexternal_id, so it is the endpoint to use when you re-send records you may have sent before. Preferred for agents and scripted backfills. - Bulk CSV upload.
POST /v1/work_items/uploadwith a multipart CSV of many items. For periodic exports out of a system that speaks CSV.
dry_run. CSV upload is asynchronous and reports per-file counts you poll for.
Method 1: single work item
POST /v1/work_items with the work item details as a JSON body:
id is a work item UUID. Fetch it later with GET /v1/work_items/{id}. That path accepts a work item id only; a bulk upload job id returns 404.
Full REST spec: Create a work item.
Method 2: bulk CSV upload
Upload a CSV toPOST /v1/work_items/upload as multipart/form-data:
pending status:
id is an upload job id. Poll it with GET /v1/work_items/upload/{id}:
GET /v1/work_items/{id} with an upload job id. That endpoint looks up a single work item and returns 404 for an upload job.
Poll until the upload reaches a terminal status:
completed: every row succeeded.completed_with_errors: at least one row failed, while valid rows were still imported.failed: the file could not be processed, such as when required headers are missing or storage is unavailable.
external_id values resolve to the same work item.
Bulk upload requirements
- Content-Type:
multipart/form-data - File format: CSV with a header row
- Header row required; column order is flexible
- Maximum file size: 25 MB
Work item schema reference
Customer-specific outcomes and metadata go in
custom_attributes. The keys type, status, and priority are reserved and not stored inside custom_attributes; send type and status as top-level fields.
Incomplete imports (for example notes-only exports) may omit agent, type, and status. Rulebase stores stubs so events can attach; UI shows Unknown agent until you backfill. AI QA scorecards will not apply until an agent is present.
How agents are matched
On receiving a work item, Rulebase looks up the agent against your existing employee records:- Match by
agent_external_idif provided. - Otherwise, match by
agent_email. - If neither matches and an identifier was provided, a new employee is created from the fields you sent.
- If neither agent field is provided, the work item is stored without an agent.
external_id within your organization (PATCH /v1/work_items/{id} instead targets the Rulebase work item ID, and cannot change external_id). Re-sending the same external_id refreshes provided fields from the new payload; omitted/null agent, type, and status preserve existing values so a thin re-upload does not erase a prior backfill. Custom attributes are merged: the new upload wins on shared keys, and keys only on the stored record are kept. There is no separate employee roster API. You enrich employee records through the agent objects you carry on the work items you push.
Name alone will not match or create an agent. Provide agent_email or agent_external_id; agent_name only enriches the matched employee.
CSV column reference
CSV uploads use flat columns that map onto the JSON schema.Status must be one of pending, in_progress, completed, or cancelled, and is normalized to lowercase. On a new work item, blank Status stores pending and blank Type stores unknown; on a re-upload, blank Status and Type preserve their stored values. Completed at is required when Status is completed or cancelled. A blank completion date with pending or in_progress clears a prior completion date, while omitting both the Status and Completed at columns preserves it. Legacy snake_case headers such as external_id, agent_email, and completed_at are also accepted. Any column prefixed with custom_ is flattened into custom_attributes. For example, custom_risk_score becomes custom_attributes.risk_score. The reserved columns custom_type, custom_status, and custom_priority are ignored.
Example CSV
Method 2: JSON batch apply
POST /v1/work_items/batch takes 1-100 work items in a work_items array and applies them in order:
- Statuses are
created,updated,unchanged,restored, orerror. - A failed item does not roll back the items that succeeded; check
summary.error. - Work items you leave out of the request are never deleted.
- Sending an
external_idthat was deleted restores it and reportsrestored. - Set
"dry_run": trueto get the same result shape without writing anything.
Updating and deleting
PATCH /v1/work_items/{id} updates a stored work item. Omitted fields keep their values, custom_attributes merge with the stored ones, and external_id cannot be changed.
DELETE /v1/work_items/{id} soft-deletes a work item. It disappears from reads and lists and stops being summarized, while existing evaluations that reference it keep resolving. The call is idempotent: deleting an already-deleted work item still returns 200 with "deleted": false. There is no hard delete and no bulk delete. To bring a work item back, apply its external_id again.
Listing work items
GET /v1/work_items returns work items newest-completion-first with cursor pagination:
external_id (exact match), status (repeatable), completed_after and completed_before (ISO 8601), and query (substring match on external ID and type). Pass the returned meta.page.next value back as cursor to fetch the next page; it is null on the last page. Deleted work items are excluded.
Retrieving a work item
Fetch a work item by its Rulebase work item id (fromPOST /v1/work_items or a successful import row) with GET /v1/work_items/{id}. For bulk upload progress, use GET /v1/work_items/upload/{id} with the upload job id.
qa_score is null until the work item is evaluated; after a QA evaluation is saved, it holds the current score from 0 to 1.
Adding work item events
Send events inline when creating a work item, or add them later withPOST /v1/work_items/{id}/events. Rulebase upserts events by external_id within your organization.
external_id is required. Actor identity, raw content, and occurred_at are optional. Actors use the same email/external-ID matching behavior as work item agents. GET /v1/work_items/{id} returns events in chronological order.