# Getting started

The QuassLabs API is a set of small, deterministic HTTP endpoints. Almost none of
them call a language model, so the same input gives the same output every time,
and a call costs about as much as the arithmetic it performs.

Everything here is also available as an MCP tool. If you are connecting from
Claude or another MCP host, read [Claude and MCP](claude-mcp.md) instead — you
will not need to write any HTTP code at all.

## 1. Get a key

During the beta, keys are issued by hand. Request one at
[quasslabs.com](https://quasslabs.com) and you will receive a token that looks
like `qlk_` followed by a random string.

There is no self-serve signup yet, and `POST /v1/keys` will not help you: it
requires a key that already holds the `admin` scope, and it refuses to grant that
scope to anything it creates. It exists so operators can issue keys, not so
callers can mint their own.

Store the token when you receive it. Only a SHA-256 hash is kept server-side, so
a lost key cannot be recovered — it can only be revoked and replaced.

## 2. Make a call

The quickest way to see a real response is the [API reference](../reference.html) —
every endpoint has a request console that calls the API directly from your
browser. Paste a key, edit the example body, send. Use a low-credit key for that
rather than a production one; nothing is proxied or stored, but you are typing a
credential into a web page.

To do it from a terminal instead, send the key as a Bearer token. Here is the
cheapest useful call on the platform, scoring a piece of prose for AI-writing
tells:

```bash
curl -sS https://api.quasslabs.com/v1/humanizer-score \
  -H "Authorization: Bearer qlk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "In today'\''s rapidly evolving landscape, it is important to note that leveraging synergies can unlock transformative value."}'
```

Every endpoint follows the same shape: `POST`, a JSON body, a JSON response.
There are no query parameters, no path parameters, and no endpoint that needs a
`GET`. The full request and response schema for each one is in the
[API reference](../reference.html), and in machine-readable form in
[openapi.json](../openapi.json).

## 3. Understand what you were charged

Each successful call decrements your key's credit balance by that endpoint's
cost. Most endpoints cost 1 credit; the ones that do more work — `alignment-gate`,
`log-analyzer`, `log-audit-creator` — cost 2. The `uploads` endpoint is free: it
only mints a presigned URL, and the endpoint that later reads the file is what
charges you.

Three rules make the billing predictable:

- **Rate limits are checked before credits.** A `429` never costs you anything.
- **The decrement is atomic and conditional.** If your balance is short you get
  `402 insufficient_credits`, and the endpoint does not run — you are not charged
  for a call that produced nothing.
- **Server errors are refunded.** If a call fails with a `5xx`, the credits are
  returned automatically. A failure on our side is not your bill.

Each metered response carries a `request_id`. Quote it if you need to ask about a
specific call.

## 4. Check your balance

**Your balance is not currently readable through the API.** There is no endpoint
that returns it and no response header that carries it. Today, the way you learn
you have run out is a `402 insufficient_credits` on your next call.

This is a known gap rather than a design decision, and it is the first thing on
the list to fix. Until it is, if you are running anything unattended, treat `402`
as an expected condition and alert on it rather than retrying — retrying a `402`
will never succeed on its own, because nothing about your key changes until it is
topped up.

## What to read next

- [Claude and MCP](claude-mcp.md) — connect the whole toolset to Claude, Claude
  Code, or any MCP host in one config block.
- [ChatGPT and OpenAI](chatgpt.md) — function-calling definitions and a Custom
  GPT Action.
- [Errors and limits](errors.md) — every error code and what to do about each.
- [API reference](../reference.html) — request and response schemas for all endpoints.