Integration

Overview

This guide covers the core integration patterns for working with the Aimable API. You will learn how to authenticate requests, structure API calls, and handle responses and errors.

Authentication

All API requests require a valid API key passed in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are scoped to your organisation and can be created, rotated, or revoked from the Aimable dashboard. We recommend using environment variables to store keys and never committing them to version control.

Making Requests

The primary endpoint for AI orchestration is POST /v1/orchestrate. Here is an example using the Node.js SDK:

import { Aimable } from "@aimable/sdk";
 
const client = new Aimable({
  apiKey: process.env.AIMABLE_API_KEY,
});
 
const response = await client.orchestrate({
  model: "default",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Summarise this document." },
  ],
  options: {
    maxTokens: 1024,
    temperature: 0.7,
  },
});
 
console.log(response.output);

Handling Responses

Every successful response includes a standard structure:

200 OK — Request completed successfully. Response body contains the output and metadata.
400 Bad Request — Invalid request parameters. Check the error.message field for details.
401 Unauthorized — Invalid or missing API key.
429 Too Many Requests — Rate limit exceeded. Retry after the duration specified in the Retry-After header.
500 Internal Server Error — An unexpected error occurred. Contact support if the issue persists.

Always check the status field in the response body and implement appropriate retry logic for transient errors (429, 500).