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

# AI REST Reference

> Direct OpenRouter HTTP integration and InsForge Model Gateway helper endpoints

## Overview

New AI integrations should call OpenRouter directly with the OpenRouter key provisioned by InsForge. The InsForge AI proxy routes for chat, image generation, and embeddings are deprecated compatibility endpoints.

Use the dashboard to copy the active OpenRouter key into a server-only `OPENROUTER_API_KEY` environment variable.

## Direct OpenRouter REST

### Headers

```bash theme={null}
Authorization: Bearer $OPENROUTER_API_KEY
Content-Type: application/json
```

### Chat Completion

```bash theme={null}
curl -X POST https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      { "role": "user", "content": "What is the capital of France?" }
    ]
  }'
```

### Streaming

```bash theme={null}
curl -X POST https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3.5-haiku",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Write a short product update." }
    ]
  }'
```

### Embeddings

```bash theme={null}
curl -X POST https://openrouter.ai/api/v1/embeddings \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "Hello world"
  }'
```

### Models

```bash theme={null}
curl "https://openrouter.ai/api/v1/models?output_modalities=all"
```

<Note>
  OpenRouter owns the current request and response shape for AI model calls. Check OpenRouter's API docs for model-specific parameters, supported modalities, plugins, and video generation endpoints.
</Note>

## InsForge Admin Helper Endpoints

These endpoints help the dashboard display the active Model Gateway key, model catalog, and usage overview. They require admin authentication.

Use either an admin JWT bearer token or an InsForge API key bearer token in the `Authorization` header.

### Get Available Models

```
GET /api/ai/models
```

```bash theme={null}
curl "https://your-app.insforge.app/api/ai/models" \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>"
```

```bash theme={null}
curl "https://your-app.insforge.app/api/ai/models" \
  -H "Authorization: Bearer <INSFORGE_API_KEY>"
```

<Warning>
  `GET /api/ai/models` now returns a flat array of model objects. Older AI proxy docs described a categorized object such as `{ "text": [...], "image": [...] }`; update existing callers that read category properties to filter by `inputModality` or `outputModality` instead.
</Warning>

Returns the normalized OpenRouter model catalog as an array:

```json theme={null}
[
  {
    "id": "openai/gpt-4o",
    "modelId": "openai/gpt-4o",
    "provider": "openrouter",
    "inputModality": ["text", "image"],
    "outputModality": ["text"],
    "inputPrice": 2.5,
    "outputPrice": 10,
    "inputPriceLabel": "$2.50 / 1M tokens",
    "outputPriceLabel": "$10.00 / 1M tokens"
  }
]
```

### Get Active OpenRouter Key

```
GET /api/ai/openrouter/api-key
```

```bash theme={null}
curl "https://your-app.insforge.app/api/ai/openrouter/api-key" \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>"
```

```bash theme={null}
curl "https://your-app.insforge.app/api/ai/openrouter/api-key" \
  -H "Authorization: Bearer <INSFORGE_API_KEY>"
```

```json theme={null}
{
  "apiKey": "sk-or-...",
  "maskedKey": "sk-or-abcd••••••••1234"
}
```

<Warning>
  `apiKey` is a raw secret. Do not log it, commit it, store it in browser storage, or return it from public endpoints. Only `maskedKey` is safe to display in client UI.
</Warning>

### Get Usage Overview

```
GET /api/ai/overview
```

```bash theme={null}
curl "https://your-app.insforge.app/api/ai/overview" \
  -H "Authorization: Bearer <ADMIN_JWT_TOKEN>"
```

```bash theme={null}
curl "https://your-app.insforge.app/api/ai/overview" \
  -H "Authorization: Bearer <INSFORGE_API_KEY>"
```

Returns key-level OpenRouter usage and activity time series when the active key has activity access.

## Deprecated InsForge Proxy Routes

The following routes still exist for existing applications, but new code should use OpenRouter directly.

| Method | Endpoint                   | Replacement                                                                          |
| ------ | -------------------------- | ------------------------------------------------------------------------------------ |
| POST   | `/api/ai/chat/completion`  | `POST https://openrouter.ai/api/v1/chat/completions`                                 |
| POST   | `/api/ai/image/generation` | OpenRouter chat completions with image output or OpenRouter image-capable model docs |
| POST   | `/api/ai/embeddings`       | `POST https://openrouter.ai/api/v1/embeddings`                                       |

### Legacy Chat Proxy

```
POST /api/ai/chat/completion
```

This route validates an InsForge-shaped request, forwards it to OpenRouter, and returns an InsForge-shaped response. It does not expose the complete OpenRouter API surface.

### Legacy Image Proxy

```
POST /api/ai/image/generation
```

This route forwards an InsForge-shaped image request to OpenRouter chat completions with image output. It is retained for compatibility only.

### Legacy Embeddings Proxy

```
POST /api/ai/embeddings
```

This route forwards an InsForge-shaped embeddings request to OpenRouter. Prefer the direct OpenRouter embeddings endpoint for new code.