Load Cargo

Submit a request for batch processing.

POST /cargo/load

Authentication

This endpoint requires the X-API-Key header with a valid project API key.

-H "X-API-Key: convoy_sk_your_key_here"

See Authentication for details on obtaining API keys.

Request Body

{
  "params": {
    "model": "claude-3-haiku",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Your prompt here"}
    ],
    "system": "Optional system prompt",
    "temperature": 0.7,
    "top_p": 0.9,
    "top_k": 50,
    "stop_sequences": ["STOP"]
  },
  "callback_url": "https://your-server.com/callback",
  "metadata": {
    "order_id": "ord_8842",
    "de_callback_id": "AQICAHh..."
  }
}

Parameters

Getting your results

Every result is stored server-side (30 days by default) regardless of how you submit. You have two delivery options — use either or both:

• Webhook — provide a callback_url and Convoy POSTs the result to you when processing completes (with retries).
• Mailbox — omit callback_url and poll GET /cargo/{cargo_id}/result instead. No public endpoint needed; the cargo terminates at completed/failed.
• Direct AWS delivery — provide a callback object naming a verified AWS connection and Convoy delivers directly: type: "aws_durable_callback" resumes your suspended durable Lambda execution via SendDurableExecutionCallbackSuccess/Failure; type: "aws_sfn_task_token" resumes your Step Functions .waitForTaskToken wait via SendTaskSuccess/Failure; type: "aws_lambda_invoke" invokes your Lambda function asynchronously with the result envelope; type: "aws_eventbridge" publishes an event onto your bus for your rules to fan out; type: "aws_sqs" / type: "aws_kinesis" deliver to your queue or data stream; type: "aws_sfn_start" starts a new state machine execution with the envelope as input; type: "aws_s3" writes the FULL result as an object in your bucket — no size cap, write-only, prefix-scoped. No webhook, no receiver.

The webhook body and the /result body have the same shape, so your parsing code is delivery-agnostic. Even with a callback_url, /result remains available as a fallback (e.g. after callback_failed).

Metadata

Attach your own correlation data to a request with the optional top-level metadata object. Convoy stores it verbatim and echoes it back in the callback payload — it is never interpreted, logged, or indexed. Typical uses: correlating a callback with a record in your system (order_id, trace_id), or carrying a resume token for a workflow engine (e.g. an AWS Lambda durable function callback ID).

Limits (requests that exceed them are rejected with a 422):

Message Format

{
  "role": "user",
  "content": "Message text"
}

Or with content blocks:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Message text"}
  ]
}

Multimodal Content Blocks

Messages can reference uploaded files (images, PDFs, documents, and video) alongside text using image, document, and video content blocks. Upload the file either from your project’s Files tab in the dashboard or programmatically via the Files API (POST /files → presigned direct-to-storage upload → POST /files/{id}/complete), then reference its file_id in the request. Two Files API branches to handle: if POST /files returns an existing identical file (deduplicated: true, upload: null), skip the upload and completion steps and use its id directly; and POST /files/{id}/complete may return 202 (status: "validating") while the malware scan is pending — keep polling while the status is pending and use the file once it reaches ready. A failed status is terminal (e.g. malware detected, checksum mismatch, scan timeout): stop polling and surface the error instead of referencing the file:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "Summarize this document"},
    {"type": "document", "source": {"file_id": "file_0123456789abcdef0123456789abcdef"}}
  ]
}

Only models with the matching capability accept these blocks — look for the Vision, Documents, and Video badges on the models page . Referenced files must be uploaded to the same project and finished processing (status ready); otherwise the request is rejected.

Response

{
  "cargo_id": "cargo_9f4c1b2a3d4e5f60718293a4b5c6d7e8",
  "status": "success",
  "message": "Cargo loaded successfully"
}

Examples

curl

curl -X POST https://api.cnvy.ai/cargo/load \
  -H "Content-Type: application/json" \
  -H "X-API-Key: convoy_sk_your_key_here" \
  -d '{
    "params": {
      "model": "claude-3-haiku",
      "max_tokens": 100,
      "messages": [{"role": "user", "content": "Hello"}]
    },
    "callback_url": "https://example.com/callback"
  }'

Python

import httpx
 
response = httpx.post(
    "https://api.cnvy.ai/cargo/load",
    headers={
        "X-API-Key": "convoy_sk_your_key_here"
    },
    json={
        "params": {
            "model": "claude-3-haiku",
            "max_tokens": 100,
            "messages": [{"role": "user", "content": "Hello"}]
        },
        "callback_url": "https://example.com/callback"
    }
)
 
data = response.json()
cargo_id = data["cargo_id"]
print(f"Submitted: {cargo_id}")

JavaScript

const response = await fetch("https://api.cnvy.ai/cargo/load", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "convoy_sk_your_key_here"
  },
  body: JSON.stringify({
    params: {
      model: "claude-3-haiku",
      max_tokens: 100,
      messages: [{ role: "user", content: "Hello" }]
    },
    callback_url: "https://example.com/callback"
  })
});
 
const { cargo_id } = await response.json();
console.log(`Submitted: ${cargo_id}`);

Errors

Error Response Examples

Missing API Key:

{"detail": "API key required. Include X-API-Key header."}

Invalid API Key:

{"detail": "Invalid API key."}

Inactive Project:

{"detail": "Project is inactive."}

Missing max_tokens (chat request):

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "params"],
      "msg": "Value error, max_tokens is required for chat requests"
    }
  ]
}

Invalid Model ID:

{
  "detail": {
    "error": "invalid_model",
    "message": "Unknown model: claude-4-turbo",
    "supported_models": ["claude-3-haiku", "claude-3-sonnet", "claude-3-opus", "..."]
  }
}