API Reference

Base URL

https://your-project.behest.app

Each project gets a dedicated subdomain. Find yours in the Behest dashboard.

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer your-api-key

API keys are generated per-project in the dashboard. Keys are hashed with Argon2id and cannot be retrieved after creation — store them securely.

POST /v1/chat/completions

Create a chat completion. OpenAI-compatible request and response format.

Request Body

Custom Headers

Full Request Example

const response = await fetch(
  "https://your-project.behest.app/v1/chat/completions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer your-api-key",
      "Content-Type": "application/json",
      "X-End-User-Id": "user-12345",
    },
    body: JSON.stringify({
      model: "gemini-2.5-flash",
      messages: [
        { role: "user", content: "Summarize this contract" }
      ],
      temperature: 0.7,
      max_tokens: 1024,
    }),
  }
);

Response Format

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709000000,
  "model": "gemini-2.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here is a summary of the contract..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

Rate Limit Headers

Every response includes rate limit headers so your app can handle limits gracefully.

Error Codes