openapi: 3.0.4
info:
  title: Fax API
  description: |-
    Welcome to the Voxtelesys Fax REST API. This API offers an easy, secure solution to send and receive faxes. If you have questions or would like more information, please reach out to support.
  version: v1
servers:
  - url: https://faxapi.voxtelesys.net/api/v1
paths:
  /faxes/{id}:
    get:
      tags:
        - Faxes
      security:
        - OAuth2: ['faxapi:faxes:view']
      summary: Retrieve a fax
      description: Endpoint for retreiving an inbound or outbound fax.
      parameters:
        - name: id
          in: path
          description: ID of fax
          example: fc90ecf7-ada9-4843-9bd2-3cd9ddfa33b7
          required: true
          schema:
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/responseSchemas/GetFax"
        "500":
          description: internal error
          content:
            application/json:
              schema:
                $ref: "#/components/responseSchemas/GetFaxError"
  /faxes:
    get:
      tags:
        - Faxes
      security:
        - OAuth2: ['faxapi:faxes:view']
      summary: List faxes
      description: Endpoint for retrieving a list of inbound and outbound faxes. To fetch all available faxes, the `next_page` parameter is available as a cursor to iterate over. The iteration process works by taking the `next_page` field in the response from the `/faxes` route and then providing the `next_page` parameter in the subsequent request to `/faxes`.
      parameters:
        - name: page_size
          in: query
          description: number of faxes to retrieve per page
          example: 50
          schema:
            type: integer
        - name: next_page
          in: query
          description: unique identifier to fetch the next page. Required for pagination
          example: 7d10a422-bd7d-4034-83de-c70caac600ba
          schema:
            type: string
            default: null
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/responseSchemas/GetFaxes"
    post:
      tags:
        - Faxes
      security:
        - OAuth2: ['faxapi:faxes:manage']
      summary: Send a fax
      description: Endpoint for creating a new outbound fax.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendFax"
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/responseSchemas/SendFax"
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://authapi.voxtelesys.net/api/v1/oauth/token
          scopes:
            faxapi:faxes:manage: Ability to send inbound/outbound faxes
            faxapi:faxes:view: Ability to view inbound/outbound faxes
  schemas:
    Fax:
      type: object
      properties:
          id:
            type: string
            example: fc90ecf7-ada9-4843-9bd2-3cd9ddfa33b7
            readOnly: true
          created_at:
            type: string
            format: date-time
            example: "2024-01-01T16:51:16.979Z"
            readOnly: true
          modified_at:
            type: string
            format: date-time
            example: "2024-01-01T16:51:16.979Z"
            readOnly: true
          direction:
            type: string
            enum: [inbound, outbound]
            example: "outbound"
            readOnly: true
          to:
            type: string
            description: The number to dial in E.164 format.
            example: "+15556667777"
          from:
            type: string
            description: The number to originate the call from in E.164 format.
            example: "+15556668888"
          status:
            type: string
            description: The status of the fax.
            readOnly: true
            example: "delivered"
          url:
            type: string
            format: uri
            description: The URL to download the file to fax. Must be a `JPEG`, `PDF`, `PNG`, or `TIFF`.
            example: "https://example.com/file.pdf"
          pages:
            type: integer
            description: The number of pages in the fax.
            readOnly: true
            example: 1
          duration:
            type: integer
            description: The duration of the fax in seconds.
            readOnly: true
            example: 10
          attempts:
            type: integer
            description: The number of attempts to make when sending the fax. Defaults to 3.
            example: 3
          error:
            type: object
            readOnly: true
            properties:
              code:
                type: integer
                description: The error code.
                example: 5312
              description:
                type: string
                description: The error description.
                example: "internal error"
    SendFax:
      allOf:
        - $ref: "#/components/schemas/Fax"
        - required:
          - to
          - from
          - url
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              example: 5312
            description:
              type: string
              example: internal error
  responseSchemas:
    GetFax:
      $ref: "#/components/schemas/Fax"
    GetFaxError:
      allOf:
        - $ref: "#/components/schemas/Fax"
        - $ref: "#/components/schemas/Error"
    GetFaxes:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/Fax"
        page_size:
          type: integer
          example: 50
        next_page:
          type: string
          example: "K0NFRUBbQV00YjkxYmRkMWU0ZjlhY2Q4ZDUiXQ=="
    SendFax:
      $ref: "#/components/schemas/Fax"
