{"openapi":"3.1.0","info":{"title":"imagebin.ca API","version":"1.0.0","description":"REST API for uploading and managing images. Authenticate with an audience-bound account API key (or a browser session). Scopes: image:create, image:read, image:delete."},"servers":[{"url":"https://imagebin.ca"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Account API key minted on the authority (token shape `pbca_live_…`), audience-bound to this site. Each call also accepts a signed-in browser cookie session; anonymous uploads require a Turnstile token instead."}},"schemas":{"Item":{"type":"object","properties":{"id":{"type":"string"},"kind":{"const":"image"},"content_type":{"type":["string","null"]},"size_bytes":{"type":"integer"},"width":{"type":["integer","null"]},"height":{"type":["integer","null"]},"created_at":{"type":"integer","description":"Creation time, epoch milliseconds."},"downloads":{"type":"integer"},"private":{"type":"boolean"},"ai_caption":{"type":["string","null"],"description":"AI caption, or null when opted out."},"ai_tags":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri"},"view_url":{"type":"string","format":"uri"},"direct_url":{"type":"string","format":"uri","description":"Cookieless CDN image URL."},"classification":{"type":"string","description":"Owner-only moderation classification."},"scan_state":{"type":"string","description":"Owner-only scan pipeline state."},"ai_caption_state":{"type":"string","description":"Owner-only caption pipeline state."},"ai_optout":{"type":"boolean","description":"Owner-only AI opt-out flag."},"dl_limit":{"type":["integer","null"],"description":"Owner-only download limit."}},"required":["id","kind","content_type","size_bytes","created_at","downloads","private","ai_caption","ai_tags","url","view_url","direct_url"],"additionalProperties":false},"ItemList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page, or null at the end."}},"required":["items","next_cursor"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"string"},"help_url":{"type":"string","format":"uri","description":"Plain-language help for this error code, when available."}},"required":["error"],"additionalProperties":true}}},"paths":{"/api/v1/items":{"post":{"summary":"Upload a image","description":"Send the image as a raw request body (with optional `x-*` metadata headers) or as `multipart/form-data` with a `file` field. Requires the `image:create` scope when authenticating with an API key.","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"x-filename","in":"header","required":false,"schema":{"type":"string"},"description":"Original filename (raw-body uploads)."},{"name":"x-title","in":"header","required":false,"schema":{"type":"string"},"description":"Item title."},{"name":"x-description","in":"header","required":false,"schema":{"type":"string"},"description":"Item description."},{"name":"x-tags","in":"header","required":false,"schema":{"type":"string"},"description":"Comma-separated tags."},{"name":"x-category","in":"header","required":false,"schema":{"type":"string"},"description":"Category: general | adult | humour."},{"name":"x-private","in":"header","required":false,"schema":{"type":"string"},"description":"Set to \"1\" to upload privately."}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary","description":"Raw image bytes."}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"title":{"type":"string","description":"Item title."},"description":{"type":"string","description":"Item description."},"tags":{"type":"string","description":"Comma-separated tags."},"category":{"type":"string","description":"Category: general | adult | humour."},"private":{"type":"string","description":"Set to \"1\" to upload privately."}},"required":["file"]}}}},"responses":{"200":{"description":"image metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"400":{"description":"Not found (or not visible to the caller).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/items/{id}":{"get":{"summary":"Read image metadata","description":"Public images need no credentials. Owners (API key with `image:read`, or cookie session) additionally see moderation/pipeline fields.","security":[{"bearerAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque image id."}],"responses":{"200":{"description":"image metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"404":{"description":"Not found (or not visible to the caller).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"The item existed but is no longer available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a image","description":"Deletes an owned image. Requires the `image:delete` scope (or an authenticated owner session).","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Opaque image id."}],"responses":{"200":{"description":"Deleted."},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Authenticated but missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (or not visible to the caller).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account/items":{"get":{"summary":"List your images","description":"Newest-first, cursor-paginated. Requires the `image:read` scope (or an authenticated owner session).","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"classification","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by classification."},{"name":"private","in":"query","required":false,"schema":{"type":"string","enum":["0","1"]},"description":"Filter by privacy."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text search."}],"responses":{"200":{"description":"A page of your images.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemList"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}