Documentation Index
Fetch the complete documentation index at: https://docs.offloadapi.com/llms.txt
Use this file to discover all available pages before exploring further.
Endpoint
Purpose
Creates a case, stores it with status: "CREATED", and queues async processing for the initial outreach.
Authentication
Request Body
Top-Level Fields
| Field | Type | Required | Notes |
|---|
channel | EMAIL | SMS | Yes | The schema accepts both values, but the implemented workflow is email-based. Use EMAIL. |
goal | object | Yes | Must include objective. |
counterparty | object | Yes | Must include address and name. |
senderPersona | object | Yes | Must include name. |
clientReferenceId | string | No | Your own identifier for joining Offload cases back to your records. |
constraints | string[] | No | Free-form instructions passed into the worker prompts. |
maxAttempts | integer | No | Defaults to 3. This is the number of automated follow-up attempts after the initial outreach. |
followUpDelayHours | integer | No | Defaults to 72. Must be a positive integer. |
resultSchema | object | No | Expected to be JSON Schema-shaped, but only validated as a generic object. |
clientWebhookUrl | string | No | Must be a valid URL. Offload sends async events here if present. |
metadata | object | No | Opaque JSON echoed in webhook payloads. |
goal
| Field | Type | Required | Notes |
|---|
objective | string | Yes | Plain-language outcome you want Offload to reach. |
knowledge | string | object | No | Extra context the worker can use while writing and evaluating messages. |
counterparty
| Field | Type | Required | Notes |
|---|
address | string | Yes | Current implementation uses this as the email recipient. |
name | string | Yes | Human-readable name used in the workflow. |
company | string | No | Optional extra context. |
timezone | string | No | Optional extra context. |
customData | object | No | String-to-string map only. |
senderPersona
| Field | Type | Required | Notes |
|---|
name | string | Yes | Sender name used in prompts. |
role | string | No | Optional role or title. |
company | string | No | Optional company name. |
tone | string | No | Optional tone guidance. |
Example Request
curl -X POST "$OFFLOAD_BASE_URL/cases" \
-H "Content-Type: application/json" \
-H "x-api-key: $OFFLOAD_API_KEY" \
-d '{
"clientReferenceId": "vendor_2048",
"channel": "EMAIL",
"maxAttempts": 3,
"followUpDelayHours": 72,
"goal": {
"objective": "Collect a signed W-9 from the vendor",
"knowledge": {
"vendorName": "Northstar Supplies",
"reason": "AP onboarding"
}
},
"counterparty": {
"address": "ap@northstar.example",
"name": "Maya Chen",
"company": "Northstar Supplies",
"timezone": "America/Los_Angeles",
"customData": {
"vendorId": "vendor_2048"
}
},
"senderPersona": {
"name": "Avery",
"role": "Accounts Payable",
"company": "Example Corp",
"tone": "friendly, concise"
},
"constraints": [
"Email only"
],
"resultSchema": {
"type": "object",
"properties": {
"signedW9Received": { "type": "boolean" },
"receivedAt": { "type": "string" }
},
"required": ["signedW9Received"]
},
"clientWebhookUrl": "https://your-app.example/webhooks/offload",
"metadata": {
"vendorId": "vendor_2048"
}
}'
Successful Response
{
"ok": true,
"data": {
"caseId": "4fc5904d-0e44-4ed3-aa57-c4a47ad0ae4f"
}
}
What Happens Next
After the API returns 201:
- the case exists in storage
- an internal
CASE_CREATED event is queued
- the worker later drafts and sends the initial outreach
- if that send succeeds, the case moves to
RUNNING
Errors
| Status | Code | Meaning |
|---|
400 | INVALID_REQUEST | Malformed JSON or validation failure |
401 | UNAUTHORIZED | Missing or invalid API key |
403 | FORBIDDEN | API key exists but is not active |
429 | USAGE_LIMIT_REACHED | Monthly case cap reached for the current UTC month |
500 | INTERNAL_ERROR | Persistence or queueing failed |
API Gateway also applies route throttling. A platform-generated throttling response may also be 429, but it may not use the standard JSON envelope.
