📡 API Reference

Base URL: https://your-api.onrender.com (production) or http://localhost:8000 (local)

Interactive docs: {BASE_URL}/docs (Swagger UI)

Authentication

IntentScope uses two auth methods depending on the endpoint:

Auth Type	Header	Used For
Virtual Key	`Authorization: Bearer sk-intentscope-...`	Proxy requests (`/v1/...`)
Clerk JWT	`Authorization: Bearer <clerk_token>`	Dashboard APIs (`/keys`, `/analytics`, `/settings`)

Gateway Proxy

`POST /v1/chat/completions`

The main proxy endpoint. Forwards requests to Groq/Mistral/Ollama after intent analysis, budget check, and model routing.

Auth: Virtual Key

Request body (OpenAI-compatible):

{
  "model": "default",
  "messages": [
    { "role": "user", "content": "Your prompt here" }
  ],
  "max_tokens": 1000,
  "temperature": 0.7
}

Field	Type	Description
`model`	string	`"default"` for auto-routing, or a specific model from `KNOWN_VALID_MODELS`
`messages`	array	OpenAI-format message array
`max_tokens`	integer	Optional max tokens
`temperature`	float	Optional temperature

Example:

curl -X POST https://your-api.onrender.com/v1/chat/completions \
  -H "Authorization: Bearer sk-intentscope-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [{"role": "user", "content": "Write a Python function to reverse a string"}]
  }'

Response (OpenAI-compatible):

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "groq/llama-3.3-70b-versatile",
  "choices": [
    {
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 142,
    "total_tokens": 166
  }
}

The response model field shows the actual model used after routing — useful for debugging.

Error responses:

Status	Meaning
`401`	Invalid or revoked virtual key
`402`	Token budget exhausted
`500`	LLM provider error (e.g. model not found)

Key Management

`POST /keys`

Create a new virtual API key.

Auth: Clerk JWT

curl -X POST https://your-api.onrender.com/keys \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "token_limit": 100000
  }'

Response:

{
  "id": "uuid",
  "name": "Production Key",
  "key": "sk-intentscope-xxxxxxxx",
  "token_limit": 100000,
  "tokens_used": 0,
  "is_active": true,
  "created_at": "2026-01-01T00:00:00Z"
}

⚠️

The key value is only shown once at creation. Store it securely.

`GET /keys`

List all virtual keys for the authenticated user.

Auth: Clerk JWT

curl https://your-api.onrender.com/keys \
  -H "Authorization: Bearer <clerk_jwt>"

`DELETE /keys/{id}`

Revoke a virtual key.

Auth: Clerk JWT

curl -X DELETE https://your-api.onrender.com/keys/uuid \
  -H "Authorization: Bearer <clerk_jwt>"

`POST /keys/{id}/rotate`

Rotate a key (generates a new key string, invalidates the old one).

Auth: Clerk JWT

curl -X POST https://your-api.onrender.com/keys/uuid/rotate \
  -H "Authorization: Bearer <clerk_jwt>"

Analytics

`GET /analytics/overview`

Dashboard summary stats.

Auth: Clerk JWT

Response:

{
  "total_requests": 1240,
  "total_tokens": 892000,
  "active_keys": 3,
  "avg_latency_ms": 412
}

`GET /analytics/usage`

Daily token usage time-series (last 30 days).

Auth: Clerk JWT

Response:

[
  { "date": "2026-01-01", "tokens": 12400 },
  { "date": "2026-01-02", "tokens": 8900 }
]

`GET /analytics/requests`

Recent request logs.

Auth: Clerk JWT

Response:

[
  {
    "id": "uuid",
    "model": "groq/llama-3.1-8b-instant",
    "intent_category": "qa",
    "risk_level": "low",
    "total_tokens": 234,
    "latency_ms": 389,
    "created_at": "2026-01-01T12:00:00Z"
  }
]

`GET /analytics/intent-breakdown`

Distribution of intent categories.

Auth: Clerk JWT

Response:

[
  { "category": "code_gen", "count": 420 },
  { "category": "qa", "count": 380 },
  { "category": "summarization", "count": 200 }
]

Settings

`GET /settings`

Get the current user’s preferences.

Auth: Clerk JWT

Response:

{
  "default_model": "groq/llama-3.1-8b-instant",
  "strict_budget": true,
  "auto_purge_sensitive": false
}

`PUT /settings`

Update user preferences.

Auth: Clerk JWT

curl -X PUT https://your-api.onrender.com/settings \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "default_model": "groq/llama-3.3-70b-versatile",
    "strict_budget": true
  }'

Health

`GET /health`

API gateway health check. No auth required.

curl https://your-api.onrender.com/health
# {"status":"healthy","db":"connected"}

`GET :8081/validate`

Go token validator fast-path. Used internally by the gateway.

curl "http://localhost:8081/validate?key=sk-intentscope-xxx"

Model Routing Deployment