Making Requests

This page covers the structure of API requests, responses, and error handling.

Base URL

https://api.custodianai.com/v1

Request format

All requests use JSON as the content type.

POST /v1/process
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "text": "The content you want to process"
}

Response format

A successful response returns a 200 OK with a JSON body:

{
  "result": "Processed output from CustodianAI",
  "characters_used": 312,
  "credits_remaining": 49688
}

Field	Type	Description
result	string	The processed output
characters_used	number	Characters consumed by this request
credits_remaining	number	Character credits left on your key

Error responses

When something goes wrong, the API returns a non-2xx status with a JSON error body:

{
  "error": "character_limit_reached",
  "message": "You have used all available character credits on this plan."
}

Common error codes

Status	Error code	Meaning
401	unauthorized	API key missing or invalid
403	expired	API key has expired
403	character_limit_reached	No credits remaining
403	not_enough_credits	Request requires more credits than available
422	invalid_input	Request body is missing required fields
429	rate_limited	Too many requests — slow down
500	server_error	Something went wrong on our end

Example: full request/response cycle

async function processText(text: string): Promise<string> {
  const response = await fetch('https://api.custodianai.com/v1/process', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CUSTODIAN_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ text }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`CustodianAI error: ${error.error} — ${error.message}`);
  }

  const data = await response.json();
  console.log(`Credits remaining: ${data.credits_remaining}`);
  return data.result;
}

Tips

• Check credits_remaining in each response to monitor usage proactively.
• Handle character_limit_reached gracefully so your app doesn't crash when credits run out.
• For large volumes of text, consider batching requests to stay within rate limits.