Incubate API

The Incubate API enables async/deferred prompt execution with built-in concurrency limiting. Unlike the synchronous /prompt endpoint, incubate queues prompts for background execution with status tracking.

Use Incubate for background jobs, scheduled tasks, or when you need concurrency control per developer.

Concurrency Limits

Each developer gets a concurrency limit based on their subscription tier:

Tier	Concurrent Tasks	Plan Seconds
Hobby/Free	2	< 3.5M
Starter	5	>= 3.5M
Pro	10	>= 15M

Concurrency is enforced per-developer across all their projects using concurrencyKey.

Endpoints

Queue a Prompt

POST https://conjure.chucky.cloud/incubate

Queue a prompt for deferred execution.

Request Body

{
  "message": "Generate a report from yesterday's data",
  "idempotencyKey": "report-2024-01-08",
  "options": {
    "token": "your-jwt-token",
    "model": "claude-sonnet-4-5-20250929",
    "maxTurns": 10
  },
  "ttl": 60,
  "callback": {
    "url": "https://your-server.com/webhook",
    "secret": "whsec_xxx"
  }
}

Parameters

Field	Type	Required	Description
`message`	`string`	Yes	The prompt message
`idempotencyKey`	`string`	Yes	Unique key to prevent duplicates (per project)
`options`	`object`	Yes	SDK options including `token`
`ttl`	`number`	No	Delay in seconds before execution
`executeAt`	`string`	No	ISO 8601 timestamp for scheduled execution
`callback`	`object`	No	Webhook for result delivery

Response

{
  "vesselId": "run_abc123xyz",
  "idempotencyKey": "report-2024-01-08",
  "status": "queued",
  "scheduledFor": "2024-01-08T10:00:00.000Z"
}

Check Status

GET https://conjure.chucky.cloud/incubate/vessel/{vesselId}

Poll the status of a queued prompt.

Response - Pending

{
  "vesselId": "run_abc123xyz",
  "status": "QUEUED",
  "taskIdentifier": "chucky-incubate",
  "isCompleted": false,
  "isSuccess": false,
  "isFailed": false,
  "createdAt": "2024-01-08T10:00:00.000Z",
  "updatedAt": "2024-01-08T10:00:01.000Z"
}

Response - Completed

{
  "vesselId": "run_abc123xyz",
  "status": "COMPLETED",
  "taskIdentifier": "chucky-incubate",
  "isCompleted": true,
  "isSuccess": true,
  "isFailed": false,
  "createdAt": "2024-01-08T10:00:00.000Z",
  "updatedAt": "2024-01-08T10:00:30.000Z",
  "startedAt": "2024-01-08T10:00:01.000Z",
  "completedAt": "2024-01-08T10:00:30.000Z",
  "output": {
    "success": true,
    "text": "Here is your generated report...",
    "result": {
      "type": "result",
      "subtype": "success",
      "total_cost_usd": 0.015
    }
  }
}

Response Fields

Field	Description
`vesselId`	Unique run ID for tracking
`status`	Current execution status
`isCompleted`	`true` when execution is complete (success or failure)
`isSuccess`	`true` if completed successfully
`isFailed`	`true` if execution failed
`completedAt`	Timestamp when execution completed
`output`	Result payload (only when `isCompleted: true`)

Status Values

Status	Description
`PENDING`	Waiting to be processed
`QUEUED`	In queue, waiting for capacity
`EXECUTING`	Currently running
`COMPLETED`	Finished successfully (`isCompleted: true`, `isSuccess: true`)
`FAILED`	Execution failed (`isCompleted: true`, `isFailed: true`)
`CANCELED`	Canceled by user

Batch Queue

POST https://conjure.chucky.cloud/incubate/batch

Queue multiple prompts at once (max 100 items).

Request Body

{
  "items": [
    {
      "message": "Analyze document 1",
      "idempotencyKey": "doc-1-analysis"
    },
    {
      "message": "Analyze document 2",
      "idempotencyKey": "doc-2-analysis"
    }
  ],
  "options": {
    "token": "your-jwt-token",
    "model": "claude-sonnet-4-5-20250929"
  },
  "callback": {
    "url": "https://your-server.com/webhook"
  }
}

Response

{
  "total": 2,
  "queued": 2,
  "failed": 0,
  "items": [
    {
      "index": 0,
      "idempotencyKey": "doc-1-analysis",
      "status": "queued",
      "vesselId": "run_abc123"
    },
    {
      "index": 1,
      "idempotencyKey": "doc-2-analysis",
      "status": "queued",
      "vesselId": "run_def456"
    }
  ]
}

Callback Webhooks

When a callback is configured, results are POSTed to your URL upon completion.

Callback Request

