Zamzar Imports API

openapi: 3.0.3
info:
  title: Zamzar Account Imports 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: Imports
  description: Import files from an external URL, (S)FTP server or Amazon S3 bucket
paths:
  /imports:
    get:
      tags:
      - Imports
      summary: Retrieve a list of all imports
      description: Retrieve a list of all imports
      operationId: listImports
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          type: integer
        description: Limit the number of results (max 50)
      - in: query
        name: after
        required: false
        schema:
          type: integer
        description: Retrieve imports after the specified importId
      - in: query
        name: before
        required: false
        schema:
          type: integer
        description: Retrieve imports before the specified importId
      responses:
        '200':
          description: A list of all imports
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Imports'
        '504':
          description: Gateway Timeout
    post:
      tags:
      - Imports
      summary: Start an Import
      description: Start an Import
      operationId: startImport
      requestBody:
        description: Start an import for a HTTP/HTTPS url, (S)FTP file or S3 bucket
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - url
              properties:
                url:
                  type: string
                  description: Provide a url in the form HTTP(S), (S)FTP or S3
                filename:
                  type: string
                  description: Override the filename provided in the url
      responses:
        '201':
          description: Import submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
  /imports/{importId}:
    get:
      tags:
      - Imports
      summary: Retrieve a specific import
      description: Retriefe a specific import
      operationId: getImportById
      parameters:
      - in: path
        name: importId
        schema:
          type: integer
        required: true
        description: Numeric id of the import to get
      responses:
        '200':
          description: Information about a specific import
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Import'
components:
  schemas:
    Imports:
      type: object
      description: Contains a paged collection of import objects. Newer imports appear before older imports.
      properties:
        paging:
          $ref: '#/components/schemas/PagingNumeric'
        data:
          type: array
          description: An array of import objects
          items:
            $ref: '#/components/schemas/Import'
    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
    Import:
      type: object
      description: Represents the process of copying a file from an external URL, (S)FTP server, or an Amazon S3 bucket.
      required:
      - id
      properties:
        id:
          type: integer
          description: The unique identifier assigned to the import
          format: int32
        key:
          type: string
          description: The API key used to create the import.
        url:
          type: string
          description: The URL to the file being imported.
        status:
          type: string
          description: The current status of the import
          enum:
          - initialising
          - downloading
          - successful
          - failed
          example: failed
        failure:
          $ref: '#/components/schemas/Failure'
        file:
          $ref: '#/components/schemas/File'
        created_at:
          type: string
          description: The time at which the import was created on Zamzar servers ((UTC in [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)))
          format: date-time
        finished_at:
          type: string
          description: The time at which the import finished if successful, or null otherwise ((UTC in [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)))
          format: date-time
          nullable: true
      example:
        id: 1
        key: apikey
        url: http://www.example.com/logo.png
        status: failed
        failure:
          code: 11
          message: an invalid value was specified for a parameter
          context:
            parameter: url
            reason: http URLs must not include a password (use https instead)
        created_at: '2022-01-01T14:15:22Z'
        finished_at: '2022-01-01T14:15:22Z'
    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'
    Failure:
      type: object
      description: If a process fails, the response will include a failure object to describe the error. If a process is either incomplete or successful, the failure object will not be present.
      properties:
        code:
          type: integer
          description: Can be used to determine what action to take
          format: int32
        message:
          type: string
          description: Provides an explanation of the failure (which could also be displayed to your users)
      example:
        code: 5
        message: A file named portrait.png already exists
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Find out more about the Zamzar API
  url: https://developers.zamzar.com/docs