API Documentation

Quickstart

Base URL: https://meriq.ai/v1. Call it 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, exports, account-read, account-write). A request outside a key's scopes returns 403 insufficient_scope.

Models

Pass one of these ids as model. Omit model and the request uses meriq, or the first model in this list your plan can call. GET /v1/models lists only the models your key can call.

Billing

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

• API wallet. A prepaid USD balance you top up from the dashboard ($5 minimum per payment). Charged per token at the published rates above. This is how every account pays by default, and how wallet-only models are always billed.
• Plan usage. If your subscription 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.

Prompt tokens the provider serves from its cache bill at the cached input rate in the table above, not the full input rate. Long conversations and agent loops that resend the same prefix cost less per call. usage.prompt_tokens still counts every prompt token.

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

Monthly key budgets cover wallet charges in UTC calendar months, including wallet fallback. Pending requests reserve part of the budget before starting; a request whose estimate does not fit returns 402 budget_exceeded. Final billing uses actual usage, including any extra usage that fits the remaining budget, while protecting other pending reservations. Charges never exceed the budget agreed when the request started. Requests crossing midnight on the first day settle against their starting month. Budget changes apply to new requests.

A refunded or disputed top-up is taken back out of the wallet, which can leave the balance below zero. Wallet-billed calls return 402 until it is positive again.

Refused answers are refunded on models marked refund-eligible: check refunds_refusals on /v1/models, or meriq.refund_policy in each response. Fees for completed server-side tool calls, such as web searches, are kept. Meriq never silently retries or rewrites your prompt.

Chat completions

POST /v1/chat/completions · scope chat, plus search for server-side tools

Fields sent as null are ignored. Not supported, and rejected with 400 unsupported_parameter: logprobs (except false), top_logprobs, logit_bias, response_format (except {"type": "text"}), reasoning and reasoning_effort. Reasoning settings are configured by the selected model. Each entry on /v1/models lists its supported_parameters.

Streaming responses are SSE lines of data: {...} in OpenAI chunk format, terminated by data: [DONE]. If generation fails after the stream has started, an error event in the same shape as the error body below is sent before [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"}]
  }'

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 tools_not_supported rather than silently answering in prose. Check supports_tools on /v1/models before sending.

Server-side tools

Meriq can also run tools for you. They need a key with the search scope and a model that supports tool calling. Models that can use them list them in server_tools on /v1/models. Dashboard keys start with only chat, so tick search when you create the key. Add them alongside your own functions:

Meriq runs these internally, up to 8 model passes per request, 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 · any scope

Returns the models your key can call, with per-model prices (including cached_input_price_per_million), limits, default_max_tokens, supported_parameters, and whether the model is eligible for plan usage on your subscription. GET /v1/models/{id} returns a single entry.

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

Balance

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": "..."}
    }
  }
}

Usage history

GET /v1/usage · scope account-read

Your most recent calls, newest first. limit sets the page size (default 50, max 200); refunded=true returns only refunded refusals.

{
  "object": "list",
  "data": [{
    "id": "...",
    "request_id": "chatcmpl-...",
    "created": 1767225600,
    "endpoint": "/v1/chat/completions",
    "model": "meriq",
    "prompt_tokens": 812,
    "completion_tokens": 240,
    "total_tokens": 1052,
    "cost_usd": 0.0013,
    "billed_to": "wallet",
    "refunded": false
  }]
}

cost_usd is null on plan-billed calls.

Request IDs

Every /v1 response, including errors, carries an X-Request-Id header. On chat completions it equals the completion id. Error bodies repeat it as error.request_id, and /v1/usage returns it as request_id. Quote it when you contact support.

Web search

POST /v1/search · scope search

Runs a cited web search and returns results with citations. Always billed to the wallet: $0.001 per request. max_results is 1 to 10; query is up to 4,000 characters. A search that returns no usable evidence is not charged.

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}'

Limits

