{"openapi":"3.1.0","info":{"title":"swiftimg API","version":"1.0.0","description":"Fast image & GIF hosting and an image CDN & API for developers. Upload, host, and embed images programmatically; on-the-fly resize and format on the delivery side via signed URLs.","contact":{"name":"swiftimg","url":"https://swiftimg.com/about"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://swiftimg.com/v1","description":"Production"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"API keys are created on /account. Pass as `Authorization: Bearer <key>`."}},"schemas":{"Image":{"type":"object","required":["id","kind","status","mime","createdAt"],"properties":{"id":{"type":"string","description":"Short, content-addressable id."},"kind":{"type":"string","enum":["image","gif","video"]},"status":{"type":"string","enum":["processing","ready","quarantined","deleted"]},"mime":{"type":"string","example":"image/png"},"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"bytes":{"type":"integer","nullable":true},"title":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"createdAt":{"type":"string","format":"date-time"},"directUrl":{"type":"string","format":"uri","description":"Direct image URL on the delivery CDN."},"pageUrl":{"type":"string","format":"uri","description":"Hosted viewer page (with OpenGraph + oEmbed)."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine code."},"message":{"type":"string","description":"Human-readable detail."}}}}},"security":[{"bearerAuth":[]}],"paths":{"/health":{"get":{"summary":"Health check","description":"Returns 200 OK with a small JSON status payload. Unauthenticated.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}}}},"/gifs/search":{"get":{"summary":"Search animated GIFs","description":"Public GIF search across uploaded animated content. Returns ready GIFs whose title or tags match the query, scored by FTS5 rank. Unauthenticated.","security":[],"parameters":[{"in":"query","name":"q","required":true,"schema":{"type":"string"},"description":"Search query (matched against title and tags)."},{"in":"query","name":"limit","schema":{"type":"integer","default":30,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Image"}}}}}}}}}},"/gifs/trending":{"get":{"summary":"Trending animated GIFs","description":"Returns the most-viewed animated GIFs, newest first within ties. Useful as the default surface for a GIF picker before the user types a query. Unauthenticated.","security":[],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":30,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Image"}}}}}}}}}},"/images":{"post":{"summary":"Upload an image","description":"Anonymous uploads work without a key but get the free-tier daily cap. Pass an API key to attribute the upload to your account and lift the cap. `src` attributes the upload to a marketing channel for the funnel.","security":[{"bearerAuth":[]},{}],"parameters":[{"in":"query","name":"src","schema":{"type":"string"},"description":"Acquisition source tag (e.g. `cli`, `sharex`)."},{"in":"query","name":"cid","schema":{"type":"string"},"description":"Stable client id for cookie-less callers (the ShareX `.sxcu` mints one, `@swiftimg/cli` persists one per install)."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"title":{"type":"string"},"tags":{"type":"string","description":"Comma-separated tags."},"album_id":{"type":"string"}}}}}},"responses":{"201":{"description":"Upload accepted; the asset is in `processing` until variants are generated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"File too large for tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate-limited (free tier daily cap)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/images/mine":{"get":{"summary":"List my images","description":"Returns the authenticated caller's images, newest first.","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50}},{"in":"query","name":"cursor","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"nextCursor":{"type":"string","nullable":true}}}}}}}}},"/images/{id}":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get image metadata","security":[{"bearerAuth":[]},{}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Image"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete an image","description":"Authenticated callers can delete their own images. Anonymous uploads can be deleted with the `delete_token` returned at upload time.","security":[{"bearerAuth":[]},{}],"parameters":[{"in":"query","name":"token","schema":{"type":"string"},"description":"Delete token for anonymous uploads."}],"responses":{"204":{"description":"Deleted"},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/images/{id}/signed-url":{"get":{"summary":"Generate a signed transform URL","description":"Returns a signed delivery URL with the requested width/format. Developer plan only.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"w","schema":{"type":"integer"},"description":"Target width in pixels."},{"in":"query","name":"fm","schema":{"type":"string","enum":["webp","jpeg","png"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}},"402":{"description":"Plan upgrade required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys":{"get":{"summary":"List my API keys","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true}}}}}}}}}}},"post":{"summary":"Create an API key","description":"Returns the secret only once at creation time.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"Plaintext key — store immediately."}}}}}}}}}}}