Skip to main content

Developer reference / API v1

Upload files. Receive useful URLs.

A small HTTP surface for scripts, desktop tools, and products that need image hosting without inheriting a media platform.

01
Bearer auth
02
JSON + multipart
03
Direct-to-storage flow

The contract

01
One stable namespace
The public integration surface lives under /api/v1/ with ordinary HTTP requests and JSON responses.
02
A choice of upload paths
Use multipart or base64 for simple clients; use presigned storage uploads for larger files.
03
Links, not lock-in
Every completed upload returns direct, thumbnail, page, and embed-ready URLs.

Create a key in API, send it as a Bearer token, and call the endpoint that fits your client. For ShareX, start with the import-ready setup guide. The machine-readable surface is also available as OpenAPI JSON.

First upload

Three steps

  1. 01

    Create an API key

    Sign in and open API to generate a Bearer token. Copy it immediately — it is shown once.
  2. 02

    Upload an image

    Send POST /api/v1/upload with Authorization: Bearer … and a multipart file field.
  3. 03

    Use the direct URL

    The response includes direct_url, thumb_url, and embed codes in codes.

Need limits first? Call GET /api/v1/upload without auth.

API documentation

This reference is for webmasters and developers who integrate with imgtree: automation, mobile or desktop clients, forum tools (for example ShareX), or server-side scripts.

Base URL: use your site’s origin (for example https://img.example.com). All paths below are rooted at that origin.

Live limits: send an unauthenticated GET /api/v1/upload to receive JSON with the current max file size, allowed image types, rate-limit notes, and a short index of upload-related routes for this deployment.

Browser note: imgtree does not send broad Access-Control-* headers on the API. Call the API from your server or backend, or place your own proxy or edge rules if you need direct browser fetch from third-party pages.


API keys (recommended for integrations)

  1. Create a free account and sign in.
  2. Open Settings (or your dashboard’s API keys section) and create an API key.
  3. Copy the key when it is shown — it is only displayed once.
  4. Send it on every request as:
Authorization: Bearer <your_api_key>

The sections below describe the version 1 HTTP API (/api/v1/...), which uses this header. Current keys are tied to your account, and their uploads count against your storage quota.

Legacy-key compatibility: upload endpoints accept any non-empty Bearer token. If the token no longer matches a current account key (for example, because its old database record was lost), the image is stored as a public guest upload instead. Guest-fallback uploads are not attached to an account or album and do not count against a member quota. A missing Bearer token is still rejected. Suspended account owners cannot use this fallback. Account-only endpoints such as image listing and deletion continue to require a valid current key.


Upload flows compared

FlowBest forNotes
Multipart POST /api/v1/uploadShareX, form posts, small/medium filesSimplest; subject to host body-size limits
JSON + base64 POST /api/v1/uploadServer scripts, one image per requestBase64 inflates payload size
Presign → PUT → completeLarge originalsBypasses app-server body limit for the main file

For automation, start with multipart. Switch to presign when files exceed your host’s request body cap or when uploading from a client that already speaks S3-style PUT URLs.

Implementation note: Legacy multipart handlers (POST /api/upload, POST /api/upload/guest, and multipart POST /api/v1/upload) are thin route adapters. They read the request body and delegate to lib/store-image.ts (storeImageFromBuffer), which applies shared type/size policy (lib/upload/image-policy.ts), Sharp thumbnail generation, R2 storage, and DB insert. Response JSON shapes are unchanged. For large originals, prefer presign → PUT → complete so the main file bytes bypass the app server’s HTTP body limit.


Rate limits and quotas

  • Upload rate limit: about 30 requests per minute per client IP on upload routes (see GET /api/v1/upload for the exact wording on this deployment).
  • Storage quota: Uploads made with a current member key count against its owner’s quota. When the operator has turned on quota enforcement, an upload that would exceed the quota is refused (presign returns 413; multipart and completion report "Storage quota exceeded"). Unrecognized legacy keys fall back to guest storage.
  • Batch presign / complete: up to 20 files per batch request.
  • Pagination: GET /api/v1/images accepts limit up to 100.

When limited, the API responds with 429 Too Many Requests. Retry with backoff.


GET/api/v1/upload

Returns machine-readable capabilities for this instance: max upload size, allowed MIME types, presigned URL lifetime, batch limits, and brief endpoint descriptions. No Authorization header.

Use this in installers or scripts so you do not hard-code limits.


POST/api/v1/upload

Upload one or more images using multipart (typical for ShareX and form posts) or JSON with base64 for a single image (convenient from servers).

Multipart

Content-Type: multipart/form-data
Authorization: Bearer <your_api_key>

file: <binary>   # repeat the field name "file" for multiple files
albumId: <uuid>  # optional — must belong to your account

JSON (one image per request)

Content-Type: application/json
Authorization: Bearer <your_api_key>
{
  "filename": "screenshot.png",
  "contentType": "image/png",
  "file_base64": "<base64 or data:image/png;base64,...>",
  "albumId": "<optional uuid>"
}

The field base64 is accepted as an alias for file_base64.

Sizing: Base64 increases payload size. For large files, prefer multipart or the presign → PUT → complete flow below.

Unsupported Content-Type: the server responds with 415.

Image types: image/jpeg, image/png, image/gif, image/webp

Max size: Defined by this deployment (see GET /api/v1/upload). Multipart uploads may also be limited by your host’s maximum request body size.

Large files: Use POST /api/v1/upload/presign, PUT the bytes to put_url, then POST /api/v1/upload/complete with completion_token. That path bypasses your app server’s body limit for the main file.

Rate limiting: By default, about 30 requests per minute per client IP (see the discovery response for wording used on this instance).

Response 200

{
  "success": true,
  "images": [
    {
      "id": "abc12xyz",
      "url": "https://{origin}/i/abc12xyz",
      "direct_url": "https://{origin}/direct/{slug}.{ext}",
      "thumb_url": "https://{origin}/thumbnail/{slug}.webp",
      "delete_url": "https://{origin}/api/images/<uuid>?token=<delete_token>",
      "codes": {
        "bbcode": "[img]https://…[/img]",
        "bbcode_thumb": "[url=https://…][img]https://…/thumb[/img][/url]",
        "html": "<img src=\"https://…\" alt=\"file.jpg\" />",
        "markdown": "![file.jpg](https://…)",
        "direct": "https://…"
      }
    }
  ]
}

id is the image slug (public page /i/{slug}). delete_url uses the internal image UUID.

bbcode, html, and markdown embed a mid-size preview rendition (/preview/{slug}.webp, capped at 1600px long edge) rather than the full original, to keep forum/page embeds off the app's outbound bandwidth. Use direct (or direct_url) for the untouched original.

/direct/{slug}.{ext} content negotiation: for JPEG/PNG originals, /direct returns a re-encoded WebP (same dimensions, Content-Type: image/webp) when the request's Accept header includes image/webp — most browsers do this automatically for <img> tags, so existing [img]direct_url[/img] embeds get the smaller format with no changes needed. GIFs and already-WebP originals are never re-encoded. Append ?format=original to always get the exact bytes you uploaded regardless of Accept (this is what the app's own "Download" button uses).