Abuse protection can also return 429. Every 429 carries a Retry-After header in seconds.

Account export and deletion

GET /v1/me/export (scope exports) and DELETE /v1/me (scope account-write) return 202 with a durable action ID, status URL, and first-party confirmation URL. Repeated requests reuse the recorded action. A request pending confirmation has not exported or deleted anything.

Open the confirmation URL while signed in as the owner. Export requires password verification or the applicable social-account confirmation and an operation-specific session grant. An API key cannot unlock saved content. Archives include a versioned completeness manifest, expire after one hour, and require a fresh download grant after ten minutes. Browser-only conversations require a browser export.

Confirmed deletion reports processing, failed_retryable, or completed. Processing waits for active work and cleanup acknowledgments from storage servers. Minimal billing and required security records follow the Privacy Policy. The receipt URL shows status for seven days without exposing account content.

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, and a key with a monthly budget cannot create keys.
• POST /v1/keys/{id}/revoke revokes a key

Image generation and file upload endpoints are not available yet and return 501 not_implemented.

Errors

Every error is returned as:

{
  "error": {
    "message": "Human-readable explanation.",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "param": "temperature",
    "request_id": "chatcmpl-..."
  }
}

param appears when one field caused the error. Rate limits add a top-level rate_limit object with reset_at and retry_after_seconds.

A streamed call that fails mid-response sends a final error event with type: "server_error" and code stream_error, providers_unavailable, or internal_error.

Use with coding tools

Any tool that speaks the OpenAI chat completions API can use Meriq. The settings below are configured for each tool, not tested with every version. Replace <MODEL_ID>, <CONTEXT> and <MAX_OUTPUT> with id, context_length and max_output_tokens from /v1/models, and pick a model with supports_tools: true for agent workflows.

OpenCode

Configured for opencode.json. Set MERIQ_API_KEY in your environment.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "meriq": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Meriq",
      "options": {
        "baseURL": "https://meriq.ai/v1",
        "apiKey": "{env:MERIQ_API_KEY}"
      },
      "models": {
        "<MODEL_ID>": {
          "name": "<MODEL_ID>",
          "limit": { "context": <CONTEXT>, "output": <MAX_OUTPUT> }
        }
      }
    }
  }
}

Cline

Configured for the Cline settings panel:

API Provider:        OpenAI Compatible
Base URL:            https://meriq.ai/v1
API Key:             mrq_your_key_here
Model ID:            <MODEL_ID>
Context Window Size: <CONTEXT>
Max Output Tokens:   <MAX_OUTPUT>

Aider

Configured for Aider's OpenAI-compatible mode. Set max_tokens, or Aider uses the API default of min(4,096, model max output) and long edits stop with finish_reason: "length".

export OPENAI_API_BASE=https://meriq.ai/v1
export OPENAI_API_KEY=mrq_your_key_here
aider --model openai/<MODEL_ID>

.aider.model.settings.yml:

- name: openai/<MODEL_ID>
  extra_params:
    max_tokens: <MAX_OUTPUT>

.aider.model.metadata.json:

{
  "openai/<MODEL_ID>": {
    "max_input_tokens": <CONTEXT>,
    "max_output_tokens": <MAX_OUTPUT>,
    "litellm_provider": "openai",
    "mode": "chat"
  }
}

Continue

Configured for config.yaml:

models:
  - name: Meriq <MODEL_ID>
    provider: openai
    model: <MODEL_ID>
    apiBase: https://meriq.ai/v1
    apiKey: mrq_your_key_here
    defaultCompletionOptions:
      contextLength: <CONTEXT>
      maxTokens: <MAX_OUTPUT>
    roles:
      - chat
      - edit

Cursor

Configured for chat only. Tab completion and other built-in features keep using Cursor's own models.

Settings > Models > API Keys
OpenAI API Key:            mrq_your_key_here
Override OpenAI Base URL:  https://meriq.ai/v1
Add model:                 <MODEL_ID>