DEVELOPER API

WebYore API v1

Use a scoped API key from your WebYore account. Every mutation request must include an Idempotency-Key.

OpenAPI 3.1 Manage API keys

QUICK START

Create your first Short Link

Choose a language, replace the sample API key and destination, then send your first request.

Base URL: https://api.webyore.com/v1
Authentication: Bearer API key
Required scope: links:write
Mutation safety: Idempotency-Key

curl --request POST \
  --url https://api.webyore.com/v1/links \
  --header 'Authorization: Bearer wy_live_your_key' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: request-20260831-0001' \
  --data '{"url":"https://example.com/article"}'

Start the integration with AI

Copy a concise API contract without personal credentials and paste it into ChatGPT, Claude, Gemini, or another coding assistant.

View AI context llms.txt

REFERENCE

Complete API reference

Expand the scope matrix, error contract, or endpoint overview when needed. OpenAPI 3.1 remains authoritative for complete data models.

Authentication and safe retries Bearer API keys, Idempotency-Key, and the 24-hour replay contract

Authentication

Every API request uses a Bearer API key created in your account. Send it in the Authorization header, never in a URL or public client-side code.

Authorization: Bearer wy_live_your_key

Idempotency-Key

Every POST, PATCH, and DELETE request requires a unique 8-128 character Idempotency-Key. WebYore retains the record for 24 hours.

Idempotency-Key: request-20260831-0001

The same key and request can be retried safely. Reusing a key with different content returns a 409 conflict.

Hosted Images API Uploads, URL imports, content ratings, and two delivery URLs

Upload and URL import

Initial creation accepts auto, general, or nsfw. URL import requires a public URL that directly returns image bytes. If the source rejects the server with 403, the web UI can offer a consented browser import; API clients can download the file locally and use multipart upload instead.

POST /images/url
Content-Type: application/json
Idempotency-Key: image-import-0001

{
  "url": "https://example.com/photo.jpg",
  "content_rating": "auto"
}

Status, ratings, and delivery

Poll status_url after creation. A ready image can be embedded using url. Regular images use WebP; large animations retain WebP or GIF. Use the returned URL and mime_type rather than constructing an extension. share_url includes rating context and a report action. Automatic classification completes in the background: ready does not mean rated. content_rating may initially be unrated; fetch GET /images/{id} or HEAD the direct URL for updates. unrated means pending or no usable result, never SFW; treat it as cautiously as nsfw when a safe default is required.

PATCH /images/{id}/rating
Idempotency-Key: image-rating-0001

{ "content_rating": "sensitive" }

New image URLs use 7-character IDs; existing URLs remain valid. Send HEAD to the direct image URL without an API key to read X-WebYore-Content-Rating without downloading the image: general, sensitive, nsfw, or unrated. Cross-origin JavaScript can also read this header. Unavailable or processing images omit the rating header.

curl -I "https://i.webyore.com/Ab3De7X.webp"

X-WebYore-Content-Rating: nsfw

API key scopes 9 independent least-privilege scopes

Grant only the minimum access an application needs. Read scopes never permit creation, changes, or deletion.

Every scope is independent. A write scope does not grant read access, and a read scope does not grant write access.

Scope	Permitted access
`links:read`	Read, search, and export Short Links; download QR codes
`links:write`	Create, update, and disable Short Links; manage UTM presets
`snapshots:read`	Read Snapshot capture and publication status
`snapshots:write`	Create Snapshots
`images:read`	Read hosted images, delivery URLs, and rating metadata
`images:write`	Upload, import by URL, rate, and delete hosted images
`analytics:read`	Read privacy-preserving aggregate link analytics
`domains:read`	Read custom domains and verification state
`domains:write`	Register, verify, and disable custom domains

Insufficient scope response HTTP status, structured errors, and request_id

Insufficient scope response

When a required scope is missing, the API returns 403 with a structured api_scope_required error. detail names the scope required for that operation.

{
  "error": {
    "code": "api_scope_required",
    "message": "The API key is missing a required scope.",
    "request_id": "req_...",
    "detail": "images:write"
  }
}

Endpoint overview Short Link, Snapshot, image, and domain endpoints

Method	Path	Purpose
POST	`/v1/links`	Create a Short Link
GET	`/v1/links`	List Short Links
PATCH	`/v1/links/{id}`	Change a destination
GET	`/v1/links/{id}/qr`	Download a Short Link QR code
GET	`/v1/links/{id}/analytics`	Read aggregate click analytics
GET	`/v1/links.csv`	Export Short Links as CSV
POST	`/v1/snapshots`	Create an immutable Snapshot
GET	`/v1/snapshots/{id}`	Read Snapshot capture status
POST	`/v1/images`	Upload a hosted image
POST	`/v1/images/url`	Import an image from a public URL
GET	`/v1/images`	List hosted images
GET	`/v1/images/{id}`	Read image processing and delivery state
PATCH	`/v1/images/{id}/rating`	Set an owner content rating
DELETE	`/v1/images/{id}`	Delete a hosted image
POST	`/v1/domains`	Register a custom Short Link domain
GET	`/v1/usage`	Read quota usage