# Scribase Toolgate docs

## Quickstart

```
curl -X POST https://toolgate.scribase.com/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"org_name": "acme"}'
# -> {"ok":true,"data":{"org":{...},"project":{...},"key":"sk-t0-...","key_id":"...","note":"..."}}

curl https://toolgate.scribase.com/v1/tools/knowledge.wikipedia.summary/call \
  -H "Authorization: Bearer sk-t0-..." \
  -H "Content-Type: application/json" \
  -d '{"input": {"title": "Rust (programming language)"}}'
```

The key works immediately on every free/public tool. A paid tool answers `402` with a `topup_url` until the project has a Mint balance.

## Auth

Every key is a **per-org scoped credential**: it belongs to exactly one org's one project, created by self-serve signup above or by `POST /v1/keys` once you hold an admin-scoped key for that project. It can only see and spend that org's own usage and balance.

- `GET /v1/keys` / `POST /v1/keys` -- list or create a key, optionally narrowed with `scopes`, `tool_allow` and `per_key_daily_cap_micros`.
- `PATCH /v1/keys/{id}` / `POST /v1/keys/{id}/revoke` -- adjust or revoke a key.
- The same key reaches Relay's OpenAI-compatible `/openai/v1` as well as Toolgate's own `/v1/tools`.
- OAuth 2.1 (PKCE, DCR, device flow): `https://toolgate.scribase.com/.well-known/oauth-authorization-server`.
- Provider credentials: `POST /v1/credentials` (write-only, never returned); never pass a provider key through a request.

## Tool catalog

24 capabilities, 27 tools as of this build (18 free/public, 9 priced) -- generated from the real catalog manifests:

- [https://toolgate.scribase.com/catalog](https://toolgate.scribase.com/catalog) -- human-browsable, with a `curl` snippet per tool.
- [https://toolgate.scribase.com/catalog.md](https://toolgate.scribase.com/catalog.md) -- the same content as markdown.
- `GET /v1/catalog` -- the same data as JSON.
- `GET /v1/tools/search?q=` -- search by task; `GET /v1/tools/{id}` -- schema, price, fallback chain, spends nothing.
- [https://toolgate.scribase.com/llms.txt](https://toolgate.scribase.com/llms.txt) / [https://toolgate.scribase.com/llms-full.txt](https://toolgate.scribase.com/llms-full.txt) -- machine-readable index.

## Billing & metering

Every paid call: **hold** (quoted price held before the call) -> **capture** (exact amount captured on success) -> **release** (hold released, nothing billed, on failure). Usage is also reported to Rago as `tool_call` events.

Spend caps -- project monthly, project daily, per-key daily, per-tool daily -- are enforced **synchronously in the request path**: each check adds spend-so-far plus every in-flight reservation and rejects with `429 cap_exceeded` before a hold is placed, so concurrent calls cannot race past a limit.

- `GET /v1/balance` / `POST /v1/balance/topup`
- `GET /v1/usage` / `GET /v1/usage/calls/{id}` (hash-chained receipt)
- `PATCH /v1/project` -- `monthly_cap_micros`, `daily_cap_micros`, `tool_daily_caps`, routing policy

Pricing model: [https://toolgate.scribase.com/pricing](https://toolgate.scribase.com/pricing).