Zamzar Files API

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