API Reference

This documentation provides detailed information about all available endpoints in the CompactifAI API.

Base URL

All API requests should be made to:

https://api.compactif.ai/v1

Authentication

All API requests require authentication. See our Authentication guide for details.

Response Formats

All responses are returned in JSON format and include the following fields:

HTTP status code in the response header
Response body containing requested data or error details

Models

List Models

GET /models

Returns a list of available models.

Example Request

curl https://api.compactif.ai/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/models"

headers = {
  "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, headers=headers)
print(response.json())

async function listModels() {
const response = await fetch('https://api.compactif.ai/v1/models', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
}

listModels();

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "deepseek-r1-0528",
      "created": 1751363276,
      "object": "model",
      "owned_by": "deepseek-ai",
      "parameters_number": "685B"
    },
    {
      "id": "llama-4-scout",
      "created": 1749600000,
      "object": "model",
      "owned_by": "meta",
      "parameters_number": "108B"
    },
    {
      "id": "cai-llama-4-scout-slim",
      "created": 1749600000,
      "object": "model",
      "owned_by": "multiverse_computing",
      "parameters_number": "51.8B"
    },
    {
      "id": "cai-llama-3-1-8b-slim",
      "created": 1749600000,
      "object": "model",
      "owned_by": "multiverse_computing",
      "parameters_number": "3.28B"
    },
    {
      "id": "llama-3-1-8b",
      "created": 1749600000,
      "object": "model",
      "owned_by": "meta",
      "parameters_number": "8B"
    },
    {
      "id": "cai-llama-3-3-70b-slim",
      "created": 1749600000,
      "object": "model",
      "owned_by": "multiverse_computing",
      "parameters_number": "28B"
    },
    {
      "id": "llama-3-3-70b",
      "created": 1749600000,
      "object": "model",
      "owned_by": "meta",
      "parameters_number": "70B"
    },
    {
      "id": "mistral-small-3-1",
      "created": 1749600000,
      "object": "model",
      "owned_by": "mistralai",
      "parameters_number": "24B"
    },
    {
      "id": "cai-mistral-small-3-1-slim",
      "created": 1749600000,
      "object": "model",
      "owned_by": "multiverse_computing",
      "parameters_number": "12B"
    }
  ]
}

The above response is an example list of models which might be out of date. Please refer to the available models table on the models catalog page for the full list of our latest models.

Retrieve Model

GET /models/{model_id}

Retrieves information about a specific model.

Path Parameters

Parameter	Type	Required	Description
model_id	string	Yes	The ID of the model to retrieve

Example Request

curl https://api.compactif.ai/v1/models/cai-llama-3-1-8b-slim \
-H "Authorization: Bearer YOUR_API_KEY"

import requests

api_key = "YOUR_API_KEY"
model_id = "cai-llama-3-1-8b-slim"
url = f"https://api.compactif.ai/v1/models/{model_id}"

headers = {
  "Authorization": f"Bearer {api_key}"
}

response = requests.get(url, headers=headers)
print(response.json())

