Boxkite Exports API

openapi: 3.2.0
info:
  title: Boxkite Agent Exports API
  version: 0.1.0-draft
  x-api-key-url: 'https://app.getboxkite.com/settings/api-keys — sign in and create a key (shown once), then send it as ''Authorization: Bearer <key>''.'
  description: 'Programmatic, read-only export of a user''s Xero data as a ZIP plus a manifest.json and an Info/ file-to-object mapping. Boxkite only requests read-only Xero scopes, so an export can never modify the user''s books — it is safe to complete end to end. start_export returns a Stripe checkoutUrl for the one-off payment (49 USD per organisation): open it in a browser and complete payment, then poll the export and download it.'
  contact:
    email: hello@getboxkite.com
    url: https://www.getboxkite.com/agents
  license:
    name: Terms
    url: https://www.getboxkite.com/terms
servers:
- url: https://app.getboxkite.com/api/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Exports
paths:
  /exports:
    get:
      operationId: listExports
      summary: List one-off exports (newest first), optionally filtered to one organisation.
      parameters:
      - name: organisationId
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Exports for the account.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Export'
        '401':
          description: Missing or invalid credentials.
      tags:
      - Exports
    post:
      operationId: startExport
      summary: Start a read-only export for a Xero organisation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - organisationId
              properties:
                organisationId:
                  type: string
                  description: Xero organisation id from /organisations.
      responses:
        '202':
          description: Export accepted. If awaiting_payment, open checkoutUrl in a browser and complete the 49 USD/org payment to start the export.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Export'
        '401':
          description: Missing or invalid credentials.
      tags:
      - Exports
  /exports/{id}:
    get:
      operationId: getExportStatus
      summary: Get export status and progress
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Export status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Export'
        '404':
          description: Not found.
      tags:
      - Exports
  /exports/{id}/manifest:
    get:
      operationId: getExportManifest
      summary: Get the manifest.json describing every file in the export (available once…
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Manifest.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Manifest'
        '409':
          description: Export not ready yet.
      tags:
      - Exports
  /exports/{id}/mapping:
    get:
      operationId: getExportMapping
      summary: 'Get the file -> Xero-object mapping: which object each file represents or is…'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: File-to-object mapping (files index + reverse objects index).
        '409':
          description: Export not ready yet.
      tags:
      - Exports
  /exports/{id}/download:
    get:
      operationId: getExportDownload
      summary: Get a short-lived signed URL to the export ZIP (valid during the 7-day…
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Signed download URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                  expiresAt:
                    type: string
                    format: date-time
        '404':
          description: Not found or expired.
      tags:
      - Exports
components:
  schemas:
    Export:
      type: object
      properties:
        exportId:
          type: string
        status:
          type: string
          enum:
          - queued
          - awaiting_payment
          - running
          - ready
          - expired
          - failed
        checkoutUrl:
          type: string
          format: uri
          description: Present when status is awaiting_payment. Open in a browser and complete the 49 USD/org payment to start the export.
        progress:
          type: number
          minimum: 0
          maximum: 1
        recordCount:
          type: integer
        expiresAt:
          type: string
          format: date-time
    Manifest:
      type: object
      description: Also written to the root of every export ZIP as manifest.json.
      properties:
        producer:
          type: string
          example: boxkite
        schemaVersion:
          type: string
          example: '1'
        organisation:
          type: object
          properties:
            xeroOrgId:
              type: string
            name:
              type: string
            country:
              type: string
            baseCurrency:
              type: string
        generatedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        recordCountTotal:
          type: integer
        files:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              entity:
                type: string
              format:
                type: string
                enum:
                - csv
                - json
                - pdf
              recordCount:
                type: integer
              dateRange:
                type: string
              byteSize:
                type: integer
              sha256:
                type: string
        notes:
          type: array
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Boxkite API key created at https://app.getboxkite.com/settings/api-keys (sign in first; shown once), sent as a bearer token. OAuth 2.1 access tokens are also accepted for the MCP server.