# WebYore API v1 integration context

Use this document as the concise integration context for WebYore. The canonical, complete contract is OpenAPI 3.1:
https://api.webyore.com/openapi.json

## Service

WebYore creates and manages safe redirecting Short Links, immutable asynchronous Snapshots, QR codes backed by managed Short Links, privacy-preserving aggregate analytics, bounded Hosted Images, and verified custom domains.

API base URL:
https://api.webyore.com/v1

## Authentication and secrets

Send an account API key as a Bearer token:
Authorization: Bearer wy_live_your_key

Never put an API key in a URL, browser-delivered JavaScript, a mobile application binary, logs, or source control. Call WebYore from trusted server-side code or a protected backend.

## Scopes

GET /usage reports images.storage_bytes.used against the caller's limit. Ordinary credentials exclude Partner uploads from used; unmetered credentials receive the account total and a null limit. total_used always includes both classes; unmetered_used identifies Partner bytes. These storage figures include pending upload reservations. Partner keys do not consume ordinary key slots.

Grant only the minimum independent scopes required by the integration:

- 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, 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

A write scope does not imply the corresponding read scope.

## Mutation safety

Every POST, PATCH, and DELETE request requires:
Idempotency-Key: a unique value containing 8 to 128 characters

WebYore retains an idempotency record for 24 hours. The same key with the same request can be retried safely. Reusing a key with different content returns HTTP 409.

## Quick start: create a Short Link

Required scope: links:write

POST https://api.webyore.com/v1/links
Authorization: Bearer wy_live_your_key
Content-Type: application/json
Idempotency-Key: request-20260831-0001

Request body:
{
  "url": "https://example.com/article"
}

Successful response: HTTP 201
{
  "data": {
    "id": "link_...",
    "slug": "Ab3dEf4",
    "short_url": "https://webyore.com/Ab3dEf4",
    "destination_url": "https://example.com/article",
    "publication_status": "active"
  },
  "meta": {
    "request_id": "req_..."
  }
}

Treat fields omitted from this abbreviated response as defined by OpenAPI. Do not invent undocumented request or response fields.

## Common endpoints

- POST /links - create a Short Link
- GET /links - list and search Short Links
- GET /links/{id} - read one Short Link
- PATCH /links/{id} - change a Short Link destination or options
- DELETE /links/{id} - disable a Short Link
- GET /links/{id}/qr - download its QR code
- GET /links/{id}/analytics - read aggregate analytics
- GET /links.csv - export Short Links
- POST /snapshots - create an immutable Snapshot
- GET /snapshots/{id} - read Snapshot capture status
- POST /images - upload a Hosted Image
- POST /images/url - import a public image URL
- GET /images - list Hosted Images
- GET /images/{id} - read processing, delivery, and rating state
- PATCH /images/{id}/rating - set an owner content-rating declaration
- DELETE /images/{id} - delete a Hosted Image
- POST /domains - register a pending custom domain
- GET /usage - read plan and quota usage

## Hosted Images

Initial upload and URL import accept content_rating values auto, general, or nsfw. auto runs the configured classifier; general and nsfw are audited owner declarations that skip automatic classification. Post-upload owner declarations accept general, sensitive, or nsfw. A stricter declaration applies immediately; lowering the effective rating can require operator review.

URL import requires a direct public URL whose response contains supported image bytes. A post, HTML share page, private address, unsafe redirect, or non-image response is rejected. Some CDNs return 403 specifically to server-side fetches; the WebYore product UI can offer a consented browser-download fallback, while API clients should download locally and submit the bytes to POST /images as multipart data. Poll status_url until status is ready. url is the immutable WebP for embedding; share_url is the session-neutral viewer page with rating context and a report action.

New image IDs are 7 characters; existing longer IDs remain valid. GET or HEAD the direct image URL without an API key to read X-WebYore-Content-Rating: general, sensitive, nsfw, or unrated. HEAD downloads no image body. Cross-origin browser fetches can read the header. The current effective rating is checked on every request; downstream responses use Cache-Control: no-store while immutable image bytes remain cached internally. Unavailable images do not return a rating header for the placeholder.

On read, content_rating is null while status is processing and is always one of general, sensitive, nsfw, or unrated once status is ready. unrated means classification did not produce a usable result; it is not a claim that the image is general. Treat unrated with the same caution as nsfw whenever you need a safe default, and branch on the full set of values rather than testing only for nsfw.

Consult OpenAPI before implementing less common endpoints, multipart uploads, pagination, QR options, UTM parameters, custom-domain proof, or complete response models.

Operator-issued Unmetered Partner Keys skip WebYore product request rates, IP/account/host quotas, image monthly/storage quotas, Snapshot host/account limits, custom-domain plan/count/rate limits and link expiry plan ceilings. WebYore has no application-wide image storage, Snapshot, registration, email or Web Risk budget caps. Ordinary per-account/IP/mailbox/host limits remain; Web Risk security checks still run. GET /usage reports null quota limits for Partner keys; image storage and delivery bytes remain recorded for operations, not global admission gates. New Partner images keep this exemption through asynchronous processing and plan-entitlement retention. Authentication, scopes, ownership, idempotency, moderation, feature pauses, file validation and actual provider capacity still apply. The image pipeline accepts files up to 10 MiB (10485760 bytes), with no dimension, frame-count or total-pixel admission limits. Images publish before background classification; classification failure never revokes publication. New uploads publish only WebP, preserving dimensions and frames except proportional scaling beyond codec dimensions. Validated existing WebP is retained with private metadata removed. Conversion keeps timeout and memory protection; temporary failures retain private sources for up to 24 hours with leased, durable retries using a faster encoding tier. Polling timeout is not upload failure: resume status_url polling without reuploading. Legacy non-WebP URLs remain readable but are not reused for new uploads. Pagination and field-length contracts remain unchanged. Cloudflare edge rate rules are separate from Worker limits.

## Errors

Errors use a structured body:
{
  "error": {
    "code": "api_scope_required",
    "message": "The API key is missing a required scope.",
    "request_id": "req_...",
    "detail": "links:write"
  }
}

Handle HTTP status codes and error.code. Do not branch on human-readable message text. Preserve request_id in logs and support reports, but never log the API key.

Typical statuses include 400 invalid input, 401 invalid authentication, 403 insufficient scope or entitlement, 404 missing resource, 409 idempotency conflict, 413 payload too large, 415 unsupported media type, 422 rejected remote content, 429 rate limit, and 503 temporary dependency failure.

## Implementation checklist

1. Load the API key from a server-side secret.
2. Grant only required scopes.
3. Set a fresh Idempotency-Key for each logical mutation.
4. Apply bounded timeouts and retry only safe requests.
5. Parse the data and meta envelopes.
6. Follow the OpenAPI schema instead of guessing fields.
7. Keep canonical WebYore Short Links even when a custom domain is also used.