Skip to main content
Tasks are a grouping of operations that can be processed together in the registry. There are three common ways tasks are created:
  • Bulk tasks: Process large volumes of resource or relationship operations asynchronously.
  • Bundle tasks: Apply resources and relationships atomically in a single transaction.
  • Object ingestion tasks: Every object creation or deletion request produces a task that tracks OCR pipelines and storage operations.
Bulk tasks are intended to be used for high-throughput operations where you need to create, update, or delete many resources or relationships efficiently. Bundle tasks are useful when you need to ensure that a set of operations either all succeed or all fail together, maintaining data integrity.

​
Overview

The task API workflow consists of two main steps:
  1. Submit a task request - Send a batch of operations using the bulk endpoints. This returns a task ID.
  2. Check task status - Monitor the progress and retrieve results using the task ID.
There is no way to retrieve the task ID after submitting a bulk request. Make sure to store it for later use!

​
At a glance

Bundle APIBulk API (Resources, Relationships)
Use CaseMultiple operations on Resources and RelationshipsOptimizing operations when dealing with large volumes.
ExecutionSynchronousAsynchronous
Supported Operations"CREATE","UPSERT", "DELETE""CREATE","UPSERT", "DELETE"
Atomic TransactionYesNo
Maximum Volume per Request500 KB5 GB

​
Supported bulk operations

The registry supports bulk operations for both resources and relationships:
  • Resource operations: CREATE, UPSERT, or DELETE multiple resources
  • Relationship operations: CREATE, UPSERT, or DELETE multiple relationships
Both are very similar in structure, but the endpoints and payloads differ.

​
Creating a bulk request

​
Bulk resources

Use the bulk resources endpoint to process multiple resource operations: 
curl -X POST "https://$CLINIA_WORKSPACE/sources/my-source/v1/resources/bulk" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "operations": [
    {
      "action": "CREATE",
      "create": {
        "type": "patient",
        "id": "patient-123",
        "data": {
          "name": [
            {
              "given": [
                "John"
              ],
              "family": "Doe"
            }
          ]
        }
      }
    }
  ]
}'

{
  "status": "ACCEPTED",
  "taskId": "bk_30yCPmXLjSOokoLC0B9z5Gs1QCa",
  "bulkId": "bk_30yCPmXLjSOokoLC0B9z5Gs1QCa"
}

​
Bulk relationships

Use the bulk relationships endpoint to process multiple relationship operations: 
curl -X POST "https://$CLINIA_WORKSPACE/sources/my-source/v1/relationships/bulk" \\
-H "X-Clinia-API-Key: $CLINIA_TOKEN" \\
-H "Content-Type: application/json" \\
-d '{
  "operations": [
    {
      "action": "CREATE",
      "create": {
        "type": "treats",
        "from": {
          "type": "practitioner",
          "id": "doctor-123"
        },
        "to": {
          "type": "patient",
          "id": "patient-123"
        }
      }
    }
  ]
}'

{
  "status": "ACCEPTED",
  "taskId": "bk_30yCPmXLjSOokoLC0B9z5Gs1QCa",
  "bulkId": "bk_30yCPmXLjSOokoLC0B9z5Gs1QCa"
}

​
Bundle operations

Use the bundle endpoint to process resources and relationships atomically. If any operation in the bundle fails, none of the operations are applied. 
curl -X POST "https://$CLINIA_WORKSPACE/sources/my-source/v1/bundle" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceOperations": [
    {
      "action": "CREATE",
      "create": {
        "type": "patient",
        "id": "patient-123",
        "data": {
          "name": [
            {
              "given": [
                "John"
              ],
              "family": "Doe"
            }
          ]
        }
      }
    }
  ],
  "relationshipOperations": []
}'

​
Object ingestion tasks

Object collections expose dedicated endpoints that always return a task response. Use the standard task workflow to monitor ingest pipelines and storage: Receipts emitted by these tasks include target.targetType: "OBJECT", allowing you to trace OCR, enrichment, and deletion activity alongside resource tasks.

​
Response format

All task operations return a response with a task ID and status. The status indicates if the task is processed synchronously (PERSISTED) or asynchronously (ACCEPTED). 
{
  "status": "ACCEPTED",
  "taskId": "bd_30sSi7otihHAiRpJ8F1YLpw6kfn"
}

​
Checking task status

Whether you submitted a bulk request or a bundle operation, you can check the status of the task and eventually retrieve the results using the task endpoint. 
curl -X GET "https://$CLINIA_WORKSPACE/sources/my-source/v1/tasks/{taskId}?withReceipts=true" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"

{
  "id": "bulk_abc123",
  "status": "SUCCESS",
  "createdAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:05:30Z",
  "operationReceipts": [
    {
      "status": "SUCCESS",
      "action": "CREATE",
      "target": {
        "targetType": "RESOURCE",
        "type": "patient", 
        "id": "patient-123"
      },
      "receivedAt": "2024-01-15T10:00:01Z",
      "processedAt": "2024-01-15T10:01:15Z"
    }
  ]
}

​
Task statuses

The overall status of the task represents the completion state of all operations in the bulk request. The possible values are:
  • SUCCESS - All the operations of the task completed successfully
  • PENDING - At least one operation in the task is still pending
  • CANCELLED - All the operations in the task were cancelled
  • FAILURE - At least one operations failed or was cancelled
The CANCELLED status can only occur if the operation was cancelled by the system. There is currently no way to cancel a task or an operation manually.For instance, if two tasks are submitted to operate on the same record id, the later task will be kept and the earlier one will be cancelled.
⌘I