# API reference

A small REST API for inspecting and cleaning text and files, included with every plan. Base URL `/api/v1`. Create a key at https://gifi.ai/api-keys.

## Authentication

Send the key as a bearer token. Keys are stored hashed, so the full value is shown once at creation and cannot be recovered afterwards.

```
curl https://gifi.ai/api/v1/usage \
  -H "Authorization: Bearer wmr_live_..."
```

## Rate limits and credits

Limits are per key, per minute. Exceeding one returns `429` with a `Retry-After` header.

| Plan     | Requests/min | Credits/month |
| -------- | ------------ | ------------- |
| Starter  | 30           | 300           |
| Pro      | 120          | 1,500         |
| Business | 600          | 6,000         |

Text operations cost no credits. Cleaning a file costs one. Failed jobs are refunded automatically, so you are never charged for work that did not complete.

## Endpoints

### POST /api/v1/inspect

Cost: free

Reports what is present without modifying anything.

```
curl -X POST https://gifi.ai/api/v1/inspect \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello\u200bworld"}'
```

Returns `verifiable` (each codepoint found, with offsets) and `bestEffort` (the writing-style heuristic). They are separate because one is a countable fact and the other is a judgement.

### POST /api/v1/clean

Cost: text free · file 1 credit

Cleans text, or a file sent inline as base64.

```
curl -X POST https://gifi.ai/api/v1/clean \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "The model\u2014which is large\u2014works."}'
```

```
curl -X POST https://gifi.ai/api/v1/clean \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file\": \"$(base64 -i photo.jpg)\", \"filename\": \"photo.jpg\"}"
```

Inline files are capped at 3 MB, because the platform limits request bodies to 4.5 MB and base64 inflates a file by a third. Use the web app’s direct upload for anything larger.

### GET /api/v1/usage

Cost: free

Credit balance, plan limits and the last 30 days of usage.

```
curl https://gifi.ai/api/v1/usage \
  -H "Authorization: Bearer $KEY"
```

## Errors

| Code | Meaning                                                                 |
| ---- | ----------------------------------------------------------------------- |
| 400  | Malformed request body                                                  |
| 401  | Missing, invalid or revoked key                                         |
| 403  | Key lacks the required scope, or the account has no active subscription |
| 402  | Insufficient credits                                                    |
| 413  | Payload too large                                                       |
| 422  | Processing failed — credits refunded                                    |
| 429  | Rate limited — see Retry-After                                          |

## Scope of what the API can promise

Character removals and metadata actions are verifiable: every response names what was removed and you can confirm it independently. The writing-style score is a heuristic. Nothing here certifies that content will pass or fail a third party’s AI detector — vendors publish neither detectors nor keys, so no tool can honestly make that claim. See [terms](https://gifi.ai/terms.md) for acceptable use.