API Conventions

Overview

All API endpoints follow consistent conventions for response formats, status codes, and error handling. This page documents what to expect when making requests to the API.

Request Headers

All API requests require the following headers:

curl -X POST https://api.confident-ai.com/v1/... \
  -H "CONFIDENT_API_KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Response Format

All API responses follow a consistent JSON structure:

Success response

{
  "success": true,
  "data": {
    // Response payload specific to the endpoint
  },
  "deprecated": false,
  "link": "https://app.confident-ai.com/..."
}

Error response

{
  "success": false,
  "error": "Error message describing what went wrong",
  "deprecated": false
}

HTTP Status Codes

The Confident API uses standard HTTP status codes to indicate the success or failure of requests.

Success codes

Client error codes

Server error codes

Rate Limits

The API allows 4,000 requests per minute per organization. The limit is shared by all of the organization's API keys and its members' sessions in the Confident AI app. Every response to an authenticated request includes headers that show where you stand in the current window:

Once your organization goes over, requests return 429 with a Retry-After header (in seconds) until the window resets:

{
  "success": false,
  "error": "Rate limit exceeded for this organization. Please retry after 42 seconds.",
  "deprecated": false
}

When you get a 429, wait for Retry-After before sending more requests.

Failed authentication

Requests with an invalid API key are limited separately, by IP address. After 30 failed attempts from the same IP within 5 minutes, every request from that IP that includes an API key returns 429 until the 5 minutes are up, even with a valid key.

Trace storage limit

The trace ingestion endpoints also count the size of every request toward your project's Trace Storage usage limit. Once a project reaches it, every trace request returns 429 until the next billing cycle starts or the limit is raised, so retrying doesn't help:

{
  "success": false,
  "error": "Trace storage usage limit reached for this billing cycle. Lower data retention or raise the project's traceStorageLimits to keep ingesting.",
  "deprecated": false,
  "details": {
    "usage": "1",
    "limit": "1"
  }
}

usage and limit are in GB. On the Free plan and during a trial, the limit is 1 GB-month, whatever the project's own limit is set to.

Ensure Forward Compatibility

We may add new fields to the data field of API responses at any time without considering it a breaking change.

To ensure your integration remains stable, your client should ignore unknown fields rather than failing when encountering them.

For example, if today an endpoint returns:

{
  "success": true,
  "data": {
    "testRunId": "abc123"
  },
  "deprecated": false
}

And tomorrow it returns:

{
  "success": true,
  "data": {
    "testRunId": "abc123",
    "newField": "some value"
  },
  "deprecated": false
}

Your client should continue to work without modification. Most JSON parsing libraries handle this by default, but be cautious if you're using strict schema validation.

Deprecation Notices

When an endpoint is deprecated, responses will include "deprecated": true. We recommend:

1. Monitor the deprecated field in all responses
2. Plan to migrate to the recommended alternative before the endpoint is removed

Last updated on October 7, 2026