OpenAPI Specification
openapi: 3.0.3
info:
title: Zamzar Account Files API
description: Zamzar provides a simple API for fast, scalable, high-quality file conversion for 100s of formats.
termsOfService: http://developers.zamzar.com
contact:
email: api-sdks@zamzar.com
license:
name: MIT
url: https://opensource.org/licenses/MIT
version: 0.0.7
servers:
- url: https://api.zamzar.com/v1
description: Production Server
- url: https://sandbox.zamzar.com/v1
description: Test Server
security:
- ApiKeyAuth: []
tags:
- name: Files
description: Create, retrieve or delete files
paths:
/files:
get:
tags:
- Files
summary: Retrieve a list of files
operationId: listFiles
parameters:
- in: query
name: limit
schema:
type: integer
example: 10
description: Limit the number of results (max 50)
- in: query
name: after
required: false
schema:
type: integer
example: 123456
description: Retrieve files after the specified fileId
- in: query
name: before
required: false
schema:
type: integer
example: 123456
description: Retrieve files before the specified fileId
responses:
'200':
description: A list of source and associated target (converted) files within the `data` array.
content:
application/json:
schema:
$ref: '#/components/schemas/Files'
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
Zamzar-Credits-Remaining:
$ref: '#/components/headers/Zamzar-Credits-Remaining'
Zamzar-Test-Credits-Remaining:
$ref: '#/components/headers/Zamzar-Test-Credits-Remaining'
description: Retrieve a list of files which have been uploaded, imported or submitted for conversion. Files are ordered by the most recent first. Expired files are not included.
post:
tags:
- Files
summary: Upload a file
operationId: uploadFile
requestBody:
description: ''
required: true
content:
multipart/form-data:
schema:
type: object
properties:
content:
type: string
description: Provide the file to be uploaded
format: binary
name:
type: string
description: Specify the name of the file
responses:
'201':
description: File uploaded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/File'
description: Upload a local file which can be used as input to a conversion job. Ensure the file is a [format supported by the API](https://developers.zamzar.com/formats) and does not exceed the maximum size of [your plan](https://developers.zamzar.com/user).
/files/{fileId}:
get:
tags:
- Files
summary: Retrieve metadata for a specific file
operationId: getFileById
parameters:
- in: path
name: fileId
schema:
type: integer
required: true
description: Numeric id of the file to get
example: 123456
responses:
'200':
description: Metadata for a specific file
content:
application/json:
schema:
$ref: '#/components/schemas/File'
'404':
description: Resource is not available because it has been deleted
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'410':
description: Resource has expired
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
description: Retrieve the metadata for a file which has been uploaded, imported or converted.
delete:
tags:
- Files
summary: Delete a file
operationId: deleteFileById
parameters:
- in: path
name: fileId
schema:
type: integer
required: true
description: Numeric id of the file to delete
example: 123456
responses:
'200':
description: File deleted successfully. The response will contain the metadata for the deleted file (but not the content).
content:
application/json:
schema:
$ref: '#/components/schemas/File'
description: Delete our copy of a file which has been uploaded, imported or converted.
/files/{fileId}/content:
get:
tags:
- Files
summary: Retrieve the content of a file
operationId: getFileContentById
parameters:
- in: path
name: fileId
schema:
type: integer
required: true
description: Numeric id of the file to get the content for
example: 123456
responses:
'200':
description: OK
content:
application/octet-stream:
schema:
type: string
format: binary
headers:
Content-Disposition:
schema:
type: string
description: eg
example: attachment; filename="name.pdf"
x-is-file: true
'201':
description: "The body of the response will contain the contents of a file in which case you can download the file data directly:\n\n```\nHTTP/1.1 200 OK\nContent-Length: 15311\nContent-Disposition: attachment; filename=\"portrait.png\"\nZamzar-Test-Credits-Remaining: 97\nZamzar-Credits-Remaining: 343\nContent-Type: image/png; charset=binary\n\n[Binary content of portrait.png]\n```\n\n### When using cURL\n\nSave the content of a file to disk using curl options `-L` (follow redirects), `-O` (Write output to a local file) and `-J` (use the server-specified Content-Disposition filename). Or specify your own filename by redirecting the output of your HTTP call:\n\n```shell\ncurl --request GET \\\n --url https://api.zamzar.com/v1/files/123456/content \\\n --header 'Authorization: Basic xxxxxx' \\\n --header 'Content-Type: application/json' -L \\\n -L\n -O \\\n -J\n > converted.png\n```"
headers:
header-0:
schema:
type: string
'307':
description: "Instruct your client code to follow the redirect link specified in the `Location` header of the response in order to download the file:\n\n```\nHTTP/1.1 307 Temporary Redirect\nContent-Length: 0\nLocation: https://someotherlocation.com/file\nZamzar-Test-Credits-Remaining: 97\nZamzar-Credits-Remaining: 343\nContent-Type: application/json; charset=utf-8\n```\n\n### When using cUrl\n\nSave the content of a file to disk using curl options `-L` (follow redirects), `-O` (Write output to a local file) and `-J` (use the server-specified Content-Disposition filename). Or specify your own filename by redirecting the output of your HTTP call:\n\n```shell\ncurl --request GET \\\n --url https://api.zamzar.com/v1/files/123456/content \\\n --header 'Authorization: Basic xxxxxx' \\\n --header 'Content-Type: application/json' -L \\\n -L\n -O \\\n -J\n > converted.png\n```"
description: Retrieve the contents of a file which has been converted using the `/jobs` endpoint. The content of files which have been uploaded or converted can also be retrieved.
x-is-file: true
components:
schemas:
Errors:
type: object
description: When a response contains a `4xx` or `5xx` response code, the body of the request will contain one or more error objects. Problems
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
PagingNumeric:
type: object
properties:
total_count:
type: integer
description: The number of elements in the entire collection
format: int32
first:
type: integer
description: The identifier of the first element in this page of the collection
format: int32
last:
type: integer
description: The identifier of the last element in this page of the collection
format: int32
limit:
type: integer
description: The maximum number of elements this page could contain
format: int32
Error:
type: object
description: An error object containing a message, code and context. Returned within an array of `errors` when a response contains a `4xx` or `5xx` code.
properties:
code:
type: integer
description: The unique identifier for the type of error. `1x` relates to problems with the content of the request. `2x` relates to the nature of the request. `3x` relates to problems with the service.
format: int32
example: 22
message:
type: string
description: The description of the error
example: unrecognised API version
context:
type: object
description: Further information about the cause of the error (only included for some error codes)
properties:
description:
type: string
value:
type: string
example:
requested_version: v42
supported_versions: v1
example:
message: an invalid value was specified for a parameter
code: 10
context:
parameter: target_format
reason: applescript is not a supported format
Files:
type: object
description: Contains a paged collection of files. Newer files appear before older files. Expired files are not included.
properties:
data:
type: array
description: An array of file objects
items:
$ref: '#/components/schemas/File'
paging:
$ref: '#/components/schemas/PagingNumeric'
File:
type: object
description: Represents a file which has been uploaded, imported or converted.
required:
- id
- name
properties:
id:
type: integer
description: The unique identifier assigned to the file
format: int32
key:
type: string
description: The API key which was used to create the file
name:
type: string
description: The name that was specified for the file (must not be more than 256 chars)
size:
type: integer
format: int64
description: The size of the file in bytes, derived from the content of the file
format:
type: string
description: The identifier of the format of the file
created_at:
type: string
description: The time at which the file was created on Zamzar servers ((UTC in [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)))
format: date-time
example:
id: 3
key: apikey
name: filename.jpg
size: 4096
format: jpg
created_at: '2022-01-01T14:15:22Z'
headers:
X-RateLimit-Remaining:
description: The number of remaining requests in the current period
schema:
type: integer
example: 597
Zamzar-Test-Credits-Remaining:
description: The number of test credits remaining in the current billing period
schema:
type: integer
example: 90
Zamzar-Credits-Remaining:
description: The number of production credits remaining in the current billing period
schema:
type: integer
example: 100
X-RateLimit-Limit:
description: The number of allowed requests in the current period
schema:
type: integer
example: 600
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
externalDocs:
description: Find out more about the Zamzar API
url: https://developers.zamzar.com/docs