All API endpoints follow a consistent response format to make integration easier and more predictable.

​
Response Structure

Every API response includes these standard fields:

​
success
boolean
required

Indicates if the request was successful. true for successful requests, false for failures.

​
data
object

Present only on successful requests (success: true). Contains the actual response data.

​
error
string

Present only on failed requests (success: false). Contains a human-readable error message.

​
details
object

Optional field present on failed requests. Contains additional error details or validation errors.

​
status
number
required

The HTTP status code of the response.

​
Success Response

A successful response always has success: true and includes the response data in the data field:

{
    "success": true,
    "data": {
        "agent_id": "agent_123",
        "name": "Example Agent",
        "created_at": "2024-02-07T20:43:00Z"
    },
    "status": 200
}

​
Error Response

Error responses always have success: false and include an error message:

{
    "success": false,
    "error": "Resource not found",
    "status": 404
}

​
Validation Errors

When validation fails, the response includes detailed error information in the details field:

{
    "success": false,
    "error": "Invalid request format",
    "details": {
        "name": {
            "message": "Name is required",
            "path": ["name"]
        },
        "model": {
            "message": "Invalid model. Supported models are: gpt-4o-mini",
            "path": ["model"]
        }
    },
    "status": 400
}

​
Status Codes

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

​
Handling Responses

import requests

response = requests.post('https://www.trytruffle.ai/api/agents', json=data)
result = response.json()

if result['success']:
    # Handle successful response
    agent = result['data']
    print(f"Created agent: {agent['agent_id']}")
else:
    # Handle error
    print(f"Error: {result['error']}")
    if 'details' in result:
        print("Validation errors:", result['details'])