Common errors

StatusMeaning
401Missing Bearer API key
403Account inactive
429Too many requests
400Bad request (for example no files)
500Server error

Per-file failures in multipart batches appear as objects with an error string instead of URLs.


POST/api/v1/upload/presign

Returns a time-limited URL to upload the original file bytes with PUT, using the same Content-Type you declare.

Request — Content-Type: application/json

{
  "filename": "photo.jpg",
  "contentType": "image/jpeg",
  "sizeBytes": 1234567,
  "albumId": "<optional uuid>"
}

Response 200

{
  "put_url": "https://…",
  "completion_token": "<opaque>"
}

Then: PUT to put_url with the raw bytes and header Content-Type matching contentType.


POST/api/v1/upload/presign/batch

Up to 20 presigns in one call (same auth and album rules as a single presign). When an unrecognized key falls back to guest mode, any supplied albumId is ignored.

Request — Content-Type: application/json

{
  "albumId": "<optional uuid>",
  "files": [
    { "filename": "a.jpg", "contentType": "image/jpeg", "sizeBytes": 1000 },
    { "filename": "b.png", "contentType": "image/png", "sizeBytes": 2000 }
  ]
}

Response 200

{
  "success": true,
  "uploads": [
    { "put_url": "https://…", "completion_token": "…" },
    { "error": "Filename required", "status": 400 }
  ]
}

Order matches files. After each successful PUT, call complete or complete/batch with the matching tokens.


POST/api/v1/upload/complete

Request — Content-Type: application/json

{ "completion_token": "<from presign>" }

token is accepted as an alias.

Response 200 — Same shape as POST /api/v1/upload (success, images[]).


POST/api/v1/upload/complete/batch

Finalize up to 20 direct uploads after PUT to each put_url.

Request — Content-Type: application/json

{
  "completion_tokens": ["<from presign>", "<from presign>"]
}

