Work Item API
Welcome to the Sema4.ai Work Item API documentation. This API allows you to create, manage, and monitor work items for AI agents in your workspace. Work items represent autonomous tasks that agents can execute, providing a powerful way to integrate Sema4.ai's Worker Agents into your applications and workflows.
Work Item API is available in Sema4.ai Enterprise Edition in AWS.
Getting started
All API requests should be made to the following URL:
https://{endpoint_url}/api/v1/work-items
Replace {endpoint_url}
with your endpoint URL, that's available in Control Room.
Example:
https://ace.dev.sema4ai.work/tenants/b7c51f2e-89ad-4e62-bf13-9a8d0c7f5e1d/api/v1/work-items
Finding your Endpoint URL
To find your endpoint URL, follow these steps:
- Log in to Control Room.
- Navigate to the Workspace and click on the API Keys tab.
- Click the Copy Endpoint URL button to copy the endpoint URL to your clipboard.
Authentication
To use the Sema4.ai Work Item API, you need to authenticate your requests using an API key. The Work Item API uses Bearer Token
as the authentication framework. If using a tool like Postman to work with the API, select Bearer Token
as the Auth Type in the Authorization tab.
All API requests must include the Authorization
header for authentication.
Example:
Authorization: Bearer your_api_key_here
Finding your API key
You can create and manage API keys in Control Room.
- Log in to Control Room.
- Navigate to the Workspace and click on the API Keys tab.
- Create a new API Key by providing a name and selecting permissions.
Clicking on any created API key will open a window displaying your Bearer Token.
Common examples
Let's walk through some common operations you can perform with the Sema4.ai Work Item API.
Create a work item
To create a new work item for an agent, you can make a POST request to the /work-items
endpoint.
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items' \
--header 'Authorization: Bearer your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": "{agent_id}",
"payload": {
"invoice_id": "ABC123",
"priority": "high"
},
"messages": [
{
"role": "user",
"content": [
{
"kind": "text",
"text": "Please process this invoice for payment approval"
}
]
}
]
}'
This request will create a new work item and return a WorkItem object with details including the work item ID, status, and configuration.
Get work item details
To retrieve details about a specific work item, including its current status and results:
curl --request GET \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}?results=true' \
--header 'Authorization: Bearer your_api_key_here'
Replace {work_item_id}
with the actual work item ID. The results=true
parameter includes the work item's message history and results.
Upload file and create work item workflow
This example demonstrates the complete workflow of uploading a file first (which creates a PRECREATED work item), then finalizing that work item with messages and payload data.
Step 1: Upload a file to create a PRECREATED work item
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/upload-file' \
--header 'Authorization: Bearer your_api_key_here' \
--form 'file=@invoice.pdf'
This returns a work item ID in PRECREATED state:
{
"work_item_id": "wi_abc123def456"
}
Step 2: Optionally upload additional files to the same work item
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/upload-file' \
--header 'Authorization: Bearer your_api_key_here' \
--form 'file=@supporting_document.pdf' \
--form 'work_item_id=wi_abc123def456'
Step 3: Finalize the work item with agent assignment, payload, and messages
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items' \
--header 'Authorization: Bearer your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
"work_item_id": "wi_abc123def456",
"agent_id": "invoice_processing_agent",
"payload": {
"priority": "high",
"department": "accounting",
"approval_required": true
},
"messages": [
{
"role": "user",
"content": [
{
"kind": "text",
"text": "Please process this invoice for payment approval. Check for accuracy and ensure all required fields are completed."
}
]
}
],
"callbacks": [
{
"url": "https://your-app.com/webhooks/work-item-completed",
"on_status": "COMPLETED"
}
]
}'
This request will:
- Take the existing PRECREATED work item with uploaded files
- Assign it to the specified agent
- Add the payload data and initial messages
- Set up webhook callbacks for status updates
- Move the work item from PRECREATED to PENDING status for agent processing
The response will be a complete WorkItem object with all the files, messages, and configuration ready for the agent to begin processing.
This workflow is ideal when you need to collect multiple files or prepare context before submitting work to an agent. Files can only be attached during the PRECREATED state.
List work items
To retrieve a list of work items, optionally filtered by agent:
curl --request GET \
--url 'https://{endpoint_url}/api/v1/work-items?agent_id={agent_id}&limit=50' \
--header 'Authorization: Bearer your_api_key_here'
This request will return a paginated list of work items for the specified agent.
Additional examples
The Sema4.ai Work Item API offers comprehensive functionality for managing work item lifecycles. Here's a brief overview of these capabilities:
Continue a paused work item
Resume a work item that has been paused or requires human intervention:
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/continue' \
--header 'Authorization: Bearer your_api_key_here'
Restart a work item
Reset a work item back to its initial state and restart processing:
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/restart' \
--header 'Authorization: Bearer your_api_key_here'
Cancel a work item
Cancel a work item that is no longer needed:
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/cancel' \
--header 'Authorization: Bearer your_api_key_here'
Mark work item as complete
Administratively mark a work item as completed:
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/complete' \
--header 'Authorization: Bearer your_api_key_here'
Work items support various status transitions and file attachments, making them ideal for complex, document-centric workflows.
Complete API reference
This section provides detailed information about all available endpoints in the Sema4.ai Work Item API.
Work Items
Create work item
POST /work-items
Creates a new work item for a specific agent.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
agent_id | body | string | Yes | ID of the agent to process this work item |
payload | body | object | No | Custom data payload for the work item |
messages | body | array | No | Initial messages to provide context |
callbacks | body | array | No | Webhook callbacks for status updates |
work_item_id | body | string | No | Existing work item ID (for updating pre-created items) |
Request Example
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items' \
--header 'Authorization: Bearer your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": "{agent_id}",
"payload": {"invoice_id": "ABC123", "priority": "high"},
"messages": [
{
"role": "user",
"content": [{"kind": "text", "text": "Please process this invoice for payment approval"}]
}
]
}'
Response
{
"work_item_id": "string",
"agent_id": "string",
"status": "string",
"payload": {},
"messages": [],
"callbacks": [],
"created_by": "string",
"user_id": "string",
"work_item_url": "string"
}
Return Type: WorkItem
Field | Type | Description |
---|---|---|
work_item_id | string | Unique identifier for the work item |
agent_id | string | ID of the agent processing this work item |
status | string | Current status of the work item |
payload | object | Custom data payload |
messages | array | Messages associated with the work item |
callbacks | array | Configured webhook callbacks |
created_by | string | ID of the user who created the work item |
user_id | string | ID of the work item owner |
work_item_url | string | URL to view the work item in Work Room |
Callbacks Parameter Details
The callbacks
parameter allows you to configure webhook notifications that will be triggered when the work item reaches specific statuses. Each callback object must include:
Field | Type | Required | Description |
---|---|---|---|
url | string | Yes | The webhook URL to call when the status is reached |
on_status | string | Yes | The work item status that triggers this callback |
Callback Validation Rules:
- Each callback must have a valid URL
- Only one callback per status is allowed
- Duplicate status callbacks will result in a 400 Bad Request error
Supported Status Values:
PENDING
- Work item is queued for processingEXECUTING
- Work item is currently being processed by an agentPAUSED
- Work item processing has been paused (requires human intervention)COMPLETED
- Work item has been successfully completedFAILED
- Work item processing has failedCANCELLED
- Work item has been cancelled
Request Example with Callbacks
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items' \
--header 'Authorization: Bearer your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": "{agent_id}",
"payload": {
"invoice_number": "INV-2024-001",
"priority": "high",
"department": "accounting"
},
"messages": [
{
"role": "user",
"content": [
{
"kind": "text",
"text": "Process this invoice and extract key information for approval workflow"
}
]
}
],
"callbacks": [
{
"url": "https://your-app.com/webhooks/work-item-completed",
"on_status": "COMPLETED"
},
{
"url": "https://your-app.com/webhooks/work-item-failed",
"on_status": "FAILED"
},
{
"url": "https://your-app.com/webhooks/work-item-paused",
"on_status": "PAUSED"
}
]
}'
Callback Webhook Payload
When a work item reaches the specified status, Sema4.ai will send a POST request to your callback URL with the following payload:
{
"work_item_id": "{work_item_id}",
"status": "COMPLETED",
"agent_id": "{agent_id}",
"timestamp": "2024-01-15T10:30:00Z",
"payload": {
"invoice_number": "INV-2024-001",
"priority": "high",
"department": "accounting"
}
}
Callback Error Handling
- Callbacks will be retried up to 3 times with exponential backoff
- Your webhook endpoint should return a 2xx status code to acknowledge receipt
- Failed callbacks will be logged but will not affect work item processing
Example: Simple Completion Notification
For basic completion tracking, you might only need a single callback:
{
"agent_id": "{agent_id}",
"payload": {"document_type": "contract"},
"callbacks": [
{
"url": "https://api.yourcompany.com/work-items/completed",
"on_status": "COMPLETED"
}
]
}
Example: Comprehensive Status Monitoring
For full lifecycle monitoring, configure callbacks for multiple statuses:
{
"agent_id": "{agent_id}",
"payload": {"workflow_id": "wf_789"},
"callbacks": [
{
"url": "https://monitoring.yourcompany.com/work-items/started",
"on_status": "EXECUTING"
},
{
"url": "https://monitoring.yourcompany.com/work-items/needs-attention",
"on_status": "PAUSED"
},
{
"url": "https://monitoring.yourcompany.com/work-items/completed",
"on_status": "COMPLETED"
},
{
"url": "https://monitoring.yourcompany.com/work-items/failed",
"on_status": "FAILED"
}
]
}
Response
{
"work_item_id": "string",
"agent_id": "string",
"status": "string",
"payload": {},
"messages": [],
"callbacks": [
{
"url": "string",
"on_status": "string"
}
],
"created_by": "string",
"user_id": "string",
"work_item_url": "string"
}
#### Get work item
`GET /work-items/{work_item_id}`
Retrieves details of a specific work item.
**Parameters**
| Parameter | In | Type | Required | Description |
| ------------ | ----- | ------- | -------- | ---------------------------------------------- |
| work_item_id | path | string | Yes | Work item ID |
| results | query | boolean | No | Whether to include the results and messages |
**Request Example**
```bash
curl --request GET \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}?results=true' \
--header 'Authorization: Bearer your_api_key_here'
Response
The response is a single WorkItem object with the same structure as the create response.
List work items
GET /work-items
Lists work items with optional filtering.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
agent_id | query | string | No | Filter by agent ID |
limit | query | int | No | Maximum number of items to return (default: 100) |
offset | query | int | No | Offset for pagination (default: 0) |
created_by | query | string | No | Filter by creator user ID |
Request Example
curl --request GET \
--url 'https://{endpoint_url}/api/v1/work-items?agent_id={agent_id}&limit=50' \
--header 'Authorization: Bearer your_api_key_here'
Response
{
"records": [
{
"work_item_id": "string",
"agent_id": "string",
"status": "string",
"work_item_url": "string"
}
],
"next_offset": 50
}
Upload file
POST /work-items/upload-file
Uploads a file to a work item or creates a new work item if none specified.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
file | form | UploadFile | Yes | File to upload or filename for remote upload |
work_item_id | form | string | No | Existing work item ID (creates new if omitted) |
Request Example
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/upload-file' \
--header 'Authorization: Bearer your_api_key_here' \
--form 'file=@document.pdf' \
--form 'work_item_id={work_item_id}'
Response
{
"work_item_id": "string",
"upload_url": "string",
"upload_form_data": {},
"file_id": "string",
"file_ref": "string"
}
Continue work item
POST /work-items/{work_item_id}/continue
Resumes a paused or stopped work item.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
work_item_id | path | string | Yes | Work item ID |
Request Example
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/continue' \
--header 'Authorization: Bearer your_api_key_here'
Restart work item
POST /work-items/{work_item_id}/restart
Resets and restarts a work item from the beginning.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
work_item_id | path | string | Yes | Work item ID |
Request Example
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/restart' \
--header 'Authorization: Bearer your_api_key_here'
Cancel work item
POST /work-items/{work_item_id}/cancel
Cancels a work item, preventing further processing.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
work_item_id | path | string | Yes | Work item ID |
Request Example
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/cancel' \
--header 'Authorization: Bearer your_api_key_here'
Response
{
"status": "ok"
}
Complete work item
POST /work-items/{work_item_id}/complete
Administratively marks a work item as completed.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
work_item_id | path | string | Yes | Work item ID |
Request Example
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/complete' \
--header 'Authorization: Bearer your_api_key_here'
Response
{
"status": "ok"
}
Confirm file upload
POST /work-items/{work_item_id}/confirm-file
Confirms a remote file upload to a work item.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
work_item_id | path | string | Yes | Work item ID |
file_ref | body | string | Yes | File reference name |
file_id | body | string | Yes | Uploaded file ID |
Request Example
curl --request POST \
--url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/confirm-file' \
--header 'Authorization: Bearer your_api_key_here' \
--header 'Content-Type: application/json' \
--data '{
"file_ref": "document.pdf",
"file_id": "file_123"
}'
Response
{
"work_item_id": "string"
}
Response codes
The Sema4.ai Work Item API uses standard HTTP response codes to indicate the success or failure of an API request. Here's an overview of the response codes you might encounter:
Success codes
- 200 OK: The request was successful. The response body will contain the requested data.
- 201 Created: The request was successful and a new resource was created. This is typically the response for POST requests that create new work items.
- 204 No Content: The request was successful, but there is no content to send back. This is often the response for successful status update requests.
Client error codes
- 400 Bad Request: The request was invalid or cannot be served. This occurs when the request payload is malformed, missing required parameters, or when attempting invalid status transitions.
- 401 Unauthorized: Authentication failed or user doesn't have permissions for the requested operation.
- 403 Forbidden: The request is understood, but it has been refused or access is not allowed. This may occur if work items are disabled.
- 404 Not Found: The requested resource could not be found. This is often returned when an invalid work item ID or agent ID is provided.
- 412 Precondition Failed: The request cannot be completed due to the current state of the work item. This occurs when attempting invalid status transitions.
- 422 Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors. This often occurs when the request payload doesn't meet the expected format or content.
Server error codes
- 500 Internal Server Error: A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
- 503 Service Unavailable: The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.
Error handling
The API uses standard HTTP status codes to indicate the success or failure of requests. In case of errors, additional information may be provided in the response body.
Common error codes
- 400 Bad Request: The request was invalid or cannot be served.
- 401 Unauthorized: The request requires authentication.
- 403 Forbidden: The server understood the request but refuses to authorize it.
- 404 Not Found: The requested resource could not be found.
- 412 Precondition Failed: The request cannot be completed due to the current state of the resource.
- 422 Unprocessable Entity: The request was well-formed but was unable to be followed due to semantic errors.
- 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request.
Error response format
{
"error": {
"code": "string",
"message": "string",
"details": {
"field": "string",
"issue": "string"
}
}
}
Work items can only have files attached when they are in the PRECREATED status. Ensure files are uploaded before transitioning the work item to other states.