{
  "openapi": "3.0.3",
  "info": {
    "title": "Integrations API",
    "version": "latest",
    "description": "Integration record, setup verification, stats, and sync job API contract."
  },
  "paths": {
    "/v1/apps/{app_id}/integrations": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "List integrations",
        "description": "Retrieves all integrations associated with an app",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by integration type (brink, storyblok, webhooks, voyado, google-retailer, klaviyo, nosto, centra, shopify, ai)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of integrations (without settings details)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/IntegrationResponse"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (e.g. bad UUID)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Integrations"
        ],
        "summary": "Create integration",
        "description": "Creates a new integration for an app with specified type and configuration",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Integration created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/IntegrationResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (e.g. bad UUID, validation error, invalid config)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "App not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "description": "Integration data",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InputCreateIntegration"
              }
            }
          }
        }
      }
    },
    "/v1/apps/{app_id}/integrations/{integration_id}": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "Get integration",
        "description": "Retrieves detailed information about a specific integration including masked settings",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration_id",
            "in": "path",
            "required": true,
            "description": "Integration UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Integration details with masked secret values",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/IntegrationResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (e.g. bad UUID)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Integration not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Integrations"
        ],
        "summary": "Delete integration",
        "description": "Deletes an integration and all its configuration",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration_id",
            "in": "path",
            "required": true,
            "description": "Integration UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Integration deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (e.g. bad UUID)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Integration not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Integrations"
        ],
        "summary": "Update integration",
        "description": "Updates an integration's title, description, active status, and/or configuration. Config changes are merged with existing values.",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration_id",
            "in": "path",
            "required": true,
            "description": "Integration UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Integration updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/IntegrationResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (e.g. bad UUID, validation error, invalid config)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Integration or app not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "description": "Integration update data",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InputUpdateIntegration"
              }
            }
          }
        }
      }
    },
    "/v1/apps/{app_id}/integrations/{integration_id}/stats": {
      "get": {
        "tags": [
          "Stats"
        ],
        "summary": "Get integration stats",
        "description": "Retrieves job statistics for a specific integration including processing, pending, failed, completed today, and to-be-retried counts",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration_id",
            "in": "path",
            "required": true,
            "description": "Integration UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Integration job statistics",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/JobStatsResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Integration not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/apps/{app_id}/integrations/{integration_id}/sync": {
      "post": {
        "tags": [
          "Sync"
        ],
        "summary": "Create sync job",
        "description": "Creates a new sync job for an integration with specified configuration",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration_id",
            "in": "path",
            "required": true,
            "description": "Integration UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sync job created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SyncCreatedResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Integration not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "description": "Sync configuration",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SyncConfig"
              }
            }
          }
        }
      }
    },
    "/v1/apps/{app_id}/integrations/{integration_id}/sync/{sync_id}": {
      "get": {
        "tags": [
          "Sync"
        ],
        "summary": "Get sync job status",
        "description": "Retrieves the current status and progress of a sync job",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration_id",
            "in": "path",
            "required": true,
            "description": "Integration UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sync_id",
            "in": "path",
            "required": true,
            "description": "Sync UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sync job status",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/SyncStatusResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sync"
        ],
        "summary": "Stop sync job",
        "description": "Stops a running sync job and cancels pending tasks",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration_id",
            "in": "path",
            "required": true,
            "description": "Integration UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sync_id",
            "in": "path",
            "required": true,
            "description": "Sync UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sync job stopped",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/StopSyncResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/apps/{app_id}/integrations/{integration_id}/verify": {
      "post": {
        "tags": [
          "Integrations"
        ],
        "summary": "Verify integration setup",
        "description": "Verifies that an integration is properly configured by testing API credentials and connectivity",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "integration_id",
            "in": "path",
            "required": true,
            "description": "Integration UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification result",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/VerificationResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request (e.g. bad UUID)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Integration not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/apps/{app_id}/stats": {
      "get": {
        "tags": [
          "Stats"
        ],
        "summary": "Get app stats",
        "description": "Retrieves job statistics for an app aggregated across all integrations including processing, pending, failed, completed today, and to-be-retried counts",
        "parameters": [
          {
            "name": "app_id",
            "in": "path",
            "required": true,
            "description": "App UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "App job statistics",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/JobStatsResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "App not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VerificationStep": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "success": {
            "type": "boolean"
          }
        }
      },
      "SyncConfig": {
        "type": "object",
        "properties": {
          "full_sync": {
            "type": "boolean"
          },
          "item_types": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SyncConfigTypes"
            }
          }
        }
      },
      "SyncConfigTypes": {
        "type": "object",
        "properties": {
          "item_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "type": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "details": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "success": {
            "type": "boolean"
          }
        }
      },
      "InputCreateIntegration": {
        "type": "object",
        "required": [
          "config",
          "title",
          "type"
        ],
        "properties": {
          "active": {
            "type": "boolean"
          },
          "channel_id": {
            "type": "string"
          },
          "config": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "custom_fields": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        }
      },
      "InputUpdateIntegration": {
        "type": "object",
        "required": [
          "config"
        ],
        "properties": {
          "active": {
            "type": "boolean"
          },
          "channel_id": {
            "type": "string"
          },
          "clear_channel_id": {
            "type": "boolean"
          },
          "config": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "custom_fields": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        }
      },
      "IntegrationResponse": {
        "type": "object",
        "properties": {
          "active": {
            "type": "boolean"
          },
          "app_id": {
            "type": "string"
          },
          "channel_id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "custom_fields": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "settings": {
            "type": "object",
            "additionalProperties": {}
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        }
      },
      "JobStatsResponse": {
        "type": "object",
        "properties": {
          "completed_today": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "pending_retrying": {
            "type": "integer"
          },
          "processing": {
            "type": "integer"
          },
          "to_be_retried": {
            "type": "integer"
          }
        }
      },
      "RemainingsJobs": {
        "type": "object",
        "properties": {
          "completed": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "processing": {
            "type": "integer"
          }
        }
      },
      "StopSyncResponse": {
        "type": "object",
        "properties": {
          "jobs_cancelled": {
            "type": "integer"
          },
          "remaining_jobs": {
            "$ref": "#/components/schemas/RemainingsJobs"
          },
          "sync_id": {
            "type": "string"
          }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "data": {},
          "success": {
            "type": "boolean"
          }
        }
      },
      "SyncCreatedResponse": {
        "type": "object",
        "properties": {
          "breakdown": {
            "type": "object",
            "additionalProperties": {
              "type": "integer"
            }
          },
          "jobs_created": {
            "type": "integer"
          },
          "sync_id": {
            "type": "string"
          }
        }
      },
      "SyncStatusResponse": {
        "type": "object",
        "properties": {
          "completed": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "pending": {
            "type": "integer"
          },
          "percentage_complete": {
            "type": "number"
          },
          "processing": {
            "type": "integer"
          },
          "sync_id": {
            "type": "string"
          },
          "to_be_retried": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "VerificationResponse": {
        "type": "object",
        "properties": {
          "overall_success": {
            "type": "boolean"
          },
          "steps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VerificationStep"
            }
          }
        }
      }
    }
  }
}