openapi: 3.1.0
info:
  title: Zylo Enterprise Applications Export Jobs API
  description: The Zylo Enterprise API provides a modern, RESTful API to work with your SaaS subscription data. The API is built using resource-oriented URLs that are protected by HTTPS transport security and authenticated via secure tokens. It enables the export of SaaS usage and subscription data to reporting tools outside of Zylo, as well as the import of additional unintegrated usage data.
  version: 1.0.0
  contact:
    name: Zylo
    url: https://zylo.com/contact/
  license:
    name: Proprietary
    url: https://zylo.com/msa/
  termsOfService: https://zylo.com/msa/
servers:
- url: https://api.zylo.com/v1
  description: Zylo Enterprise API v1
security:
- bearerAuth: []
tags:
- name: Export Jobs
  description: Export Jobs allow you to export subscription data asynchronously. You first create an export job, then retrieve the results when the job is complete.
paths:
  /subscriptions/-/exportJobs:
    post:
      operationId: createExportJob
      summary: Zylo Create an export job
      description: Creates an asynchronous export job for subscription data. Due to the size of the data, subscription exports use an asynchronous workflow where you first create the export job and then retrieve the results when the job is complete.
      tags:
      - Export Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportJobRequest'
      responses:
        '201':
          description: The export job has been created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJob'
        '401':
          description: Unauthorized. Invalid or missing authentication token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /subscriptions/-/exportJobs/{exportJobId}:
    get:
      operationId: getExportJob
      summary: Zylo Get an export job
      description: Retrieves the status and results of a previously created export job. When the job is complete, the response includes a URL to download the exported data.
      tags:
      - Export Jobs
      parameters:
      - name: exportJobId
        in: path
        required: true
        description: The unique identifier of the export job.
        schema:
          type: string
      responses:
        '200':
          description: The export job details and status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportJob'
        '401':
          description: Unauthorized. Invalid or missing authentication token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Export job not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ExportJob:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the export job.
        status:
          type: string
          description: The current status of the export job.
          enum:
          - pending
          - processing
          - completed
          - failed
        downloadUrl:
          type: string
          format: uri
          description: The URL to download the exported data. Only available when the job status is completed.
        createdAt:
          type: string
          format: date-time
          description: The date and time the export job was created.
        completedAt:
          type: string
          format: date-time
          description: The date and time the export job completed.
        error:
          type: string
          description: Error message if the job failed.
    Error:
      type: object
      properties:
        code:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: A human-readable error message.
        details:
          type: string
          description: Additional details about the error.
    ExportJobRequest:
      type: object
      properties:
        subscriptionIds:
          type: array
          items:
            type: string
          description: An optional list of subscription IDs to include in the export. If not specified, all subscriptions will be exported.
        format:
          type: string
          description: The format of the exported data.
          enum:
          - csv
          - json
          default: csv
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your Token ID and Token Secret separated by a colon (TOKENID:TOKENSECRET). Tokens can be created in the Zylo Admin panel under Company Tokens.