> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pariprotocol.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploads

> Upload endpoints, limits and error codes.

## What it is

The hosted service stores token images and metadata for **registered** integrators. It does nothing else: no transaction building, no custody. It uses the same moderation as the Pari site.

## When to use it

Use it when you do not host your own metadata. Its URIs are short enough for the launch transaction. See [Launching](https://docs.pariprotocol.xyz/build/launching.md).

## Step by step

**1. Get your key**

You get the key after registration, and it is shown once. Set it as `PARI_API_KEY` for the CLI. Requests use `Authorization: Bearer <api key>`.

**2. Upload the image**

```sh theme={null}
pari upload image ./cat.png
```

**3. Upload the metadata**

```sh theme={null}
pari upload metadata --name Cat --symbol CAT --description "A cat" --image https://m.pariprotocol.xyz/i/<id>
```

**4. Launch with the returned uri**

See [Launching](https://docs.pariprotocol.xyz/build/launching.md).

## Endpoints

| Method and path | Body | Success |
| - | - | - |
| `POST /v1/images` | Raw image bytes with `Content-Type` `image/png`, `image/jpeg`, `image/webp` or `image/gif` | `201 { id, url, width, height }` |
| `POST /v1/metadata` | JSON `{ name, symbol, description, image, website?, twitter?, telegram? }` | `201 { id, uri }` |
| `GET /v1/limits` | None | `200 { perMinute, perDay, usedMinute, usedDay }` |
| `POST /v1/integrator-requests` | JSON from the request form, no key needed | `201 { id, answerWithinHours: 24 }` |

`image` in the metadata body must be a `url` returned by `/v1/images` for the same key. The service builds the stored JSON from the validated fields. It never stores your blob.

## Numbers and limits

* **Image:** at most 2 MiB, 64 to 2048 pixels per side.
* **Metadata:** at most 4 KiB. Name 32 characters, symbol 10, description 1000, links 200 and `https` only.
* **Rate:** 30 requests per minute and 200 uploads per day per key, by default.
* **Request form:** 5 requests per IP per day, 2 KiB body.

The service re-encodes every image and drops its metadata (EXIF and the rest). You get back the stored copy.

Served files are immutable (`Cache-Control: public, max-age=31536000, immutable`) until a takedown removes them. After that, their URL returns `404`.

## What can go wrong

Errors are `{ "error": "<code>" }`.

| Status | `error` | Meaning and what to do |
| - | - | - |
| 400 | `invalid_metadata`, `invalid_request` | A field is missing, too long or not `https`. Fix it. |
| 401 | `unauthorized` | Missing or unknown key. |
| 403 | `revoked` | The key was revoked. Ask for a new one. |
| 413 | `too_large` | Over the size cap. Shrink the file. |
| 415 | `bad_type` | Not a PNG, JPEG, WebP or GIF. |
| 422 | `type_mismatch`, `bad_dimensions`, `image_not_owned` | The bytes do not match the declared type, the size is outside 64 to 2048 px, or the image was not uploaded with this key. |
| 429 | `rate_limited` | Wait for `Retry-After` seconds. The SDK marks this error retryable. |
| 451 | `matched` | The image matched a hash list. See below. |
| 503 | `matcher_unavailable` | A moderation check could not run. The service fails closed. Safe to retry later. |

### A 451 response

`451 matched` means the image, or its re-encoded copy, matched a hash list. Nothing was stored.

* Do not retry the same bytes. They will match again.
* A different picture is a different upload. Do not make small edits to get around a match: the operator can revoke a key.
* If you believe it is a mistake, write to [support@pariprotocol.xyz](mailto:support@pariprotocol.xyz) with the key id and the time of the request. Do not attach the image.

## Next

> [card] [Moderation](https://docs.pariprotocol.xyz/build/moderation.md)
>
> What is checked on every upload.

> [card] [Launching](https://docs.pariprotocol.xyz/build/launching.md)
>
> Use the uri in a launch.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.