openapi: 3.1.0
info:
  title: LayerBack Conversion API
  version: "1.0"
  description: |
    Convert diagram images (PNG, JPEG, WebP) into fully editable
    Visio (VSDX), PowerPoint (PPTX), draw.io, and SVG files.
    Every shape, connector, and label is rebuilt as a native object —
    not an image embedded in a file container.

    Get an API key at https://layerback.com/settings/apikeys.
    One conversion costs 10 credits and includes all output formats.
  contact:
    url: https://layerback.com/docs/api
servers:
  - url: https://layerback.com/api/v1
security:
  - apiKey: []
paths:
  /convert:
    post:
      summary: Start a conversion
      description: |
        Send raw image bytes as the request body. Poll the job endpoint,
        or pass `callback_url` to receive a completion webhook.
      operationId: startConversion
      parameters:
        - name: callback_url
          in: query
          required: false
          description: |
            Public https URL that receives a POST when the job finishes
            (both success and failure):
            `{"job_id", "status", "total_seconds", "error", "formats"}`.
          schema:
            type: string
            format: uri
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "202":
          description: Conversion started
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id: { type: string, format: uuid }
        "400": { description: Empty body or invalid callback_url }
        "401": { description: Invalid API key }
        "402": { description: Insufficient credits }
        "413": { description: Image exceeds 20 MB }
        "415": { description: Body is not PNG, JPEG, or WebP }
        "429": { description: Rate limit exceeded }
        "503": { description: Conversion service unavailable (credits refunded) }
  /jobs/{jobId}:
    get:
      summary: Get job status
      operationId: getJob
      parameters:
        - name: jobId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200":
          description: Current job state
          content:
            application/json:
              schema:
                type: object
                properties:
                  job_id: { type: string, format: uuid }
                  status:
                    type: string
                    enum: [queued, running, succeeded, failed]
                  total_seconds: { type: number }
                  formats:
                    type: array
                    items: { type: string }
                    description: Available once succeeded (vsdx, pptx, drawio, svg, ir, preview)
        "401": { description: Invalid API key }
        "404": { description: Unknown job }
  /jobs/{jobId}/download:
    get:
      summary: Download an artifact
      description: |
        Responds with a 302 redirect to a short-lived download URL —
        follow redirects (`curl -L`). Downloads are free and repeatable.
      operationId: downloadArtifact
      parameters:
        - name: jobId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [vsdx, pptx, drawio, svg, ir, preview]
            default: vsdx
      responses:
        "302": { description: Redirect to the artifact }
        "200":
          description: Artifact bytes (fallback path)
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        "401": { description: Invalid API key }
        "404": { description: Unknown job or artifact not ready }
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key