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.

​

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

   pari upload image ./cat.png
   
3. Upload the metadata

   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.

​

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 [e-mail] with the key id and the time of the request. Do not attach the image.

​

Next

Moderation

What is checked on every upload.

Launching

Use the uri in a launch.