REST API

The Chucky service provides a REST endpoint for one-shot prompts. This is useful when you don’t need a persistent WebSocket session.

For multi-turn conversations or streaming with tools, use the WebSocket API instead.

Endpoint

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

Request

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`Accept`	No	Response format: `text/event-stream` for SSE, `application/json` for JSON (default)

Body

{
  "message": "What is the capital of France?",
  "options": {
    "token": "your-jwt-token",
    "model": "claude-sonnet-4-5-20250929",
    "systemPrompt": "You are a helpful assistant.",
    "maxTurns": 5
  }
}

Options

Field	Type	Required	Description
`token`	`string`	Yes	JWT authentication token
`model`	`string`	No	Claude model (default: `claude-sonnet-4-5-20250929`)
`systemPrompt`	`string`	No	System prompt for Claude
`tools`	`array`	No	Tool definitions
`allowedTools`	`string[]`	No	Whitelist of allowed tools
`disallowedTools`	`string[]`	No	Blacklist of blocked tools
`maxTurns`	`number`	No	Maximum conversation turns
`maxBudgetUsd`	`number`	No	Max cost for this request
`maxThinkingTokens`	`number`	No	Max tokens for extended thinking
`outputFormat`	`object`	No	Structured output schema
`mcpServers`	`object`	No	MCP server configurations

Response Formats

JSON Response (Default)

When Accept: application/json or no Accept header:

{
  "result": {
    "type": "result",
    "subtype": "success",
    "text": "The capital of France is Paris.",
    "total_cost_usd": 0.0012,
    "duration_secs": 1.5,
    "usage": {
      "input_tokens": 50,
      "output_tokens": 20
    }
  },
  "messages": [
    {
      "type": "assistant",
      "subtype": "text",
      "text": "The capital of France is Paris."
    },
    {
      "type": "result",
      "subtype": "success",
      "text": "The capital of France is Paris.",
      "total_cost_usd": 0.0012
    }
  ],
  "sessionId": "550e8400-e29b-41d4-a716-446655440000"
}

SSE Response (Streaming)

When Accept: text/event-stream:

event: message
data: {"type":"assistant","subtype":"text","text":"The capital of "}

event: message
data: {"type":"assistant","subtype":"text","text":"France is Paris."}

event: message
data: {"type":"result","subtype":"success","text":"The capital of France is Paris.","total_cost_usd":0.0012}

event: done
data: {"sessionId":"550e8400-e29b-41d4-a716-446655440000"}

Error Responses

Authentication Errors

{
  "error": "Token expired"
}

Status: 401 Unauthorized

Budget Exceeded

{
  "error": "user_budget_exhausted",
  "ai": {
    "used": 1000000,
    "remaining": 0,
    "budget": 1000000
  },
  "compute": {
    "used": 3600,
    "remaining": 0,
    "budget": 3600
  }
}

Status: 429 Too Many Requests

Concurrency Limit

{
  "error": "concurrent_limit_reached",
  "active": 5,
  "max": 5,
  "sessions": [
    { "sessionId": "abc123", "userId": "user1", "ageMs": 45000 }
  ]
}

Status: 429 Too Many Requests

Developer Budget Exceeded

{
  "error": "developer_budget_exhausted",
  "used": 500000,
  "available": 0,
  "planSeconds": 500000,
  "poolSeconds": 0
}

Status: 402 Payment Required

Examples

cURL - JSON Response

curl -X POST https://conjure.chucky.cloud/prompt \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "message": "What is 2 + 2?",
    "options": {
      "token": "your-jwt-token"
    }
  }'

cURL - SSE Streaming

curl -X POST https://conjure.chucky.cloud/prompt \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "message": "Write a haiku about coding",
    "options": {
      "token": "your-jwt-token",
      "model": "claude-sonnet-4-5-20250929"
    }
  }'

JavaScript - Fetch with JSON

const response = await fetch('https://conjure.chucky.cloud/prompt', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    message: 'Explain quantum computing briefly',
    options: {
      token: 'your-jwt-token',
      model: 'claude-sonnet-4-5-20250929',
    },
  }),
});

const data = await response.json();
console.log(data.result.text);

JavaScript - SSE Streaming

const response = await fetch('https://conjure.chucky.cloud/prompt', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream',
  },
  body: JSON.stringify({
    message: 'Write a short story',
    options: { token: 'your-jwt-token' },
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.type === 'assistant' && data.subtype === 'text') {
        process.stdout.write(data.text);
      }
    }
  }
}

Python - Requests

import requests

response = requests.post(
    'https://conjure.chucky.cloud/prompt',
    headers={
        'Content-Type': 'application/json',
        'Accept': 'application/json',
    },
    json={
        'message': 'What is the meaning of life?',
        'options': {
            'token': 'your-jwt-token',
        },
    },
)

data = response.json()
print(data['result']['text'])

Comparison: REST vs WebSocket

Feature	REST `/prompt`	WebSocket `/ws`
Multi-turn conversations	No	Yes
Session persistence	No	Yes
Streaming	SSE only	Full duplex
Client-side tools	Limited	Full support
Best for	Simple one-shot queries	Interactive apps

REST API

WebSocket API

​REST API

​Endpoint

​Request

​Headers

​Body

​Options

​Response Formats

​JSON Response (Default)

​SSE Response (Streaming)

​Error Responses

​Authentication Errors

​Budget Exceeded

​Concurrency Limit

​Developer Budget Exceeded

​Examples

​cURL - JSON Response

​cURL - SSE Streaming

​JavaScript - Fetch with JSON

​JavaScript - SSE Streaming

​Python - Requests

​Comparison: REST vs WebSocket

REST API

Endpoint

Request

Headers

Body

Options

Response Formats

JSON Response (Default)

SSE Response (Streaming)

Error Responses

Authentication Errors

Budget Exceeded

Concurrency Limit

Developer Budget Exceeded

Examples

cURL - JSON Response

cURL - SSE Streaming

JavaScript - Fetch with JSON

JavaScript - SSE Streaming

Python - Requests

Comparison: REST vs WebSocket