Durable batch processing orchestrations with pause/resume support
openapi: 3.0.0
info:
description: Unified API for QuantCDN Admin and QuantCloud Platform services
title: QuantCDN AI Agents AI Orchestrations API
version: 4.15.8
servers:
- description: QuantCDN Public Cloud
url: https://dashboard.quantcdn.io
- description: QuantGov Cloud
url: https://dash.quantgov.cloud
security:
- BearerAuth: []
tags:
- description: Durable batch processing orchestrations with pause/resume support
name: AI Orchestrations
paths:
/api/v3/organizations/{organisation}/ai/orchestrations:
get:
description: "List durable orchestrations for an organization with optional filtering.\n *\n * **Note:** This is different from `/tools/orchestrations` which handles async tool execution\n * polling. These durable orchestrations are for long-running batch processing loops.\n *\n * **Filter Options:**\n * - `status`: Filter by orchestration status\n * - `limit`: Max results (default 20, max 100)\n * - `cursor`: Pagination cursor"
operationId: listOrchestrations
parameters:
- description: The organisation machine name
explode: false
in: path
name: organisation
required: true
schema:
type: string
style: simple
- description: Filter by orchestration status
explode: true
in: query
name: status
required: false
schema:
enum:
- pending
- running
- paused
- completed
- failed
- cancelled
type: string
style: form
- description: Maximum number of results
explode: true
in: query
name: limit
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
style: form
- description: Pagination cursor from previous response
explode: true
in: query
name: cursor
required: false
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/listOrchestrations_200_response'
description: List of orchestrations
'403':
description: Access denied
'500':
description: Failed to list orchestrations
summary: List Durable Orchestrations
tags:
- AI Orchestrations
post:
description: "Create a new durable orchestration for batch processing.\n *\n * **Input Sources:**\n * - `static`: Process a fixed list of items\n * - `task_query`: Process tasks matching a query\n * - `generator`: AI generates items from a prompt\n *\n * **Stop Conditions:**\n * - `all_complete`: Stop when all items processed\n * - `max_iterations`: Stop after N iterations\n * - `condition`: AI evaluates a prompt to decide\n * - `manual`: Run until manually stopped\n *\n * **Auto-start:**\n * By default, the orchestration starts immediately. Set `autoStart: false` to create in pending state."
operationId: createOrchestration
parameters:
- description: The organisation machine name
explode: false
in: path
name: organisation
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createOrchestration_request'
required: true
responses:
'201':
content:
application/json:
schema:
type: object
description: Orchestration created
'400':
description: Invalid request
'403':
description: Access denied
'500':
description: Failed to create orchestration
summary: Create Durable Orchestration
tags:
- AI Orchestrations
/api/v3/organizations/{organisation}/ai/orchestrations/{orchestrationId}:
delete:
description: Delete an orchestration. Can only delete orchestrations in completed, failed, or cancelled status.
operationId: deleteOrchestration
parameters:
- description: The organisation machine name
explode: false
in: path
name: organisation
required: true
schema:
type: string
style: simple
- description: Orchestration identifier
explode: false
in: path
name: orchestrationId
required: true
schema:
type: string
style: simple
responses:
'204':
description: Orchestration deleted
'400':
description: Cannot delete active orchestration
'403':
description: Access denied
'404':
description: Orchestration not found
'500':
description: Failed to delete orchestration
summary: Delete Durable Orchestration
tags:
- AI Orchestrations
get:
description: "Get orchestration details including status and progress.\n *\n * **Progress Tracking:**\n * - `total`: Total items to process\n * - `completed`: Successfully processed\n * - `failed`: Failed processing\n * - `pending`: Awaiting processing"
operationId: getOrchestration
parameters:
- description: The organisation machine name
explode: false
in: path
name: organisation
required: true
schema:
type: string
style: simple
- description: Orchestration identifier
example: orch_1704067200_abc123xyz
explode: false
in: path
name: orchestrationId
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
type: object
description: Orchestration details
'403':
description: Access denied
'404':
description: Orchestration not found
'500':
description: Failed to get orchestration
summary: Get Durable Orchestration
tags:
- AI Orchestrations
/api/v3/organizations/{organisation}/ai/orchestrations/{orchestrationId}/start:
post:
description: 'Start a pending orchestration. Only works on orchestrations created with `autoStart: false`.'
operationId: startOrchestration
parameters:
- description: The organisation machine name
explode: false
in: path
name: organisation
required: true
schema:
type: string
style: simple
- description: Orchestration identifier
explode: false
in: path
name: orchestrationId
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
type: object
description: Orchestration started
'400':
description: Orchestration not in pending state
'403':
description: Access denied
'404':
description: Orchestration not found
'500':
description: Failed to start orchestration
summary: Start Durable Orchestration
tags:
- AI Orchestrations
/api/v3/organizations/{organisation}/ai/orchestrations/{orchestrationId}/pause:
post:
description: Pause a running orchestration. The current batch will complete, but no new batches will start. Can be resumed later.
operationId: pauseOrchestration
parameters:
- description: The organisation machine name
explode: false
in: path
name: organisation
required: true
schema:
type: string
style: simple
- description: Orchestration identifier
explode: false
in: path
name: orchestrationId
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
type: object
description: Orchestration paused
'400':
description: Orchestration not running
'403':
description: Access denied
'404':
description: Orchestration not found
'500':
description: Failed to pause orchestration
summary: Pause Durable Orchestration
tags:
- AI Orchestrations
/api/v3/organizations/{organisation}/ai/orchestrations/{orchestrationId}/resume:
post:
description: Resume a paused orchestration. Processing continues from where it left off.
operationId: resumeOrchestration
parameters:
- description: The organisation machine name
explode: false
in: path
name: organisation
required: true
schema:
type: string
style: simple
- description: Orchestration identifier
explode: false
in: path
name: orchestrationId
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
type: object
description: Orchestration resumed
'400':
description: Orchestration not paused
'403':
description: Access denied
'404':
description: Orchestration not found
'500':
description: Failed to resume orchestration
summary: Resume Durable Orchestration
tags:
- AI Orchestrations
/api/v3/organizations/{organisation}/ai/orchestrations/{orchestrationId}/cancel:
post:
description: Cancel an orchestration permanently. Cannot be resumed. Any in-progress items will complete, but no new processing starts.
operationId: cancelOrchestration
parameters:
- description: The organisation machine name
explode: false
in: path
name: organisation
required: true
schema:
type: string
style: simple
- description: Orchestration identifier
explode: false
in: path
name: orchestrationId
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
type: object
description: Orchestration cancelled
'400':
description: Orchestration already completed/cancelled
'403':
description: Access denied
'404':
description: Orchestration not found
'500':
description: Failed to cancel orchestration
summary: Cancel Durable Orchestration
tags:
- AI Orchestrations
/api/v3/organizations/{organisation}/ai/orchestrations/{orchestrationId}/batches:
get:
description: Get history of batches processed by this orchestration. Returns paginated batch records with status and item counts.
operationId: listOrchestrationBatches
parameters:
- description: The organisation machine name
explode: false
in: path
name: organisation
required: true
schema:
type: string
style: simple
- description: Orchestration identifier
explode: false
in: path
name: orchestrationId
required: true
schema:
type: string
style: simple
- description: Maximum number of batches to return
explode: true
in: query
name: limit
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
style: form
- description: Pagination cursor from previous response
explode: true
in: query
name: cursor
required: false
schema:
type: string
style: form
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/listOrchestrationBatches_200_response'
description: Batch history
'403':
description: Access denied
'404':
description: Orchestration not found
'500':
description: Failed to list orchestration batches
summary: List Orchestration Batches
tags:
- AI Orchestrations
components:
schemas:
createOrchestration_request:
properties:
name:
description: Orchestration name
example: Process batch documents
type: string
description:
description: Optional description
nullable: true
type: string
agentId:
description: Agent to process items
nullable: true
type: string
toolId:
description: Tool to execute for items
nullable: true
type: string
workflowId:
description: Workflow to run for items
nullable: true
type: string
inputSource:
$ref: '#/components/schemas/createOrchestration_request_inputSource'
batchSize:
default: 10
description: Items per batch
maximum: 100
minimum: 1
type: integer
concurrency:
default: 1
description: Concurrent items within a batch
maximum: 10
minimum: 1
type: integer
stopCondition:
$ref: '#/components/schemas/createOrchestration_request_stopCondition'
assignedSkills:
description: Skill IDs to assign
items:
type: string
type: array
context:
description: Optional context merged into each item before processing (e.g. shared credentials or endpoints)
nullable: true
type: object
autoStart:
default: true
description: Whether to start immediately
type: boolean
required:
- inputSource
- name
type: object
createOrchestration_request_stopCondition:
properties:
type:
default: all_complete
enum:
- all_complete
- max_iterations
- condition
- manual
type: string
maxIterations:
description: Max iterations (for type=max_iterations)
minimum: 1
type: integer
conditionPrompt:
description: AI prompt to evaluate stop (for type=condition)
type: string
type: object
listOrchestrations_200_response:
example:
nextCursor: nextCursor
orchestrations:
- '{}'
- '{}'
properties:
orchestrations:
items:
type: object
type: array
nextCursor:
nullable: true
type: string
type: object
listOrchestrationBatches_200_response:
example:
nextCursor: nextCursor
batches:
- completedAt: 2000-01-23 04:56:07+00:00
failedCount: 5
orchestrationId: orchestrationId
iteration: 0
startedAt: 2000-01-23 04:56:07+00:00
batchId: batchId
completedCount: 1
error: error
itemCount: 6
status: pending
- completedAt: 2000-01-23 04:56:07+00:00
failedCount: 5
orchestrationId: orchestrationId
iteration: 0
startedAt: 2000-01-23 04:56:07+00:00
batchId: batchId
completedCount: 1
error: error
itemCount: 6
status: pending
properties:
batches:
items:
$ref: '#/components/schemas/listOrchestrationBatches_200_response_batches_inner'
type: array
nextCursor:
nullable: true
type: string
type: object
listOrchestrationBatches_200_response_batches_inner:
example:
completedAt: 2000-01-23 04:56:07+00:00
failedCount: 5
orchestrationId: orchestrationId
iteration: 0
startedAt: 2000-01-23 04:56:07+00:00
batchId: batchId
completedCount: 1
error: error
itemCount: 6
status: pending
properties:
batchId:
type: string
orchestrationId:
type: string
iteration:
type: integer
itemCount:
type: integer
completedCount:
type: integer
failedCount:
type: integer
status:
enum:
- pending
- running
- completed
- failed
type: string
startedAt:
format: date-time
type: string
completedAt:
format: date-time
type: string
error:
nullable: true
type: string
type: object
createOrchestration_request_inputSource:
properties:
type:
description: Input source type (api type not yet supported)
enum:
- static
- task_query
- generator
type: string
items:
description: Static items (for type=static)
items:
type: object
type: array
taskQuery:
description: Task query filters (for type=task_query)
type: object
generatorPrompt:
description: AI prompt (for type=generator)
type: string
required:
- type
type: object
securitySchemes:
BearerAuth:
bearerFormat: JWT
description: 'Enter your Bearer token in the format: `Bearer <your-token-here>`. Obtain your API token from the QuantCDN dashboard under Profile > API Tokens.'
scheme: bearer
type: http