{"openapi":"3.1.0","info":{"title":"Clearify AI API","version":"v1","description":"Programmatic AI image upscaling and enhancement for Clearify AI accounts."},"servers":[{"url":"https://api.clearifyai.net/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/health":{"get":{"operationId":"getHealth","security":[],"summary":"Health check","responses":{"200":{"description":"Service health","content":{"application/json":{"example":{"status":"ok","service":"clearify-api","version":"v1"}}}}}}},"/me":{"get":{"operationId":"getCurrentApiAccount","summary":"Get current API account","responses":{"200":{"description":"API account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiAccount"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/uploads":{"post":{"operationId":"createUpload","summary":"Create an upload target","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUploadRequest"},"example":{"filename":"photo.jpg","content_type":"image/jpeg","size_bytes":1234567}}}},"responses":{"201":{"description":"Upload target","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Upload"}}}},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/uploads/{upload_id}/content":{"put":{"operationId":"uploadImageContent","summary":"Upload image bytes to a prepared upload target","parameters":[{"name":"upload_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Uploaded image content"},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/images/upscale":{"post":{"operationId":"createUpscaleJob","summary":"Create a single async image upscale job","parameters":[{"name":"wait","in":"query","required":false,"schema":{"type":"boolean"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUpscaleJobRequest"}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"scale":{"type":"integer","enum":[2,4,8]},"output_format":{"type":"string","enum":["png","jpg","webp"]}}}}}},"responses":{"202":{"description":"Queued job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpscaleJob"}}}},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/images/upscale/batch":{"post":{"operationId":"createUpscaleBatch","summary":"Create a batch of async image upscale jobs","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUpscaleBatchRequest"}}}},"responses":{"202":{"description":"Queued batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpscaleBatch"}}}},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jobs":{"get":{"operationId":"listJobs","summary":"List jobs","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Job list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedJobs"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jobs/{job_id}":{"get":{"operationId":"getJob","summary":"Get a job","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpscaleJob"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"deleteJob","summary":"Delete job assets","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Assets deleted"},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jobs/{job_id}/cancel":{"post":{"operationId":"cancelJob","summary":"Cancel a queued or processing job","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpscaleJob"}}}},"400":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/jobs/{job_id}/download":{"get":{"operationId":"downloadJobOutput","security":[],"summary":"Download a completed job output using its signed token","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Enhanced image bytes","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Output not found, expired, or token invalid"}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Get API usage","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummary"}}}},"401":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","security":[],"summary":"OpenAPI JSON","responses":{"200":{"description":"OpenAPI document"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"ApiAccount":{"type":"object","properties":{"object":{"const":"api_account"},"user_id":{"type":"string"},"key":{"$ref":"#/components/schemas/ApiKey"},"billing":{"$ref":"#/components/schemas/BillingStatus"}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"scopes":{"type":"array","items":{"type":"string"}}}},"BillingStatus":{"type":"object","properties":{"api_billing_enabled":{"type":"boolean"},"status":{"type":"string"}}},"CreateUploadRequest":{"type":"object","required":["filename","content_type","size_bytes"],"properties":{"filename":{"type":"string"},"content_type":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"size_bytes":{"type":"integer","maximum":10485760}}},"Upload":{"type":"object","properties":{"upload_id":{"type":"string"},"upload_url":{"type":"string"},"method":{"const":"PUT"},"headers":{"type":"object"},"expires_at":{"type":"string","format":"date-time"}}},"CreateUpscaleJobRequest":{"type":"object","properties":{"upload_id":{"type":"string"},"image_url":{"type":"string","format":"uri"},"scale":{"type":"integer","enum":[2,4,8],"default":2},"output_format":{"type":"string","enum":["png","jpg","webp"]},"enhance_detail":{"type":"boolean"},"reduce_noise":{"type":"boolean"},"metadata":{"type":"object"}}},"CreateUpscaleBatchRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","maxItems":15,"items":{"$ref":"#/components/schemas/CreateUpscaleJobRequest"}},"scale":{"type":"integer","enum":[2,4,8],"default":2},"output_format":{"type":"string","enum":["png","jpg","webp"]},"enhance_detail":{"type":"boolean"},"reduce_noise":{"type":"boolean"}}},"UpscaleJob":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"upscale_job"},"status":{"type":"string","enum":["queued","processing","succeeded","failed","cancelled"]},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"output":{"type":["object","null"]},"billing":{"type":"object"},"metadata":{"type":"object"}}},"UpscaleBatch":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"upscale_batch"},"status":{"type":"string"},"jobs":{"type":"array","items":{"type":"object"}}}},"UsageSummary":{"type":"object","properties":{"period":{"type":"object"},"totals":{"type":"object"},"by_day":{"type":"array","items":{"type":"object"}}}},"Pagination":{"type":"object","properties":{"object":{"const":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"PaginatedJobs":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UpscaleJob"}}}}]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"},"docs_url":{"type":"string"}}}}}}}}