> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperleap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Completions API

> Execute raw prompt completions without creating/storing a prompt first

Execute raw prompt completions without creating or storing a prompt first. Ideal for developers who want direct API access.

## Authentication

Use your API key in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

## Available Endpoints

| Method | Endpoint                  | Description                              |
| ------ | ------------------------- | ---------------------------------------- |
| POST   | `/api/completions`        | Main endpoint (use `?stream=true/false`) |
| POST   | `/api/completions/sync`   | Non-streaming response                   |
| POST   | `/api/completions/stream` | HTTP/2 streaming (JSON array)            |
| POST   | `/api/completions/sse`    | Server-Sent Events streaming             |

## Request Body

```json theme={null}
{
  "promptText": "string (required)",
  "systemMessage": "string (optional)",
  "aiSystem": "string (required)",
  "model": "string (required)",
  "configuration": { },
  "replacements": { },
  "dataspaceIds": ["uuid"],
  "metadata": { }
}
```

### Fields

| Field           | Type   | Required | Description                                                                         |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| `promptText`    | string | Yes      | The prompt text. Supports `{{variable}}` placeholders                               |
| `systemMessage` | string | No       | System message for AI context                                                       |
| `aiSystem`      | string | Yes      | AI provider: `HyperleapAi`, `OpenAi`, `Anthropic`, `GoogleGemini`, `Groq`, `Cohere` |
| `model`         | string | Yes      | Model name (e.g., `hl-gpt-4o-mini`, `gpt-4`, `claude-3-haiku-20240307`)             |
| `configuration` | object | No       | Model parameters (`temperature`, `max_tokens`, etc.)                                |
| `replacements`  | object | No       | Key-value pairs for `{{variable}}` substitution                                     |
| `dataspaceIds`  | array  | No       | Dataspace UUIDs for RAG grounding                                                   |
| `metadata`      | object | No       | Custom metadata to attach                                                           |

## Examples

### Basic Request

```bash theme={null}
curl -X POST "https://api.hyperleapai.com/api/completions/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptText": "Say hello in French",
    "aiSystem": "HyperleapAi",
    "model": "hl-gpt-4o-mini"
  }'
```

### With Variable Replacements

```bash theme={null}
curl -X POST "https://api.hyperleapai.com/api/completions/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptText": "Translate to {{language}}: {{text}}",
    "aiSystem": "HyperleapAi",
    "model": "hl-gpt-4o-mini",
    "replacements": {
      "language": "Spanish",
      "text": "Hello world"
    }
  }'
```

### With System Message

```bash theme={null}
curl -X POST "https://api.hyperleapai.com/api/completions/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptText": "What is the capital of France?",
    "systemMessage": "You are a geography expert. Be concise.",
    "aiSystem": "HyperleapAi",
    "model": "hl-gpt-4o-mini"
  }'
```

### Streaming (SSE)

```bash theme={null}
curl -X POST "https://api.hyperleapai.com/api/completions/sse" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "promptText": "Count from 1 to 5",
    "aiSystem": "HyperleapAi",
    "model": "hl-gpt-4o-mini"
  }'
```

### With Configuration

```bash theme={null}
curl -X POST "https://api.hyperleapai.com/api/completions/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptText": "Write a creative story about a robot",
    "aiSystem": "HyperleapAi",
    "model": "hl-gpt-4o-mini",
    "configuration": {
      "temperature": 0.9,
      "max_tokens": 500
    }
  }'
```

## Response Format

### Sync Response

```json theme={null}
{
  "choices": [{
    "finish_reason": "Stop",
    "index": 0,
    "message": {
      "role": "Assistant",
      "content": "Bonjour!"
    }
  }],
  "messageId": "uuid",
  "runId": "uuid",
  "usage": {
    "prompt_tokens": 21,
    "completion_tokens": 7,
    "total_tokens": 28
  }
}
```

### SSE Response

```
data: {"choice":{"index":0,"message":{"role":"assistant","content":"Hello"}},...}

data: {"choice":{"index":0,"message":{"role":"assistant","content":" world"}},...}

data: {"choice":{"index":0,"finish_reason":"Stop","message":{"role":"assistant"}},...}
```

## Available Models

### HyperleapAi

* `hl-gpt-4o-mini`
* `hl-gpt-4.1-mini`

### OpenAi

* `gpt-4o`
* `gpt-4o-mini`
* `gpt-4-turbo`
* `gpt-3.5-turbo`

### Anthropic

* `claude-3-opus-20240229`
* `claude-3-sonnet-20240229`
* `claude-3-haiku-20240307`

### Google Gemini

* `gemini-pro`
* `gemini-1.5-pro`

### Groq

* `llama3-70b-8192`
* `mixtral-8x7b-32768`

## Error Handling

| Status | Description                                              |
| ------ | -------------------------------------------------------- |
| 400    | Invalid request (missing required fields, invalid model) |
| 401    | Unauthorized (invalid or missing API key)                |
| 500    | Server error                                             |

## Notes

* Credits are consumed for each API call
* Variable replacement uses Handlebars syntax: `{{variableName}}`
* All endpoints support the same request body format
* Use `/api/completions?stream=true` for streaming via query parameter

<RequestExample>
  ```bash ENDPOINTS theme={null}
  POST /api/completions
  POST /api/completions/sync
  POST /api/completions/stream
  POST /api/completions/sse
  ```
</RequestExample>