Create Case

Endpoint

POST /cases

Purpose

Creates a case, stores it with status: "CREATED", and queues async processing for the initial outreach.

Authentication

x-api-key: your-api-key

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.

Overview

Endpoints

Endpoint

Purpose

Authentication

Request Body

Top-Level Fields

`goal`

`counterparty`

`senderPersona`

Example Request

Successful Response

What Happens Next

Errors

​Endpoint

​Purpose

​Authentication

​Request Body

​Top-Level Fields

​goal

​counterparty

​senderPersona

​Example Request

​Successful Response

​What Happens Next

​Errors

Endpoint

Purpose

Authentication

Request Body

Top-Level Fields

`goal`

`counterparty`

`senderPersona`

Example Request

Successful Response

What Happens Next

Errors