Toolgram

API reference

OpenAI-compatible. One key, one base URL, every model. Requests are forwarded as-is, so any parameter your SDK sends reaches the model.

Base URL

https://toolgram.app/api/v1

Authentication

Send your key in the Authorization header as a Bearer token. Keys start with tg_live_, are stored hashed, and can be revoked from the dashboard at any time.

Authorization: Bearer tg_live_YOUR_KEY

Requests without a valid key return 401. A revoked key stops working immediately.

Endpoints

MethodPathBody
POST/chat/completionsOpenAI chat format. Messages, tools, streaming.
POST/completionsLegacy prompt format.
POST/embeddingsModel id plus input text.
GET/modelsNo body. Returns the catalog for your key.

Other OpenAI-style paths are forwarded to the upstream provider. If a model supports a feature, the feature passes through.

Streaming

Add "stream": true and read server-sent events. Usage is still metered from the final chunk.

curl https://toolgram.app/api/v1/chat/completions \
  -H "Authorization: Bearer tg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai-gpt-oss-20b",
    "messages": [{"role": "user", "content": "Count to five."}],
    "max_tokens": 100,
    "stream": true
  }'

Set max_tokens

Before a request starts we check that your balance covers the worst case. If you omitmax_tokens, we assume 2000 output tokens for that check. Set it explicitly to keep the check tight and avoid a 402 on a small balance.

Rate limits

Each key allows 120 requests per minute. Above that you get a 429 with aRetry-After header. Retry after that many seconds, with jitter.

Errors

StatusCodeWhat to do
401invalid_api_keyKey missing, mistyped or revoked. Create a new one.
402insufficient_quotaBalance too low for this request. Top up or lower max_tokens.
429rate_limit_errorOver 120 requests per minute. Wait for Retry-After.
503service_disabledThe API is paused for maintenance. Check status.

Error bodies follow the OpenAI shape:

{
  "error": {
    "message": "Insufficient balance. Top up your Toolgram wallet to continue using the API.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

Billing per request

Every completed request is charged from your prepaid balance using the token counts the provider reports. Prices are per 1 million tokens, shown on Models and prices. A request that fails before reaching the model is not charged.

Need a hand?

Post in the group with the key prefix, model id, error code and time.