API Documentation

Quickstart

Create a key from the API dashboard, then call the API exactly as you would OpenAI's.

# pip install openai
from openai import OpenAI

client = OpenAI(
    api_key="mrq_your_key_here",
    base_url="https://meriq.ai/v1",
)

resp = client.chat.completions.create(
    model="meriq",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Authentication

Every request needs a bearer token. Keys start with mrq_ and are shown once at creation, so store them somewhere safe.

Authorization: Bearer mrq_your_key_here

Each key carries scopes (chat, search, images, files, exports, account-read, account-write). A request outside a key's scopes returns 403 insufficient_scope. Keys also carry their own per-minute rate limit, shown in the dashboard.

Models

Pass one of these ids as model.

Billing

API usage is billed one of two ways, decided per request:

• API wallet. A prepaid USD balance you top up from the dashboard. Charged per token at the published rates above. This is how every account pays by default, and how all wallet-only models are always billed.
• Plan usage. If you're on a subscription that includes API usage, calls to the plan-eligible models above draw from the same rolling usage windows as chat instead of your wallet. No wallet balance required.

Usage is measured in tokens processed, so it scales with the size of what you're building: long files, large contexts, and multi-step agent loops consume far more per call than short prompts.

When a plan usage window runs out, calls return 429 until it resets. Turn on wallet fallback in the dashboard to have those calls continue on your wallet balance instead.

If a model refuses your request, the refusal is detected and the charge is credited back automatically. Meriq never silently retries or rewrites your prompt.

Chat completions

POST /v1/chat/completions · scope chat

Streaming responses are SSE lines of data: {...} in OpenAI chunk format, terminated by data: [DONE].

curl https://meriq.ai/v1/chat/completions \
  -H "Authorization: Bearer mrq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meriq",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Tool calling

Meriq supports standard OpenAI function calling. Send your schemas in tools and they are passed to the model untouched; when it decides to call one you get tool_calls back with finish_reason: "tool_calls". Reply with a role: "tool" message carrying the matching tool_call_id to continue the loop. This is what agent harnesses expect, so pointing one at Meriq works without changes.

{
  "model": "meriq",
  "messages": [{"role": "user", "content": "What's the weather in Paris?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}

If a model cannot use tools, the request is rejected with 400 rather than silently answering in prose. Check supports_tools on /v1/models before sending.

Server-side tools

Meriq can also run tools for you. Because Meriq executes them itself rather than relying on the upstream provider, they work on every model in the catalog. Add them alongside your own functions:

Meriq runs these internally and returns the finished answer. The tool calls never surface in your response. If you define your own function with the same name, yours wins and Meriq's is not added.

List models

GET /v1/models

Returns the catalog available to your account, including per-model prices and whether the model is eligible for plan usage on your subscription.

curl https://meriq.ai/v1/models \
  -H "Authorization: Bearer mrq_your_key_here"

Balance and usage

GET /v1/me/balance · scope account-read

Returns your wallet balance, month-to-date spend, whether wallet fallback is on, and the state of each usage window if your plan includes API usage.

{
  "balance_usd": 24.8102,
  "wallet_fallback_enabled": false,
  "month_spend_usd": 5.1898,
  "subscription_usage": {
    "eligible_models": ["meriq", "meriq-pro"],
    "windows": {
      "session": {"used_usd": 0.12, "limit_usd": 0.5, "pct_used": 24, "reset_at": "..."}
    }
  }
}

Web search

POST /v1/search · scope search

Runs a cited web search and returns results with citations. Billed as a flat fee per request against your wallet.

curl https://meriq.ai/v1/search \
  -H "Authorization: Bearer mrq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "latest AI research", "max_results": 5}'

Key management

Manage keys programmatically with an account-read / account-write scoped key:

• GET /v1/keys lists your keys
• POST /v1/keys creates a key. A child key can never hold scopes its parent lacks.
• POST /v1/keys/{id}/revoke revokes a key

Errors

Errors are returned as {"error": {"message": "...", "type": "..."}}, except rate limits, which add a rate_limit object with the reset time.