> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chucky.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Incubate API

> Async/deferred prompt execution with concurrency control

# 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.

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

## 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```javascript theme={null}
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

```json theme={null}
{
  "error": "missing_idempotency_key",
  "message": "Request body must include \"idempotencyKey\" field"
}
```

Status: `400 Bad Request`

### Token Expired

```json theme={null}
{
  "error": "token_expired"
}
```

Status: `401 Unauthorized`

### Developer Budget Exhausted

```json theme={null}
{
  "error": "developer_budget_exhausted"
}
```

Status: `402 Payment Required`

### Trigger Failed

```json theme={null}
{
  "error": "trigger_failed",
  "message": "Task queue unavailable"
}
```

Status: `503 Service Unavailable`

## Examples

### cURL - Queue Prompt

```bash theme={null}
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

```bash theme={null}
curl https://conjure.chucky.cloud/incubate/vessel/run_abc123xyz
```

### JavaScript - Queue and Poll

```javascript theme={null}
// 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

```python theme={null}
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 |