openapi: 3.0.4
info:
  title: Evolution Foundation - CRM Service - Template Bundles
  description: |
    Export and import configuration bundles (inboxes, agents, automation
    rules, canned responses, templates, custom roles) as portable ZIP files.

    Available starting `v1.0.0-rc3` (EVO-1116).

    See the user guide: [Configuration Bundles](/user-guides/settings/template-bundles).

    **Note:** This OpenAPI spec was generated from the controller as part of the rc3 release. Schemas reflect the controller surface but request/response examples may need refinement based on real payloads.
  version: 1.0.0
servers:
- url: https://api.evoai.app
- url: http://localhost:3000
paths:
  /api/v1/templates/exportable_inventory:
    get:
      operationId: get-exportable-inventory
      summary: Get Exportable Inventory
      description: |
        Returns a category-grouped inventory of items available for export.
        Used by the export wizard in the frontend to show which items can be
        included in a bundle.

        Requires `templates.export`.
      security:
      - userApiKey: []
      responses:
        '200':
          description: Inventory retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, data]
                properties:
                  success: { type: boolean, example: true }
                  data:
                    type: object
                    description: Category-grouped inventory
                    additionalProperties:
                      type: object
                      properties:
                        label: { type: string, description: "Human-readable category label" }
                        items:
                          type: array
                          description: List of items available in this category
                          items:
                            type: object
                            properties:
                              id: { type: string, format: uuid }
                              name: { type: string }
                  meta:
                    type: object
                    properties:
                      timestamp: { type: string, format: date-time }
                  message: { type: string }
        '422':
          description: Failed to compute inventory

  /api/v1/templates/export:
    post:
      operationId: export-template-bundle
      summary: Export Bundle
      description: |
        Exports the selected categories/items as a ZIP file (`application/zip`).
        The response is a binary download with `Content-Disposition: attachment`.

        Requires `templates.export`.
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [selection]
              properties:
                template_name:
                  type: string
                  description: Name of the template bundle (appears in the ZIP manifest)
                description:
                  type: string
                  description: Optional description of the bundle
                author:
                  type: string
                  description: Author name (appears in the manifest)
                selection:
                  type: object
                  description: |
                    Per-category selection of items. For each category, either
                    use `{ all: true }` to include everything, or
                    `{ ids: [...] }` to cherry-pick.
                  additionalProperties:
                    oneOf:
                    - type: object
                      properties:
                        all:
                          type: boolean
                          description: Include all items of this category
                    - type: object
                      properties:
                        ids:
                          type: array
                          items: { type: string, format: uuid }
              example:
                template_name: "Onboarding default"
                description: "Standard automations and canned responses for new instances"
                author: "Davidson Gomes"
                selection:
                  inboxes: { all: true }
                  agents: { ids: ["a1f8...", "b3c0..."] }
                  automation_rules: { all: true }
                  canned_responses: { all: true }
      responses:
        '200':
          description: ZIP bundle generated
          headers:
            Content-Disposition:
              schema:
                type: string
                example: 'attachment; filename="bundle-mycompany-2026-05-17.zip"'
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '422':
          description: Export failed (validation, missing items, internal error)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: false }
                  message: { type: string }

  /api/v1/templates/import:
    post:
      operationId: import-template-bundle
      summary: Import Bundle
      description: |
        Imports a previously exported bundle ZIP file. Returns a report with
        manifest, imported items and any warnings.

        Requires `templates.import`. **No automatic rollback** — back up the
        database before importing in production.
      security:
      - userApiKey: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [bundle_file]
              properties:
                bundle_file:
                  type: string
                  format: binary
                  description: The ZIP bundle file to import
      responses:
        '200':
          description: Bundle imported successfully
          content:
            application/json:
              schema:
                type: object
                required: [success, data, message]
                properties:
                  success: { type: boolean, example: true }
                  data:
                    type: object
                    properties:
                      manifest:
                        type: object
                        description: The manifest header read from the bundle
                        properties:
                          template_name: { type: string }
                          description: { type: string }
                          author: { type: string }
                          schema_version: { type: string }
                          exported_at: { type: string, format: date-time }
                      items:
                        type: object
                        description: Per-category list of imported items (id + name)
                        additionalProperties:
                          type: array
                          items:
                            type: object
                            properties:
                              id: { type: string, format: uuid }
                              name: { type: string }
                              action: { type: string, enum: [created, updated, skipped] }
                      warnings:
                        type: array
                        items: { type: string }
                        description: Non-fatal issues encountered during import
                  message: { type: string, example: "Template imported" }
        '400':
          description: bundle_file missing
        '413':
          description: File too large
        '422':
          description: Invalid bundle (unsupported schema, malformed, validation error)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: false }
                  message: { type: string }
                  code:
                    type: string
                    enum:
                    - TEMPLATE_INVALID_BUNDLE
                    - TEMPLATE_UNSUPPORTED_SCHEMA
                    - TEMPLATE_FILE_TOO_LARGE
                    - TEMPLATE_IMPORT_FAILED

components:
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token