# API Reference

FireImg API keys let server-side apps and CI/CD pipelines list, upload (and optionally moderate), and delete images without a browser session.

For use from a terminal, CI job, or coding agent, prefer the FireImg CLI (fireimg upload, fireimg projects, fireimg images). From Ruby, prefer the fireimg gem. This page is the HTTP contract those clients wrap.

Team owners can create, list, and revoke keys from API Keys in the FireImg dashboard. Give each key a descriptive name so you can identify its consumer later.

Keys begin with fimg_. The full key is shown only once when it is created, so copy it immediately and store it as a secret. The dashboard subsequently shows only the key prefix. Revoking a key takes effect immediately and cannot be undone.

Request one or more presigned upload URLs:

POST /v1/api/presigned-upload-urls
Content-Type: application/json
X-Api-Key: fimg_…

{
  "slug": "needapp",
  "files": [
    {
      "filename": "feed_items/43/uuid.jpg",
      "contentType": "image/jpeg"
    }
  ]
}

slug is the FireImg project slug. files must contain between 1 and 20 images. filename may include folders (for example feed_items/43/uuid.jpg); .. segments are rejected.

Optional sizes is a list of variants to generate asynchronously after the PUT (up to 20 entries). When present, these sizes replace the project's default image params for this upload. An empty list ("sizes": []) still overrides defaults and pre-generates only the 80px dashboard thumbnail. When sizes is omitted, the project defaults are used. The thumbnail is always included.

Each size uses the same fields as project default image params (width and/or height, plus optional quality, fmt, fit, pos, and fill):

POST /v1/api/presigned-upload-urls
Content-Type: application/json
X-Api-Key: fimg_…

{
  "slug": "needapp",
  "files": [
    {
      "filename": "hero.jpg",
      "contentType": "image/jpeg"
    }
  ],
  "sizes": [
    { "width": 1600, "quality": "high" },
    { "width": 800, "height": 600, "fit": "cover" }
  ]
}

Each response entry corresponds to the file at the same position:

{
  "urls": [
    {
      "filename": "feed_items/43/uuid.jpg",
      "uploadUrl": "https://…",
      "s3Key": "raw-images/…/feed_items/43/uuid.jpg",
      "expiresInSecs": 900
    }
  ]
}

Upload each file by making a PUT request to its uploadUrl. Send the raw file bytes and use the same Content-Type value supplied when requesting the URL:

PUT https://…
Content-Type: image/jpeg

<raw image bytes>

The presigned URL expires after expiresInSecs; it does not require the X-Api-Key header.

The image key used in CDN URLs is the sanitized filename (including folders).

After the PUT, request a Rekognition content scan. This is not automatic and does not apply a reject policy — FireImg returns labels so your app can decide. The POST is the gate:

POST /v1/api/projects/{slug}/images/moderation/{imageKey}
X-Api-Key: fimg_…

{imageKey} may contain slashes (feed_items/43/uuid.jpg). The handler reads the object in FireImg’s bucket (S3 object, not bytes through your app). JPEG and PNG only.

Typical responses:

{
  "moderation": "checked",
  "labels": [
    { "name": "Graphic Male Nudity", "parent": "Explicit Nudity", "confidence": 91.2 }
  ]
}

• { "moderation": "checked", "labels": [] } — scan completed; empty means nothing above Rekognition’s default 50% confidence
• { "moderation": "skipped_quota" } — monthly included checks exhausted
• { "moderation": "error_bypass", "reason": "…" } — Rekognition/IAM/format failure; no labels

Repeated checked calls return the stored labels (idempotent) and do not consume extra quota. Apply your own parent/category rules and confidence threshold. To remove an image after your policy rejects it, call DELETE.

Included checks per calendar month: Free 20, Lite 1,000, Starter 5,000, Growth 25,000.

DELETE /v1/api/projects/{slug}/images/{imageKey}
X-Api-Key: fimg_…

Soft-deletes the image (same as the dashboard). {imageKey} may contain folders.

GET /v1/api/projects
X-Api-Key: fimg_…

Returns every project the API key's team can access:

{
  "projects": [
    {
      "projectName": "NeedApp",
      "slug": "needapp",
      "teamId": "team_…",
      "createdAt": "2025-06-15T10:30:00Z"
    }
  ]
}

GET /v1/api/projects/{slug}/images?limit=100&nextToken=…&folder=feed_items
X-Api-Key: fimg_…

Returns one page of images. limit defaults to 100 and may be 1–1000. nextToken continues from a previous page. folder (optional) lists only images in that folder.

{
  "images": [
    {
      "imageKey": "feed_items/43/uuid.jpg",
      "s3RawKey": "raw-images/…/feed_items/43/uuid.jpg",
      "uploadedAt": "2025-06-15T10:30:00Z",
      "originalSizeBytes": 2048,
      "contentType": "image/jpeg",
      "variationsGeneratedCount": 1,
      "cacheVersion": 1
    }
  ],
  "folder": "feed_items",
  "nextToken": "eyJ…"
}

nextToken is omitted when there are no further pages. Pass it as nextToken on the next request to continue.

After upload, use the image filename (including folders) as its image key in the CDN URL:

https://img.fireimg.com/{project}/images/{imageKey}?width=764&quality=high&format=auto

Folder-key example:

https://img.fireimg.com/needapp/images/feed_items/43/uuid.jpg?width=800&quality=high&format=auto

See the Image URL reference for all transformation options.