tokens is accepted as an alias for completion_tokens.

Response 200

{
  "success": true,
  "images": [
    { "id": "<slug>", "url": "…", "direct_url": "…", "thumb_url": "…", "delete_url": "…", "codes": { } },
    { "error": "Invalid or expired upload token" }
  ]
}

Order matches the input tokens. A current member key’s upload counter increases by the number of successful finalizations; guest-fallback keys have no counter.


GET/api/v1/images

Lists images owned by the API key (not deleted), with pagination.

Query: page (default 1), limit (default 24, max 100).

Response 200

{
  "success": true,
  "images": [
    {
      "id": "<uuid>",
      "slug": "…",
      "url": "https://{origin}/i/{slug}",
      "direct_url": "…",
      "thumb_url": "…",
      "original_name": "…",
      "created_at": "…"
    }
  ],
  "page": 1,
  "limit": 24,
  "total": 42,
  "has_more": true
}

DELETE/api/v1/images/[imageId]

Soft-deletes an image by UUID (imageId), using the API key. Behaviour matches an authenticated delete in the web app, without cookies.


ShareX (example custom uploader)

Replace the URL with your site and paste your API key:

{
  "Name": "imgtree",
  "DestinationType": "ImageUploader",
  "RequestMethod": "POST",
  "RequestURL": "https://{your-site}/api/v1/upload",
  "Headers": {
    "Authorization": "Bearer <your_api_key>"
  },
  "Body": "MultipartFormData",
  "FileFormName": "file",
  "URL": "$json:images[0].url$",
  "ThumbnailURL": "$json:images[0].thumb_url$",
  "DeletionURL": "$json:images[0].delete_url$"
}

Multipart vs presigned upload: ShareX’s single-request custom uploader works well with multipart POST /api/v1/upload. If your hosting enforces a small HTTP body limit (often a few megabytes), very large files may fail before they reach the app. For larger files, use presign → PUT → complete from a script or another client, or keep multipart uploads under the limit.


Signed-in session API (cookies)

These routes power the imgtree web app. They expect a logged-in browser session (session cookie), not the Bearer API key. Use them only if you are building tooling that runs as the signed-in user in a trusted environment.

Images

MethodPathDescription
GET/api/imagesPaginated list (page, limit ≤ 100)
PATCH/api/images/[imageId]Update allowed fields (owner only)
DELETE/api/images/[imageId]Soft delete; owner session or ?token=<delete_token> from a delete_url (rate limited)

GET /api/images returns { images, page, limit, total, has_more }.

Albums

MethodPathDescription
GET/api/albumsList albums
POST/api/albumsCreate album
GET/api/albums/[albumId]Album detail
PATCH/api/albums/[albumId]Update album
DELETE/api/albums/[albumId]Delete album

API keys (session)

MethodPathDescription
GET/api/keysList keys (metadata only)
POST/api/keysCreate key (secret returned once)
DELETE/api/keys/[keyId]Revoke key

Account security (session)

All writes are same-origin, rate limited per user, and answer 401 when signed out.

MethodPathDescription
GET/api/account/two-factorWhether two-factor sign-in is on, and how many recovery codes remain
POST/api/account/two-factor/setupBody { password }. Returns the setup key; 403 wrong password, 409 already on
POST/api/account/two-factor/confirmBody { code }. Turns it on; returns the recovery codes once
POST/api/account/two-factor/disableBody { password, code }; 403 when either is wrong
POST/api/account/two-factor/recovery-codesBody { password, code }. Replaces all recovery codes; returns the new ones once
GET/api/account/email/verification{ email, verified }
POST/api/account/email/verificationSend the confirmation link; 409 already verified, 503 email not configured
PATCH/api/account/emailChange address (marks it unverified and sends a link; response has verificationSent)
POST/api/auth/verify-emailBody { email, token }; consumes the link. 400 invalid/expired/used. POST only, so mail scanners that open links cannot use them up

Sign-in with two-factor on: the credentials form also takes a code (authenticator or recovery code). A wrong code counts toward the same lockout as a wrong password.

Upload (session and guest)

MethodPathDescription
POST/api/uploadSigned-in multipart (files, optional albumId, isPublic)
POST/api/upload/presignPresign for signed-in user
POST/api/upload/completeComplete after PUT (session)
POST/api/upload/guestPublic multipart upload
POST/api/upload/guest/presignGuest presign
POST/api/upload/guest/completeGuest complete after PUT

Multipart rows above delegate to storeImageFromBuffer (see Upload flows compared). Presign + complete routes use runPresignUpload and the direct-upload completion module instead.


