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	No	Max tokens to generate (default: 1024)
`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

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

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

Invalid Model ID:


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