← Back to home

DEVELOPER

Integrate BetterQuery into your service

BetterQuery exposes one primary API and optional MCP integration. Use it as a preprocessing step before the model that receives your user prompt. No internal model names are exposed; behavior is controlled by BetterQuery profiles: betterquery-light and betterquery-pro.

1) Create credentials

  • Sign in to BetterQuery and open API Keys.
  • Create a key with enhance:basic (free profile) or enhance:pro (pro profile).
  • Copy the key immediately and store it in your secrets manager.
  • Use the same key for REST, MCP, and browser extension flows.
Open API key manager →

2) REST API integration

Use HTTPS with API key auth. Header required:

X-API-Key: bq_live_...

Request shape

POST /api/v1/enhance
Content-Type: application/json

{
  "query": "string (min 10 chars)",
  "options": {
    "mode": "transparent | review | trigger",
    "role": "engineering | quality | product | operations | management",
    "expertise": "beginner | intermediate | expert | principal"
  }
}

Sample cURL

curl -X POST \
  https://betterquery.app/api/v1/enhance \
  -H "X-API-Key: bq_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "Summarize this PR for a non-technical stakeholder",
  "options": {
    "mode": "transparent"
  }
}'

3) Server-side example

const response = await fetch("https://betterquery.app/api/v1/enhance", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "bq_live_your_key"
  },
  body: JSON.stringify({
    query: "Summarize this PR for a non-technical stakeholder",
    options: { mode: "transparent" },
  }),
});

const { data } = await response.json();
console.log(data.enhanced);

If successful, the response returns an updated quota payload in data.quota with used, limit, remaining, and resetAt.

4) MCP and browser extension

MCP gives agent tools a ready-made interface. Configure your client once and reuse the same key.

{
  "mcpServers": {
    "betterquery": {
      "command": "npx",
      "args": ["-y", "@cdli-ai/betterquery-mcp"],
      "env": {
        "BETTERQUERY_API_KEY": "bq_live_your_key"
      }
    }
  }
}

Browser extension users can also use the same key through the extension popup. This is the path with the least friction for non-technical users.

MCP package on npm →

5) Troubleshooting

  • 401 TOKEN_MISSING — send the API key in X-API-Key or Authorization: Bearer bq_....
  • 401 Invalid API key — the key format may be wrong, it may be revoked, or expired.
  • 429 Monthly quota exceeded — upgrade the account plan before retrying.
  • check_usage tool — use MCP tool to inspect remaining quota in real time.