Operator API (staff only)

Session-cookie authenticated (not API-key). Every route goes through one wrapper that enforces: same-origin on mutating methods (403), a signed-in staff role (401 without a session, 403 without the capability), a per-user rate limit (429 + Retry-After: 240 reads, 60 writes, 10 exports per minute), Content-Type: application/json on mutations that carry a body (415), and Cache-Control: no-store. Bulk endpoints return { changed, requested }: ids that were already in the target state or no longer exist are not counted and not audited, so a retry is safe. Unexpected errors return a generic 500 with an X-Request-Id header that matches the server log.

Roles: admin (everything), moderator (images, reports, read users), support (read users, images, albums, reports, API keys). Capability names are in lib/admin-permissions.ts.

MethodPathCapabilityDescription
GET/api/admin/statsoverview.readAggregated statistics
GET/api/admin/usersusers.readUser list (search, role, status, sort, page)
PATCH/api/admin/users/[userId]users.writeUpdate role (also needs users.role), isActive, storageQuota (bytes). Audited; last-admin and self-demotion rules apply
POST/api/admin/users/[userId]/unlockusers.writeClear a failed-login lockout
GET, POST/api/admin/users/[userId]/notesusers.notesList or add internal staff notes (1-2000 characters). Support and moderators may use these
DELETE/api/admin/users/[userId]/notes/[noteId]users.notesAuthors delete their own notes; admins any
POST/api/admin/users/[userId]/password-resetusers.write, admin onlyEmail the account holder a normal reset link (one hour, single use). The link is never shown to staff. 409 for suspended or password-less accounts, 503 if email is not configured
GET/api/admin/search?q=overview.read (any staff role)Command-palette search over accounts, images and reports (text of at least 2 characters or an exact id, 5 per group). Each group is returned only if the caller's role may read that area, so a moderator receives no data a list page would refuse them
GET/api/admin/imagesimages.readImage list (search by slug, name or exact id; visibility; owner)
PATCH/api/admin/images/[imageId]images.write{ isPublic, reason? }. Hiding places a moderation hold; publishing lifts it
DELETE/api/admin/images/[imageId]images.writeMove to Trash
GET/api/admin/images/[imageId]/content?variant=images.readStream thumbnail, preview or original. Full-size views of private or trashed images are audited
GET/api/admin/albumsalbums.readAlbum list
GET/api/admin/api-keysapiKeys.readAPI keys across accounts
PATCH/api/admin/api-keys/[keyId]apiKeys.writeRevoke ({ isActive: false })
GET/api/admin/reportsreports.readReports with owner and repeat-report context, plus the assignable staff list. Filters: status, assignee=me|unassigned
PATCH/api/admin/reports/[reportId]reports.writestatus, hideImage, note, assigneeId, priority
POST/api/admin/users/bulkusers.write{ ids (max 100), isActive }: suspend or reactivate in one audited transaction. The caller is never a target; suspending also revokes the accounts' API keys
POST/api/admin/images/bulkimages.write{ action: hide|publish|delete, ids (max 100), reason? }. Hiding places the moderation hold; delete moves to Trash and adjusts storage and album counters per owner
POST/api/admin/api-keys/bulkapiKeys.write{ ids (max 100) }: revoke active keys. Already-revoked keys are skipped
POST/api/admin/reports/bulkreports.write{ ids (max 100), status: resolved|dismissed, hideImage?, note? } in one audited transaction
GET/api/admin/auditaudit.readAudit log. Filters: action, targetId, actor (username or id), q (details text), from/to (UTC dates, inclusive)
GET/api/admin/users/exportexport.runAccounts matching the list filters as CSV. Never includes password or key hashes
GET/api/admin/images/exportexport.runImages matching the list filters as CSV (metadata only, no file URLs)
GET/api/admin/reports/exportexport.runReports matching the filters as CSV, including reporter IP addresses
GET/api/admin/audit/exportaudit.readSame filters as CSV (max 10,000 rows; X-Export-Truncated header). The export is itself audited
POST/api/admin/system/probesystem.readLive connectivity checks (database, storage, shared rate limiting, email). Read-only
POST/api/admin/system/purgesystem.writeRun the cleanup job now (409 if one is already running). Audited as system.purge
GET/api/admin/analytics/exportexport.runDelivery statistics CSV (audited)
GET, PUT/api/admin/settingssettings.read / settings.writeRuntime settings overrides
GET, PATCH/api/admin/announcementsettings.read / announcement.writeBanner messages