sherserve

Base path /api/sherserve/v1. See API reference for authentication and the api.shebang.pro rewrite.

Every route requires an shb_... key or bearer with serve in scope (master keys always qualify). project behaves exactly as described in platform. An object's access level, password, expiry, and view budget live on its sherlink short link — see access modes.

The Object returned by metadata routes:

{
  "id": "uuid",
  "public_id": "string",
  "url": "string",
  "shortUrl": "string | null",
  "slug": "string",
  "title": "string",
  "originalFilename": "string",
  "contentType": "string",
  "sizeBytes": "number",
  "access": "private | password | allow_list | public",
  "status": "active | archived",
  "expiresAt": "ISO 8601 | null",
  "maxViews": "number | null",
  "viewCount": "number",
  "createdAt": "ISO 8601",
  "updatedAt": "ISO 8601",
  "archivedAt": "ISO 8601 | null"
}

GET /api/sherserve/v1/objects

Lists objects.

• Auth — serve scope.
• Query params — status ("active" or "archived", defaults to "active"), project (slug, optional).
• Response — 200 { "objects": [Object, ...], "project": "slug" }.
• Errors — 400 invalid status filter, 403 insufficient_scope.

POST /api/sherserve/v1/objects

Uploads a file — creates the resource row, stores the bytes, and mints its short link in one call. Rolls back everything already created if a later step fails. Body is multipart/form-data, not JSON.

• Auth — serve scope, write access to the target project.
• Request body (form fields) — file (required, ≤ 500 MB), title (optional, defaults to the filename), slug (optional — derived from title if omitted, auto-suffixed on collision only when omitted), access (default "private"), password (required if access is "password"), expiresAt (ISO 8601, optional), maxViews (positive integer, optional), alias (optional), allow (repeated field and/or comma-separated, optional), project (slug, optional).
• Response — 201 { "object": Object, "url", "shortUrl", "project" }.
• Errors — 400 (missing/invalid file, title, slug, access, password, expiresAt, maxViews, alias, allow entry, or a malformed multipart body), 400 password_required, 409 slug_conflict, 409 alias_conflict, 413 file too large, 415 (unsupported file type — no extension or content type to infer one from), 403 insufficient_scope, 500 public_id_exhausted.

GET /api/sherserve/v1/objects/{id}

Fetches one object.

• Auth — serve scope, read access to the object's project.
• Path params — id (uuid).
• Response — 200 Object.
• Errors — 404 not_found, 403 insufficient_scope.

GET /api/sherserve/v1/objects/{id}/content

Downloads an owner's original file bytes. Uses the same bearer credentials as metadata, including for private objects. Visitor link passwords, expiry, archive status, and view budgets do not restrict this owner operation.

• Auth — serve scope, object ownership, read access to its project.
• Path params — id (uuid).
• Response — 200 streamed file bytes with the stored content type, an attachment filename, and Cache-Control: private, no-store. Always returns the complete original file; ranges and image transforms are not applied.
• Errors — 401 (invalid credentials), 403 insufficient_scope, 404 not_found (invalid ID, wrong owner, or missing row/bytes), 500 internal_error (storage unavailable).

PATCH /api/sherserve/v1/objects/{id}

Updates an object's content fields and/or its link's policy fields. The row commits first; if the link update then fails, the row is reverted.

• Auth — serve scope, write access to the object's project.
• Path params — id (uuid).
• Request body — any of title, slug, access, password (string or null), expiresAt (string or null), maxViews (number or null), alias (string or null), status ("active" or "archived") — all optional.
• Response — 200 Object.
• Errors — 400 (invalid field value), 404 not_found, 409 slug_taken, 409 alias_conflict, 400 password_required, 403 insufficient_scope.

DELETE /api/sherserve/v1/objects/{id}

Deletes an object — its stored bytes, its short link, then the row.

• Auth — serve scope, write access to the object's project.
• Path params — id (uuid).
• Response — 204 (empty body).
• Errors — 404 not_found, 403 insufficient_scope, 500 storage_cleanup_failed, 500 link_cleanup_failed.

Next

sherlink — short links and access.