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

1
{
2
  "success": true,
3
  "data": {
4
    // Response payload specific to the endpoint
5
  },
6
  "deprecated": false,
7
  "link": "https://app.confident-ai.com/..."
8
}

Error response

1
{
2
  "success": false,
3
  "error": "Error message describing what went wrong",
4
  "deprecated": false
5
}

HTTP Status Codes

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

Success codes

Client error codes

Server error codes

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:

1
{
2
  "success": true,
3
  "data": {
4
    "testRunId": "abc123"
5
  },
6
  "deprecated": false
7
}

And tomorrow it returns:

1
{
2
  "success": true,
3
  "data": {
4
    "testRunId": "abc123",
5
    "newField": "some value"
6
  },
7
  "deprecated": false
8
}

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