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"
}

Parameters

Field	Type	Required	Description
`params.model`	string	Yes	Provider-agnostic model ID (e.g., `claude-3-haiku`)
`params.max_tokens`	integer	Yes (chat)	Max tokens to generate. Required for chat requests (`messages`); ignored for embedding requests (`input_text`). Must be a positive integer
`params.messages`	array	Yes	Conversation messages
`params.system`	string	No	System prompt
`params.temperature`	float	No	Sampling temperature (0.0-1.0)
`params.top_p`	float	No	Top-p sampling (0.0-1.0)
`params.top_k`	integer	No	Top-k sampling
`params.stop_sequences`	array	No	Stop sequences
`callback_url`	string	Yes	URL to receive results

Breaking change: max_tokens is now required for chat requests and no longer defaults to 1024. Requests that omit it are rejected with a 422 validation error ("max_tokens is required for chat requests"). Set it to a realistic ceiling for your workload — it caps the model’s output and is used to estimate the credit hold placed while the batch is in flight, so a tighter value means a smaller hold against your available balance.

See Supported Models for the full list of available model IDs.

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.

Plan availability (Convoy Cloud): file uploads are available on the Starter and Pro plans. On the Free plan, creating files returns 403 files_not_allowed_for_plan and the dashboard shows an upgrade prompt instead of the upload widget — upgrade from Dashboard → Billing to enable uploads. Self-hosted Enterprise deployments are not plan-gated; Files limits come from your license entitlements.

Response


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

Field	Description
`cargo_id`	Unique identifier for tracking
`status`	`success` or `error`
`message`	Result description

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

Status	Description
`400`	Invalid request body or invalid model ID
`401`	Missing or invalid API key
`403`	Project is inactive
`422`	Validation error (e.g. `max_tokens` missing on a chat request)
`500`	Internal server error

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", "..."]
  }
}