{"openapi":"3.1.0","info":{"title":"101convert API","version":"1.0.0","description":"Convert files between formats from your own code. Every conversion is asynchronous: submit a file (or a URL), then poll its status, wait for it with ?wait=, or receive a webhook. Results stay downloadable for 24 hours.\n\nAuthenticate with an API key from your account page: `Authorization: Bearer <key>`.\n\nConversions cost credits from your plan (the same credits as on the website). A free account gets a monthly allowance of free API credits.","contact":{"url":"https:\/\/www.101convert.com\/contact"}},"servers":[{"url":"https:\/\/api.101convert.com\/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Conversions"},{"name":"Formats"},{"name":"Account"}],"paths":{"\/conversions":{"post":{"tags":["Conversions"],"summary":"Start a conversion","description":"Send exactly one input: a file (multipart) or a url. Conversion options can be sent flat (quality=85) or as options[quality]=85. Also available as POST \/convert.","operationId":"createConversion","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Retry safely: a repeated request with the same key returns the original conversion instead of starting (and paying for) a new one. Remembered for 24 hours.","schema":{"type":"string","maxLength":64}}],"requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"$ref":"#\/components\/schemas\/ConversionRequest"}},"application\/x-www-form-urlencoded":{"schema":{"$ref":"#\/components\/schemas\/ConversionRequest"}},"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ConversionRequest"}}}},"responses":{"200":{"description":"Finished within ?wait=","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Conversion"}}}},"202":{"description":"Accepted; poll the Location header","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Conversion"}}}},"401":{"$ref":"#\/components\/responses\/Error"},"402":{"$ref":"#\/components\/responses\/Error"},"409":{"$ref":"#\/components\/responses\/Error"},"413":{"$ref":"#\/components\/responses\/Error"},"422":{"$ref":"#\/components\/responses\/Error"},"429":{"$ref":"#\/components\/responses\/Error"}}},"get":{"tags":["Conversions"],"summary":"List your conversions","operationId":"listConversions","parameters":[{"name":"status","in":"query","schema":{"$ref":"#\/components\/schemas\/Status"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Newest first","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Conversion"}},"next_cursor":{"type":["string","null"]}}}}}}}}},"\/conversions\/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Conversions"],"summary":"Get a conversion","operationId":"getConversion","responses":{"200":{"description":"The conversion","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Conversion"}}}},"404":{"$ref":"#\/components\/responses\/Error"}}},"delete":{"tags":["Conversions"],"summary":"Cancel a queued conversion or delete a result","operationId":"deleteConversion","responses":{"200":{"description":"Cancelled or deleted","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Conversion"}}}},"409":{"$ref":"#\/components\/responses\/Error"}}}},"\/conversions\/{id}\/download":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Conversions"],"summary":"Download the result","description":"Can be downloaded repeatedly until result.expires_at.","operationId":"downloadConversion","responses":{"200":{"description":"The converted file","content":{"application\/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"409":{"$ref":"#\/components\/responses\/Error"},"410":{"$ref":"#\/components\/responses\/Error"}}}},"\/formats":{"get":{"tags":["Formats"],"summary":"All supported conversions","operationId":"listFormats","responses":{"200":{"description":"Source formats and their targets","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"targets":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"\/formats\/{source}":{"get":{"tags":["Formats"],"summary":"Targets, options, variants and limits for one source format","operationId":"getFormat","parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Details per target","content":{"application\/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"target":{"type":"string"},"max_upload_mb":{"type":"integer","description":"For your plan"},"credit_weight":{"type":"integer","description":"Credits per file up to 100 MB; larger files cost a multiple"},"options":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["range","number","enum","bool"]},"values":{"type":"array","items":{"type":"string"}},"min":{"type":"integer"},"max":{"type":"integer"},"default":[],"label":{"type":"string"}}}},"variants":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"}}}}}}}}}}}},"404":{"$ref":"#\/components\/responses\/Error"}}}},"\/account":{"get":{"tags":["Account"],"summary":"Plan, credits and limits of this key's account","operationId":"getAccount","responses":{"200":{"description":"The account","content":{"application\/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"credits":{"type":"object","properties":{"type":{"type":"string","enum":["plan_credits","free_api_credits","unmetered"]},"remaining":{"type":["integer","null"]},"monthly_allowance":{"type":"integer"},"resets_at":{"type":["string","null"],"format":"date-time"}}},"limits":{"type":"object","properties":{"max_upload_mb":{"type":"integer"},"conversions_per_window":{"type":"integer"},"window_seconds":{"type":"integer"},"concurrent_conversions":{"type":"integer"},"active_conversions":{"type":"integer"},"requests_per_minute":{"type":"integer"},"result_ttl_hours":{"type":"integer"}}}}}}}}}}}},"webhooks":{"conversionFinished":{"post":{"summary":"Sent to callback_url when a conversion succeeds or fails","description":"Verify the X-101convert-Signature header: t=<unix time>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with your webhook secret>. Retried with backoff until your endpoint answers 2xx.","parameters":[{"name":"X-101convert-Event","in":"header","schema":{"type":"string","enum":["conversion.succeeded","conversion.failed"]}},{"name":"X-101convert-Delivery","in":"header","schema":{"type":"string","format":"uuid"}},{"name":"X-101convert-Signature","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application\/json":{"schema":{"type":"object","properties":{"event":{"type":"string"},"data":{"$ref":"#\/components\/schemas\/Conversion"}}}}}},"responses":{"2XX":{"description":"Delivered"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from your account page"}},"responses":{"Error":{"description":"Error","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"On 429: seconds to wait"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}},"schemas":{"Status":{"type":"string","enum":["queued","fetching","processing","succeeded","failed","cancelled","expired"]},"ConversionRequest":{"type":"object","required":["target"],"properties":{"file":{"type":"string","format":"binary","description":"The file to convert (multipart only)"},"url":{"type":"string","format":"uri","description":"Or: a public URL to download the file from"},"target":{"type":"string","example":"webp"},"source":{"type":"string","description":"Source format, when the file name or URL does not say it","example":"jpg"},"filename":{"type":"string","description":"Name for a URL input"},"variant":{"type":"string","description":"Mode, for conversions that have several (see GET \/formats\/{source})"},"options":{"type":"object","additionalProperties":true,"example":{"quality":85}},"callback_url":{"type":"string","format":"uri","description":"https URL to receive a webhook when finished"},"wait":{"type":"integer","minimum":0,"maximum":30,"description":"Seconds to wait for the result before answering"}}},"Conversion":{"type":"object","properties":{"id":{"type":"string","example":"cnv_01j9z3k8q4x7m2n5p6r8s9t0v1"},"object":{"type":"string","const":"conversion"},"status":{"$ref":"#\/components\/schemas\/Status"},"source":{"type":"string"},"target":{"type":"string"},"variant":{"type":["string","null"]},"options":{"type":"object"},"original_name":{"type":"string"},"input_size":{"type":["integer","null"]},"progress":{"type":["integer","null"],"minimum":0,"maximum":100},"credits":{"type":"integer","description":"Credits this conversion cost (0 if it failed)"},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"filename":{"type":"string"},"size":{"type":"integer"},"mime":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"download_url":{"type":"string","format":"uri"}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"download":{"type":"string","format":"uri"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code","examples":["unauthenticated","forbidden","validation_failed","unsupported_conversion","file_too_large","insufficient_credits","free_quota_exhausted","rate_limited","concurrency_limit","idempotency_conflict","not_ready","expired","api_disabled"]},"message":{"type":"string","description":"Human-readable, in the language of Accept-Language"},"details":{"type":"object"}}}}}}}}