API Reference

Base URL: https://api.cnvy.ai

Interactive API documentation (Swagger UI) is available at: https://api.cnvy.ai/docs 

Authentication

Convoy uses API key authentication. Include your key in the request header:

curl -H "X-API-Key: convoy_sk_your_key_here" https://api.cnvy.ai/cargo/...

See Authentication for details on obtaining API keys from the dashboard.

Cargo Operations

These endpoints require the X-API-Key header with a valid project API key.

Health Check

No authentication required.

Response Format

All responses are JSON. Successful responses return 2xx status codes.

Success Response

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

Error Response

{
  "detail": "Error message describing what went wrong"
}

Common Error Codes

Rate Limits

Convoy uses a token bucket rate limiter designed for batch-shaped traffic. Each organization has a bucket with two parameters:

• Burst capacity — the maximum number of requests you can submit instantly. An idle organization’s bucket refills to full, so you can submit an entire batch in one shot.
• Sustained rate — how fast the bucket refills once the burst allowance is spent, measured in requests per minute.

For example, on the Free plan you can submit 100 prompts back-to-back with no delay, then continue at up to 30 requests/minute. After a quiet period the bucket refills to full and another 100-request burst is available.

Rate limit errors

When the bucket is empty, POST /cargo/load returns 429 with a Retry-After header (seconds) and a JSON body describing the limit:

{
  "detail": {
    "error": "rate_limit_exceeded",
    "message": "Request rate limit exceeded for the free plan (burst of 100 requests, then 30 requests/minute sustained). Retry in 2s, slow down, or upgrade your plan for higher throughput.",
    "plan": "free",
    "burst": 100,
    "sustained_requests_per_minute": 30,
    "requests_per_minute": 30,
    "retry_after_seconds": 2,
    "upgrade_url": "https://cnvy.ai/pricing"
  }
}

sustained_requests_per_minute is the canonical field name; requests_per_minute is a deprecated alias kept for backward compatibility and will be removed in a future release.

Recommended client behavior:

1. Honor the Retry-After header — wait that many seconds and retry.
2. If you’re submitting very large volumes, pace requests at or below your plan’s sustained rate after the initial burst.

Platform backstop

In addition to the plan token bucket, every project is subject to a platform-level backstop limiter. Its limits are configured per deployment via the CONVOY_BACKSTOP_LIMIT_PER_MINUTE (default 6,000) and CONVOY_BACKSTOP_LIMIT_PER_HOUR (default 60,000) environment variables. On the hosted service these sit well above every plan’s limits, so the plan bucket throttles first — but self-hosted deployments may configure lower values, in which case the backstop can impose stricter limits than your plan bucket.

The backstop’s 429 response is different from the plan-limit response above: it is a generic rate-limit error with no plan fields (plan, burst, sustained_requests_per_minute, retry_after_seconds) and no Retry-After header. If you receive a 429 without these fields, back off with your own exponential-backoff schedule rather than relying on a server-provided retry hint.