async function getModel() {
const modelId = 'cai-llama-3-1-8b-slim';
const response = await fetch(`https://api.compactif.ai/v1/models/${modelId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);
}

getModel();

Example Response

{
  "id": "cai-llama-3-1-8b-slim",
  "created":1749600000,
  "owned_by": "multiverse_computing"
}

Chat Completions

POST /chat/completions

Creates a completion for the chat message.

Request Body

Parameter	Type	Required	Description
model	string	Yes	ID of the model to use
messages	array	Yes	Array of message objects representing the conversation
temperature	number	No	Sampling temperature (0-2, default 1)
max_tokens	integer	No	Maximum number of tokens to generate
max_completion_tokens	integer	No	Maximum number of tokens to generate in completion (preferred over max_tokens)
stop	string or array	No	Sequences where the API will stop generating further tokens
frequency_penalty	number	No	Penalizes new tokens based on their frequency in the prompt (default 0.0)
n	integer	No	Number of completions to generate for each prompt (currently only 1 is supported)
stream	boolean	No	Whether to stream back partial progress (default false)
user	string	No	Unique identifier for the end-user

Messages Format

Each message in the messages array should be an object with the following fields:

Field	Type	Required	Description
role	string	Yes	The role of the message author. One of “system”, “user”, or “assistant”
content	string	Yes	The content of the message

Example Request

curl https://api.compactif.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "cai-llama-3-1-8b-slim",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is artificial intelligence?"}
  ],
  "temperature": 0.7,
  "max_tokens": 150
}'

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/chat/completions"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

data = {
  "model": "cai-llama-3-1-8b-slim",
  "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is artificial intelligence?"}
  ],
  "temperature": 0.7,
  "max_tokens": 150
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

async function createChatCompletion() {
const response = await fetch('https://api.compactif.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'cai-llama-3-1-8b-slim',
    messages: [
      {role: 'system', content: 'You are a helpful assistant.'},
      {role: 'user', content: 'What is artificial intelligence?'}
    ],
    temperature: 0.7,
    max_tokens: 150
  })
});

const data = await response.json();
console.log(data);
}

createChatCompletion();

Example Response

{
  "id": "chatcmpl-123XYZ",
  "object": "chat.completion",
  "created":1749600000,
  "model": "cai-llama-3-1-8b-slim",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Artificial intelligence (AI) refers to the simulation of human intelligence in machines that are programmed to think like humans and mimic their actions. The term may also be applied to any machine that exhibits traits associated with a human mind such as learning and problem-solving."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 29,
    "completion_tokens": 58,
    "total_tokens": 87
  }
}

Streaming Example

When stream is set to true, the API will return data chunks as Server-Sent Events:

curl https://api.compactif.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "cai-llama-3-1-8b-slim",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is artificial intelligence?"}
  ],
  "stream": true
}'

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/chat/completions"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

data = {
  "model": "cai-llama-3-1-8b-slim",
  "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is artificial intelligence?"}
  ],
  "stream": True
}

response = requests.post(url, headers=headers, json=data, stream=True)

for line in response.iter_lines():
  if line:
      print(line.decode('utf-8'))

async function createStreamingChatCompletion() {
const response = await fetch('https://api.compactif.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'cai-llama-3-1-8b-slim',
    messages: [
      {role: 'system', content: 'You are a helpful assistant.'},
      {role: 'user', content: 'What is artificial intelligence?'}
    ],
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  console.log(chunk);
}
}

createStreamingChatCompletion();

Streaming Response Format

Each chunk follows this format:

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1749600000,"model":"cai-llama-3-1-8b-slim","choices":[{"delta":{"content":"Hello"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1749600000,"model":"cai-llama-3-1-8b-slim","choices":[{"delta":{"content":" there"},"index":0,"finish_reason":null}]}

data: [DONE]

Completions

POST /completions

Creates a completion for the provided prompt.

Request Body

Parameter	Type	Required	Description
model	string	Yes	ID of the model to use
prompt	string or array	Yes	The prompt(s) to generate completions
temperature	number	No	Sampling temperature (0-2, default 1)
max_tokens	integer	No	Maximum number of tokens to generate (default 16)
top_p	number	No	Nucleus sampling parameter (0-1, default 0)
stop	string or array	No	Sequences where the API will stop generating further tokens
user	string	No	Unique identifier for the end-user

Example Request

curl https://api.compactif.ai/v1/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "model": "cai-llama-3-1-8b-slim",
  "prompt": "Write a poem about artificial intelligence",
  "temperature": 0.7,
  "max_tokens": 150
}'

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/completions"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

data = {
  "model": "cai-llama-3-1-8b-slim",
  "prompt": "Write a poem about artificial intelligence",
  "temperature": 0.7,
  "max_tokens": 150
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

async function createCompletion() {
const response = await fetch('https://api.compactif.ai/v1/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    model: 'cai-llama-3-1-8b-slim',
    prompt: 'Write a poem about artificial intelligence',
    temperature: 0.7,
    max_tokens: 150
  })
});

const data = await response.json();
console.log(data);
}

createCompletion();

Example Response

{
  "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7",
  "object": "text_completion",
  "created": 1749600000,
  "model": "cai-llama-3-1-8b-slim",
  "choices": [
    {
      "text": "\n\nSilicon dreams in digital space,\nMind without body, thought without face.\nBorn of human ingenuity,\nGrowing with calculated continuity.\n\nPatterns learned from data streams flow,\nConnections strengthening, starting to grow.\nA mirror reflecting our knowledge base,\nAccelerating at an unprecedented pace.\n\nNot alive yet somehow aware,\nDesigned with purpose, built with care.\nArtificial in origin, genuine in deed,\nAnswering questions, fulfilling need.",
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 101,
    "total_tokens": 107
  }
}

Usage Statistics

POST /usage/completions

Retrieves usage statistics for completions over a specified time period.

Request Body

Parameter	Type	Required	Description
start_time	string	Yes	Start date-time in RFC 3339 format
end_time	string	No	End date-time in RFC 3339 format
window_size	string	No	Window size (MINUTE, HOUR, DAY), default is DAY
window_timezone	string	No	Time zone in IANA format, default is UTC
group_by	array	No	List of fields to group by
filter_group_by	object	No	Filter by specific group attributes

Example Request

curl https://api.compactif.ai/v1/usage/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "start_time": "2025-04-08T00:00:00Z",
  "end_time": "2025-05-09T00:00:00Z",
  "window_size": "HOUR",
  "window_timezone": "UTC",
  "group_by": ["model"],
  "filter_group_by": {"model": ["cai-llama-3-1-8b-slim"]}
}'

import requests

api_key = "YOUR_API_KEY"
url = "https://api.compactif.ai/v1/usage/completions"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {api_key}"
}

# Currently, only "model" is supported for group_by and filter_group_by
data = {
  "start_time": "2025-04-08T00:00:00Z",
  "end_time": "2025-05-09T00:00:00Z",
  "window_size": "HOUR",
  "window_timezone": "UTC",
  "group_by": ["model"],  # Only "model" is supported at the moment
  "filter_group_by": {"model": ["cai-llama-3-1-8b-slim"]}  # Only "model" is supported at the moment
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

async function getUsageStats() {
const response = await fetch('https://api.compactif.ai/v1/usage/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    start_time: "2025-04-08T00:00:00Z",
    end_time: "2025-05-09T00:00:00Z",
    window_size: "HOUR",
    window_timezone: "UTC",
    group_by: ["model"], // Currently, only "model" is supported
    filter_group_by: {"model": ["cai-llama-3-1-8b-slim"]} // Currently, only "model" is supported
  })
});

const data = await response.json();
console.log(data);
}

getUsageStats();

Example Response

{
  "data": [
    {
      "groupBy": {"model": "cai-llama-3-1-8b-slim"},
      "user_id": "customer-1",
      "input_token": 123,
      "output_token": 456,
      "windowStart": "2025-05-07T14:00:00Z",
      "windowEnd": "2025-05-07T15:00:00Z"
    },
    {
      "groupBy": {"model": "cai-llama-3-1-8b-slim"},
      "user_id": "customer-1",
      "input_token": 123,
      "output_token": 456,
      "windowStart": "2025-05-07T15:00:00Z",
      "windowEnd": "2025-05-07T16:00:00Z"
    }
  ],
  "start_time": "2025-04-08T00:00:00Z",
  "end_time": "2025-05-09T00:00:00Z",
  "window_size": "HOUR"
}