Skip to main content

​
Overview

Relay is the Snipp API geared toward the full user experience. It mirrors the public API for uploads and posts, and adds the discover feed, likes, comments, notifications, blocking, profile editing, avatar and banner uploads, and view counting. Relay is intended for first-party clients (for example, the Snipp mobile app). For third-party integrations and SDKs, use the public API at api.snipp.gg.

​
Base URL

The default base URL is:
relay.snipp.gg is a load balancer sitting in front of the Relay servers. It resolves to the nearest healthy region and connects straight to it, with no per-request size cap, so your file size limit is whatever your plan allows. It is the right default for everything, including uploads.

​
Regional endpoints

Regional endpoints reach the same servers as relay.snipp.gg and upload at the same speed, so pinning one buys you no performance. Use them when you want to control which region stores your files, or to force a specific server instead of letting the load balancer choose. To confirm which region served a request, hit GET /region on any host.

​
Alternative endpoint

pulsar.snipp.gg serves the same Relay API over a separate network path. Requests are buffered before they reach the server, so uploads there are capped at 100 MB per request and large uploads are several times slower. Use it only as a fallback if relay.snipp.gg is ever unreachable.

​
Authentication

Relay uses a relay-key header. Each Snipp account has a unique relay key. Treat it like a password.
Generate, regenerate, or delete your relay key from snipp.gg/settings/relay. Keys are 32 alphanumeric characters ([A-Za-z0-9]). A missing, empty, or unrecognized relay key returns 401.

​
Team Access Keys

Teams (an Ultra feature) each have a dedicated access key. Pass it in the relay-key header in place of a personal relay key, and uploads go to the team’s shared gallery instead of a personal account. It works on POST /upload, PATCH /posts/{code}, DELETE /posts/{code}, POST /posts/{code}/files, DELETE /posts/{code}/files/{name} and POST /convert; every other endpoint is personal only and returns 401 for a team key.
Key differences when uploading with a team key:
  • Files are stored in the team gallery, not a personal gallery.
  • Uploads count against the team’s weekly quota, never a member’s personal quota.
  • Team-key uploads are always created private, regardless of the post-privacy header, and their privacy cannot be changed afterward. Team posts are never unlisted or public.
  • Only the team owner can regenerate or delete the key, from the team’s settings page.
  • If the team’s subscription lapses, uploading, adding files and converting with the key return 403 with type forbidden. Editing and deleting existing team posts keep working.
  • Team members can also edit team posts with their own relay key, through PATCH /posts/{code}, unless their role is viewer.
  • If the team owner’s account is suspended, the key is refused with 403 on every endpoint that accepts it.
Anyone who holds a team key can upload with it, so treat it like any other credential and share it only with trusted team members.

​
Endpoints

Wherever a user ID goes in the path, @me works too.

​
View Counting

Relay does not expose a dedicated view endpoint. Views increment automatically when a viewer hits GET /posts/{code} or GET /discover. To prevent inflation, views are deduplicated per IP and post: an IP can contribute up to 3 counted views per post per hour. Views are only counted on public, non-moderated posts.

​
Conventions

Relay follows the same conventions as the API: JSON bodies with snake_case keys, resources in the path, limit and cursor pagination, ISO 8601 timestamps, and a request-id header on every response.

​
Errors

Errors return a non-2xx status and an error object with a stable type and a readable message:
See Errors for every type and status.

​
Rate Limits

Rate limits apply per endpoint, not per account. See Rate Limits for the full table and how to handle 429 responses. Upgrading from the old endpoints such as /follow, /like or /profile? See the migration guide.