{
  "success": true,
  "text": "Generated response text...",
  "result": {
    "type": "result",
    "subtype": "success",
    "total_cost_usd": 0.015,
    "usage": {
      "input_tokens": 500,
      "output_tokens": 200
    }
  }
}

HMAC Verification

If you provide a secret in the callback config, the response includes an HMAC signature:

X-Chucky-Signature: <hmac-sha256-hex>

Verify the signature:

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return signature === expected;
}

Error Responses

Missing Idempotency Key

{
  "error": "missing_idempotency_key",
  "message": "Request body must include \"idempotencyKey\" field"
}

Status: 400 Bad Request

Token Expired

{
  "error": "token_expired"
}

Status: 401 Unauthorized

Developer Budget Exhausted

{
  "error": "developer_budget_exhausted"
}

Status: 402 Payment Required

Trigger Failed

{
  "error": "trigger_failed",
  "message": "Task queue unavailable"
}

Status: 503 Service Unavailable

Examples

cURL - Queue Prompt

curl -X POST https://conjure.chucky.cloud/incubate \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Generate weekly report",
    "idempotencyKey": "weekly-report-2024-w02",
    "options": {
      "token": "your-jwt-token",
      "model": "claude-sonnet-4-5-20250929",
      "maxTurns": 10
    }
  }'

cURL - Check Status

curl https://conjure.chucky.cloud/incubate/vessel/run_abc123xyz

JavaScript - Queue and Poll

// Queue the prompt
const queueResponse = await fetch('https://conjure.chucky.cloud/incubate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'Analyze this dataset',
    idempotencyKey: `analysis-${Date.now()}`,
    options: { token: 'your-jwt-token' },
  }),
});

const { vesselId } = await queueResponse.json();

// Poll for completion
async function waitForCompletion(vesselId, maxWaitMs = 300000) {
  const startTime = Date.now();

  while (Date.now() - startTime < maxWaitMs) {
    const response = await fetch(
      `https://conjure.chucky.cloud/incubate/vessel/${vesselId}`
    );
    const status = await response.json();

    if (status.isCompleted) {
      return status;
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }

  throw new Error('Timeout waiting for completion');
}

const result = await waitForCompletion(vesselId);
console.log(result.output.text);

Python - With Callback

import requests
import hmac
import hashlib

# Queue with callback
response = requests.post(
    'https://conjure.chucky.cloud/incubate',
    json={
        'message': 'Generate summary',
        'idempotencyKey': 'summary-001',
        'options': {'token': 'your-jwt-token'},
        'callback': {
            'url': 'https://your-server.com/webhook',
            'secret': 'your-webhook-secret',
        },
    },
)

print(response.json())

# In your webhook handler:
def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Comparison: /prompt vs /incubate

Feature	`/prompt`	`/incubate`
Execution	Synchronous	Async/deferred
Response	Immediate result	Vessel ID for polling
Concurrency control	Per-developer limit	Per-developer queue
Scheduling	No	Yes (`ttl`, `executeAt`)
Webhooks	No	Yes
Batch support	No	Yes (up to 100)
Best for	Real-time interactions	Background jobs, scheduled tasks

REST API

WebSocket API

Incubate API

Incubate API

Concurrency Limits

Endpoints

Queue a Prompt

Request Body

Parameters

Response

Check Status

Response - Pending

Response - Completed

Response Fields

Status Values

Batch Queue

Request Body

Response

Callback Webhooks

Callback Request

HMAC Verification

Error Responses

Missing Idempotency Key

Token Expired

Developer Budget Exhausted

Trigger Failed

Examples

cURL - Queue Prompt

cURL - Check Status

JavaScript - Queue and Poll

Python - With Callback

Comparison: /prompt vs /incubate

REST API

WebSocket API

​Incubate API

​Concurrency Limits

​Endpoints

​Queue a Prompt

​Request Body

​Parameters

​Response

​Check Status

​Response - Pending

​Response - Completed

​Response Fields

​Status Values

​Batch Queue

​Request Body

​Response

​Callback Webhooks

​Callback Request

​HMAC Verification

​Error Responses

​Missing Idempotency Key

​Token Expired

​Developer Budget Exhausted

​Trigger Failed

​Examples

​cURL - Queue Prompt

​cURL - Check Status

​JavaScript - Queue and Poll

​Python - With Callback

​Comparison: /prompt vs /incubate

Incubate API

Concurrency Limits

Endpoints

Queue a Prompt

Request Body

Parameters

Response

Check Status

Response - Pending

Response - Completed

Response Fields

Status Values

Batch Queue

Request Body

Response

Callback Webhooks

Callback Request

HMAC Verification

Error Responses

Missing Idempotency Key

Token Expired

Developer Budget Exhausted

Trigger Failed

Examples

cURL - Queue Prompt

cURL - Check Status

JavaScript - Queue and Poll

Python - With Callback

Comparison: /prompt vs /incubate