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.

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:

1. Log in to Control Room.
2. Navigate to the Workspace and click on the API Keys tab.
3. 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.

Example:

Authorization: Bearer your_api_key_here

Finding your API key

You can create and manage API keys in Control Room.

1. Log in to Control Room.
2. Navigate to the Workspace and click on the API Keys tab.
3. 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?work_item_id=wi_abc123def456' \
  --header 'Authorization: Bearer your_api_key_here' \
  --form 'file=@supporting_document.pdf'

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.

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:

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'

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

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

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:

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 processing
• EXECUTING - Work item is currently being processed by an agent
• PAUSED - Work item processing has been paused (requires human intervention)
• COMPLETED - Work item has been successfully completed
• FAILED - Work item processing has failed
• CANCELLED - 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

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

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"
}

Confirm file upload

POST /work-items/{work_item_id}/confirm-file

Confirms a remote file upload to a Work Item.

Parameters

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"
}

Restart Work Item

POST /work-items/{work_item_id}/restart

Resets and restarts a Work Item from the beginning.

Parameters

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

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

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"
}

Work Item Status Management

Work Item Status Reference

Here's a comprehensive table describing all possible states of a Work Item:

Key Notes

• Agent judgement determines success: When an agent finishes processing, it evaluates whether it successfully completed the work. If the agent believes it accomplished the task successfully, it transitions to COMPLETED. If the agent determines it needs human assistance, clarification, or validation, it transitions to NEEDS_REVIEW
• File uploads are only possible during the PRECREATED state
• Callbacks can be configured to trigger on any status change
• Human intervention is typically required for NEEDS_REVIEW and FAILED states
• Final states (COMPLETED, CANCELLED) generally cannot transition to other states without explicit restart actions

Handling NEEDS_REVIEW Status

When a Work Item reaches NEEDS_REVIEW status, it indicates that the agent has encountered a situation requiring human intervention or decision-making. This typically occurs when:

• The agent needs clarification on ambiguous instructions
• External validation is required before proceeding
• The agent has identified potential issues that need human review
• Business rules require human approval at this stage

Option 1: Human Investigation and Completion

When human review determines the work is satisfactory or after manual remediation:

1. Investigate the Work Item by retrieving its current state:

curl --request GET \
  --url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}?results=true' \
  --header 'Authorization: Bearer your_api_key_here'

2. Mark as complete after human review/remediation:

curl --request POST \
  --url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/complete' \
  --header 'Authorization: Bearer your_api_key_here'

This approach is ideal when:

• The agent's work is acceptable as-is
• Minor manual corrections have been made
• Business approval has been obtained

Option 2: Restart for Agent Retry

When you want the agent to attempt the work again (perhaps with updated instructions or after resolving external issues):

curl --request POST \
  --url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/restart' \
  --header 'Authorization: Bearer your_api_key_here'

This approach is ideal when:

• External dependencies have been resolved
• The agent should retry with the same instructions
• Temporary issues have been addressed

Example Workflow for NEEDS_REVIEW:

# 1. Check why the Work Item needs review
curl --request GET \
  --url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}?results=true' \
  --header 'Authorization: Bearer your_api_key_here'
 
# 2a. If human review is sufficient, mark complete
curl --request POST \
  --url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/complete' \
  --header 'Authorization: Bearer your_api_key_here'
 
# OR
 
# 2b. If agent should retry, restart the Work Item
curl --request POST \
  --url 'https://{endpoint_url}/api/v1/work-items/{work_item_id}/restart' \
  --header 'Authorization: Bearer your_api_key_here'

Callback Configuration for NEEDS_REVIEW:

To be notified when Work Items require human attention, configure a callback:

{
  "callbacks": [
    {
      "url": "https://your-app.com/webhooks/needs-review",
      "on_status": "NEEDS_REVIEW"
    }
  ]
}

This ensures your team is immediately notified when Work Items require human intervention, enabling review and resolution.

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"
    }
  }
}