External Integrations Endpoints

External Integrations API endpoints.

---

Overview

Method	Endpoint	Description
GET	/api/v1/external-integrations/	Read Integrations
GET	/api/v1/external-integrations/ovs	Read Ovs Integrations
POST	/api/v1/external-integrations/ovs	Create Ovs Integration
PUT	/api/v1/external-integrations/ovs/{integration_id}	Update Ovs Integration
POST	/api/v1/external-integrations/ovs/{integration_id}/sync	Trigger Ovs Sync
GET	/api/v1/external-integrations/ovs/{integration_id}/sync/status	Get Ovs Sync Status
GET	/api/v1/external-integrations/{integration_id}	Read Integration
DELETE	/api/v1/external-integrations/{integration_id}	Delete Integration

---

API Reference

Sartiq Backend Server - External Integrations 0.1.0

external-integrations

---

GET /api/v1/external-integrations/

Read Integrations

Description

Retrieve external integrations.

• Regular users see only their own integrations or organization integrations
• Superusers see all integrations

When organization_id query param is provided, returns integrations belonging to that organization. Without organization_id, returns only personal integrations (not belonging to any organization).

Optional filters: - integration_type: Filter by specific integration type (e.g., 'ovs')

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
integration_type	query			No	Filter by integration type
limit	query	integer	100	No
organization_id	query			No
skip	query	integer	0	No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "id": "b42030e0-3e09-4e59-89e6-5f6f12d48b44",
    "created_at": "2022-04-13T15:42:05.901Z",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "data": [
        {
            "id": "2fadade2-da14-43e3-844b-8cc6d2623410",
            "created_at": "2022-04-13T15:42:05.901Z",
            "updated_at": "2022-04-13T15:42:05.901Z",
            "name": "string",
            "integration_type": "string",
            "user_id": "3c624b54-7b98-4353-a607-7a4bb0d0c585",
            "organization_id": null
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "data": {
            "items": {
                "$ref": "#/components/schemas/ExternalSystemIntegrationPublic"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "ExternalSystemIntegrationsPublic",
    "description": "Schema for paginated list of external integrations."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/external-integrations/ovs

Read Ovs Integrations

Description

Retrieve OVS integrations with full OVS-specific fields.

• Regular users see only their own integrations or organization integrations
• Superusers see all integrations

When organization_id query param is provided, returns integrations belonging to that organization. Without organization_id, returns only personal integrations.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
limit	query	integer	100	No
organization_id	query			No
skip	query	integer	0	No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "id": "5a2eea97-bf4f-4ec5-96f7-3f5acc10226c",
    "created_at": "2022-04-13T15:42:05.901Z",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "data": [
        {
            "base_url": "https://ovs.example.com/api",
            "created_at": "2025-01-01T00:00:00Z",
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "integration_type": "ovs",
            "name": "Production OVS",
            "push_products": true,
            "push_service_base_url": "https://upload.example.com/stage",
            "updated_at": "2025-01-01T00:00:00Z",
            "user_id": "123e4567-e89b-12d3-a456-426614174001",
            "username": "api_user"
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "data": {
            "items": {
                "$ref": "#/components/schemas/OVSIntegrationPublic"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "OVSIntegrationsPublic",
    "description": "Schema for paginated list of OVS integrations with full OVS fields."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/external-integrations/ovs

Create Ovs Integration

Description

Create a new OVS (Order and Warehouse System) integration.

Regular users: Integration is created for themselves Superusers: Can optionally specify user_id to create for another user

When organization_id query param is provided, creates the integration for that organization.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
organization_id	query			No

Request body

application/json

{
    "base_url": "https://ovs.example.com/api",
    "name": "Production OVS",
    "password": "secure_password",
    "push_products": false,
    "push_service_api_key": "your-api-key",
    "push_service_base_url": "https://upload.example.com/stage",
    "username": "api_user"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "name": {
            "type": "string",
            "maxLength": 255,
            "title": "Name",
            "description": "User-friendly name for this integration"
        },
        "base_url": {
            "type": "string",
            "maxLength": 255,
            "title": "Base Url",
            "description": "Base URL of the OVS API endpoint"
        },
        "username": {
            "type": "string",
            "maxLength": 255,
            "title": "Username",
            "description": "Username for OVS authentication"
        },
        "password": {
            "type": "string",
            "maxLength": 255,
            "title": "Password",
            "description": "Password for OVS authentication"
        },
        "user_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "User Id",
            "description": "User ID to create integration for (superusers only). If not provided, creates for current user."
        },
        "push_service_base_url": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 500
                },
                {
                    "type": "null"
                }
            ],
            "title": "Push Service Base Url",
            "description": "Base URL of the push service API for image uploads"
        },
        "push_service_api_key": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 500
                },
                {
                    "type": "null"
                }
            ],
            "title": "Push Service Api Key",
            "description": "API key for the push service (x-api-key header)"
        },
        "push_products": {
            "type": "boolean",
            "title": "Push Products",
            "description": "Whether to automatically push products to external system",
            "default": false
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id",
            "description": "Organization this integration belongs to"
        }
    },
    "type": "object",
    "required": [
        "name",
        "base_url",
        "username",
        "password"
    ],
    "title": "OVSIntegrationCreate",
    "description": "Schema for creating a new OVS integration.\n\nRegular users: Integration is created for themselves\nSuperusers: Can optionally specify user_id to create for another user",
    "example": {
        "base_url": "https://ovs.example.com/api",
        "name": "Production OVS",
        "password": "secure_password",
        "push_products": false,
        "push_service_api_key": "your-api-key",
        "push_service_base_url": "https://upload.example.com/stage",
        "username": "api_user"
    }
}

Responses

201 Created422 Unprocessable Entity

application/json

{
    "base_url": "https://ovs.example.com/api",
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "integration_type": "ovs",
    "name": "Production OVS",
    "push_products": true,
    "push_service_base_url": "https://upload.example.com/stage",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001",
    "username": "api_user"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "integration_type": {
            "type": "string",
            "title": "Integration Type"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "base_url": {
            "type": "string",
            "title": "Base Url"
        },
        "username": {
            "type": "string",
            "title": "Username"
        },
        "push_service_base_url": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Push Service Base Url"
        },
        "push_products": {
            "type": "boolean",
            "title": "Push Products",
            "default": false
        }
    },
    "type": "object",
    "required": [
        "id",
        "name",
        "integration_type",
        "user_id",
        "base_url",
        "username"
    ],
    "title": "OVSIntegrationPublic",
    "description": "Public schema for OVS integration with all fields.\n\nNote: Sensitive fields are intentionally excluded for security:\n- password: User credentials (security)\n- token: JWT authentication token (auto-managed by OVSService)\n- token_expires_at: Token expiration timestamp (auto-managed by OVSService)\n- push_service_api_key: API key for push service (security)\n\nToken management is handled automatically by the OVSService class.",
    "example": {
        "base_url": "https://ovs.example.com/api",
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "integration_type": "ovs",
        "name": "Production OVS",
        "push_products": true,
        "push_service_base_url": "https://upload.example.com/stage",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001",
        "username": "api_user"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/external-integrations/{integration_id}

Read Integration

Description

Get a specific integration by ID.

Returns the integration with all type-specific fields. Currently only OVS integrations are supported.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
integration_id	path	string		No
organization_id	query			No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "base_url": "https://ovs.example.com/api",
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "integration_type": "ovs",
    "name": "Production OVS",
    "push_products": true,
    "push_service_base_url": "https://upload.example.com/stage",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001",
    "username": "api_user"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "integration_type": {
            "type": "string",
            "title": "Integration Type"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "base_url": {
            "type": "string",
            "title": "Base Url"
        },
        "username": {
            "type": "string",
            "title": "Username"
        },
        "push_service_base_url": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Push Service Base Url"
        },
        "push_products": {
            "type": "boolean",
            "title": "Push Products",
            "default": false
        }
    },
    "type": "object",
    "required": [
        "id",
        "name",
        "integration_type",
        "user_id",
        "base_url",
        "username"
    ],
    "title": "OVSIntegrationPublic",
    "description": "Public schema for OVS integration with all fields.\n\nNote: Sensitive fields are intentionally excluded for security:\n- password: User credentials (security)\n- token: JWT authentication token (auto-managed by OVSService)\n- token_expires_at: Token expiration timestamp (auto-managed by OVSService)\n- push_service_api_key: API key for push service (security)\n\nToken management is handled automatically by the OVSService class.",
    "example": {
        "base_url": "https://ovs.example.com/api",
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "integration_type": "ovs",
        "name": "Production OVS",
        "push_products": true,
        "push_service_base_url": "https://upload.example.com/stage",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001",
        "username": "api_user"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

DELETE /api/v1/external-integrations/{integration_id}

Delete Integration

Description

Delete an external integration.

Only the owner, organization member, or superuser can delete an integration. This will permanently remove the integration and all its configuration.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
integration_id	path	string		No
organization_id	query			No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "message": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "message": {
            "type": "string",
            "title": "Message"
        }
    },
    "type": "object",
    "required": [
        "message"
    ],
    "title": "Message"
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

PUT /api/v1/external-integrations/ovs/{integration_id}

Update Ovs Integration

Description

Update an existing OVS integration.

Only the owner, organization member, or superuser can update an integration. All fields are optional - only provided fields will be updated.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
integration_id	path	string		No
organization_id	query			No

Request body

application/json

{
    "base_url": "https://ovs-new.example.com/api",
    "name": "Updated Production OVS",
    "push_products": true,
    "push_service_base_url": "https://upload.example.com/stage"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "name": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 255
                },
                {
                    "type": "null"
                }
            ],
            "title": "Name"
        },
        "base_url": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 255
                },
                {
                    "type": "null"
                }
            ],
            "title": "Base Url"
        },
        "username": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 255
                },
                {
                    "type": "null"
                }
            ],
            "title": "Username"
        },
        "password": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 255
                },
                {
                    "type": "null"
                }
            ],
            "title": "Password"
        },
        "push_service_base_url": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 500
                },
                {
                    "type": "null"
                }
            ],
            "title": "Push Service Base Url"
        },
        "push_service_api_key": {
            "anyOf": [
                {
                    "type": "string",
                    "maxLength": 500
                },
                {
                    "type": "null"
                }
            ],
            "title": "Push Service Api Key"
        },
        "push_products": {
            "anyOf": [
                {
                    "type": "boolean"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Push Products"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id",
            "description": "Organization to transfer this integration to"
        },
        "user_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "User Id",
            "description": "User to transfer this integration to (admin only)"
        }
    },
    "type": "object",
    "title": "OVSIntegrationUpdate",
    "description": "Schema for updating an existing OVS integration.",
    "example": {
        "base_url": "https://ovs-new.example.com/api",
        "name": "Updated Production OVS",
        "push_products": true,
        "push_service_base_url": "https://upload.example.com/stage"
    }
}

Responses

200 OK422 Unprocessable Entity

application/json

{
    "base_url": "https://ovs.example.com/api",
    "created_at": "2025-01-01T00:00:00Z",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "integration_type": "ovs",
    "name": "Production OVS",
    "push_products": true,
    "push_service_base_url": "https://upload.example.com/stage",
    "updated_at": "2025-01-01T00:00:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174001",
    "username": "api_user"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        },
        "name": {
            "type": "string",
            "title": "Name"
        },
        "integration_type": {
            "type": "string",
            "title": "Integration Type"
        },
        "user_id": {
            "type": "string",
            "format": "uuid",
            "title": "User Id"
        },
        "organization_id": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "uuid"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Organization Id"
        },
        "base_url": {
            "type": "string",
            "title": "Base Url"
        },
        "username": {
            "type": "string",
            "title": "Username"
        },
        "push_service_base_url": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Push Service Base Url"
        },
        "push_products": {
            "type": "boolean",
            "title": "Push Products",
            "default": false
        }
    },
    "type": "object",
    "required": [
        "id",
        "name",
        "integration_type",
        "user_id",
        "base_url",
        "username"
    ],
    "title": "OVSIntegrationPublic",
    "description": "Public schema for OVS integration with all fields.\n\nNote: Sensitive fields are intentionally excluded for security:\n- password: User credentials (security)\n- token: JWT authentication token (auto-managed by OVSService)\n- token_expires_at: Token expiration timestamp (auto-managed by OVSService)\n- push_service_api_key: API key for push service (security)\n\nToken management is handled automatically by the OVSService class.",
    "example": {
        "base_url": "https://ovs.example.com/api",
        "created_at": "2025-01-01T00:00:00Z",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "integration_type": "ovs",
        "name": "Production OVS",
        "push_products": true,
        "push_service_base_url": "https://upload.example.com/stage",
        "updated_at": "2025-01-01T00:00:00Z",
        "user_id": "123e4567-e89b-12d3-a456-426614174001",
        "username": "api_user"
    }
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/external-integrations/ovs/{integration_id}/sync

Trigger Ovs Sync

Description

Trigger manual product sync for an OVS integration.

This endpoint starts a background sync process for the specified integration. The sync will import new and updated products from OVS.

Returns HTTP 202 Accepted to indicate the sync has been queued. Use the sync status endpoint to check progress.

Only the owner, organization member, or superuser can trigger sync.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
integration_id	path	string		No
organization_id	query			No

Responses

202 Accepted422 Unprocessable Entity

application/json

{
    "message": "string",
    "integration_id": "e36a034d-c867-411e-8fc9-280ba2544c1f",
    "status": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "message": {
            "type": "string",
            "title": "Message",
            "description": "Human-readable message about the sync trigger"
        },
        "integration_id": {
            "type": "string",
            "format": "uuid",
            "title": "Integration Id",
            "description": "Integration ID that was triggered"
        },
        "status": {
            "type": "string",
            "title": "Status",
            "description": "Sync trigger status (e.g., 'queued', 'started')"
        }
    },
    "type": "object",
    "required": [
        "message",
        "integration_id",
        "status"
    ],
    "title": "SyncTriggerResponse",
    "description": "Response for manual sync trigger."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/external-integrations/ovs/{integration_id}/sync/status

Get Ovs Sync Status

Description

Get current sync status and statistics for an OVS integration.

Returns information about: - Current sync status (idle, running, completed, error) - Last sync timestamps - Cumulative statistics (total products synced/skipped) - Last run statistics - Error messages (if any)

Only the owner, organization member, or superuser can view sync status.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
integration_id	path	string		No
organization_id	query			No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "integration_id": "40fbf49e-9fb0-4d24-b5c7-5e1f2d4f4f51",
    "sync_status": "string",
    "last_sync_at": null,
    "last_successful_sync_at": null,
    "total_products_synced": 0,
    "total_products_updated": 0,
    "total_products_skipped": 0,
    "last_sync_stats": {},
    "last_error_message": null
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "integration_id": {
            "type": "string",
            "format": "uuid",
            "title": "Integration Id",
            "description": "Integration ID"
        },
        "sync_status": {
            "type": "string",
            "title": "Sync Status",
            "description": "Current sync status: idle, running, completed, error"
        },
        "last_sync_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Sync At",
            "description": "Last sync attempt timestamp (successful or failed)"
        },
        "last_successful_sync_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Successful Sync At",
            "description": "Last successful sync completion timestamp"
        },
        "total_products_synced": {
            "type": "integer",
            "title": "Total Products Synced",
            "description": "Total number of products successfully synced (all time)",
            "default": 0
        },
        "total_products_updated": {
            "type": "integer",
            "title": "Total Products Updated",
            "description": "Total number of products updated (all time)",
            "default": 0
        },
        "total_products_skipped": {
            "type": "integer",
            "title": "Total Products Skipped",
            "description": "Total number of products skipped (already exist)",
            "default": 0
        },
        "last_sync_stats": {
            "additionalProperties": {
                "type": "integer"
            },
            "type": "object",
            "title": "Last Sync Stats",
            "description": "Statistics from last sync run"
        },
        "last_error_message": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Last Error Message",
            "description": "Error message from last failed sync"
        }
    },
    "type": "object",
    "required": [
        "integration_id",
        "sync_status"
    ],
    "title": "SyncStatusResponse",
    "description": "Current sync status and statistics for an integration."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

POST /api/v1/external-integrations/{integration_id}/import-products

Trigger Ovs Product Import

Description

Trigger an on-demand import of specific products from OVS by product codes.

The import runs as a background Celery task. Poll the task status endpoint to check progress and results.

Returns HTTP 202 Accepted with the created task details.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
integration_id	path	string		No
organization_id	query			No

Request body

application/json

{
    "product_codes": [
        "string"
    ],
    "is_filler": true
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "properties": {
        "product_codes": {
            "items": {
                "type": "string"
            },
            "type": "array",
            "title": "Product Codes"
        },
        "is_filler": {
            "type": "boolean",
            "title": "Is Filler",
            "default": false
        }
    },
    "type": "object",
    "required": [
        "product_codes"
    ],
    "title": "OVSProductImportRequest",
    "description": "Request body for triggering an OVS product import."
}

Responses

202 Accepted422 Unprocessable Entity

application/json

{
    "id": "6c65f10e-c259-47bc-b6e4-902b5a8a74d6",
    "owner_id": "b5a4128b-41f9-47d3-87c9-0a200bfb4be1",
    "integration_id": "6b2400cb-aba8-455b-b932-5f8a21620e39",
    "status": "PENDING",
    "progress": 0,
    "total_items": 0,
    "processed_items": 0,
    "product_codes_count": 0,
    "is_filler": true,
    "result_data": null,
    "error_message": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2022-04-13T15:42:05.901Z",
    "updated_at": "2022-04-13T15:42:05.901Z"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "owner_id": {
            "type": "string",
            "format": "uuid",
            "title": "Owner Id"
        },
        "integration_id": {
            "type": "string",
            "format": "uuid",
            "title": "Integration Id"
        },
        "status": {
            "$ref": "#/components/schemas/TaskStatus-Output"
        },
        "progress": {
            "type": "integer",
            "title": "Progress"
        },
        "total_items": {
            "type": "integer",
            "title": "Total Items"
        },
        "processed_items": {
            "type": "integer",
            "title": "Processed Items"
        },
        "product_codes_count": {
            "type": "integer",
            "title": "Product Codes Count"
        },
        "is_filler": {
            "type": "boolean",
            "title": "Is Filler",
            "default": false
        },
        "result_data": {
            "anyOf": [
                {
                    "additionalProperties": true,
                    "type": "object"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Result Data"
        },
        "error_message": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Error Message"
        },
        "started_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Started At"
        },
        "completed_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Completed At"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        }
    },
    "type": "object",
    "required": [
        "id",
        "owner_id",
        "integration_id",
        "status",
        "progress",
        "total_items",
        "processed_items",
        "product_codes_count",
        "created_at",
        "updated_at"
    ],
    "title": "OVSProductImportTaskPublic",
    "description": "Public schema for OVS product import task responses."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/external-integrations/{integration_id}/import-tasks

List Ovs Import Tasks

Description

List previous OVS product import tasks for an integration.

Returns a paginated list of import tasks with their status and results.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
integration_id	path	string		No
limit	query	integer	10	No
organization_id	query			No
skip	query	integer	0	No
status	query			No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "data": [
        {
            "id": "8ddc706e-cdfb-4d73-be20-06d57fa02d34",
            "owner_id": "edee7c2b-9258-4cef-ba7f-ba6a115362a7",
            "integration_id": "2e92db0d-07cc-444d-a16e-fcc552495609",
            "status": "PENDING",
            "progress": 0,
            "total_items": 0,
            "processed_items": 0,
            "product_codes_count": 0,
            "is_filler": true,
            "result_data": null,
            "error_message": null,
            "started_at": null,
            "completed_at": null,
            "created_at": "2022-04-13T15:42:05.901Z",
            "updated_at": "2022-04-13T15:42:05.901Z"
        }
    ],
    "count": 0
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "data": {
            "items": {
                "$ref": "#/components/schemas/OVSProductImportTaskPublic"
            },
            "type": "array",
            "title": "Data"
        },
        "count": {
            "type": "integer",
            "title": "Count"
        }
    },
    "type": "object",
    "required": [
        "data",
        "count"
    ],
    "title": "OVSProductImportTasksPublic",
    "description": "Paginated list of OVS product import tasks."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

GET /api/v1/external-integrations/{integration_id}/import-tasks/{task_id}

Get Ovs Import Task Status

Description

Get the status of a specific OVS product import task.

Poll this endpoint to check import progress and get results when complete.

Input parameters

Parameter	In	Type	Default	Nullable	Description
OAuth2PasswordBearer	header	string	N/A	No
integration_id	path	string		No
organization_id	query			No
task_id	path	string		No

Responses

200 OK422 Unprocessable Entity

application/json

{
    "id": "724046ee-48f7-4274-a32d-47142bbc1452",
    "owner_id": "1fcd2979-9e26-4335-b653-185c29ac8ef6",
    "integration_id": "c241debd-0654-4999-8fac-4c94f5145fa1",
    "status": "PENDING",
    "progress": 0,
    "total_items": 0,
    "processed_items": 0,
    "product_codes_count": 0,
    "is_filler": true,
    "result_data": null,
    "error_message": null,
    "started_at": null,
    "completed_at": null,
    "created_at": "2022-04-13T15:42:05.901Z",
    "updated_at": "2022-04-13T15:42:05.901Z"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "id": {
            "type": "string",
            "format": "uuid",
            "title": "Id"
        },
        "owner_id": {
            "type": "string",
            "format": "uuid",
            "title": "Owner Id"
        },
        "integration_id": {
            "type": "string",
            "format": "uuid",
            "title": "Integration Id"
        },
        "status": {
            "$ref": "#/components/schemas/TaskStatus-Output"
        },
        "progress": {
            "type": "integer",
            "title": "Progress"
        },
        "total_items": {
            "type": "integer",
            "title": "Total Items"
        },
        "processed_items": {
            "type": "integer",
            "title": "Processed Items"
        },
        "product_codes_count": {
            "type": "integer",
            "title": "Product Codes Count"
        },
        "is_filler": {
            "type": "boolean",
            "title": "Is Filler",
            "default": false
        },
        "result_data": {
            "anyOf": [
                {
                    "additionalProperties": true,
                    "type": "object"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Result Data"
        },
        "error_message": {
            "anyOf": [
                {
                    "type": "string"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Error Message"
        },
        "started_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Started At"
        },
        "completed_at": {
            "anyOf": [
                {
                    "type": "string",
                    "format": "date-time"
                },
                {
                    "type": "null"
                }
            ],
            "title": "Completed At"
        },
        "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At"
        },
        "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At"
        }
    },
    "type": "object",
    "required": [
        "id",
        "owner_id",
        "integration_id",
        "status",
        "progress",
        "total_items",
        "processed_items",
        "product_codes_count",
        "created_at",
        "updated_at"
    ],
    "title": "OVSProductImportTaskPublic",
    "description": "Public schema for OVS product import task responses."
}

application/json

{
    "detail": [
        {
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string",
            "input": null,
            "ctx": {}
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "properties": {
        "detail": {
            "items": {
                "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
        }
    },
    "type": "object",
    "title": "HTTPValidationError"
}

---

Schemas

app__models__base_task__TaskStatus

Type: string

ExternalSystemIntegrationPublic

Name	Type	Description
created_at	string(date-time)
id	string(uuid)
integration_type	string
name	string
organization_id
updated_at	string(date-time)
user_id	string(uuid)

ExternalSystemIntegrationsPublic

Name	Type	Description
count	integer
created_at	string(date-time)
data	Array<ExternalSystemIntegrationPublic>
id	string(uuid)
updated_at	string(date-time)

HTTPValidationError

Name	Type	Description
detail	Array<ValidationError>

IntegrationType

Type: string

Message

Name	Type	Description
message	string

OVSIntegrationCreate

Name	Type	Description
base_url	string	Base URL of the OVS API endpoint
name	string	User-friendly name for this integration
organization_id		Organization this integration belongs to
password	string	Password for OVS authentication
push_products	boolean	Whether to automatically push products to external system
push_service_api_key		API key for the push service (x-api-key header)
push_service_base_url		Base URL of the push service API for image uploads
user_id		User ID to create integration for (superusers only). If not provided, creates for current user.
username	string	Username for OVS authentication

OVSIntegrationPublic

Name	Type	Description
base_url	string
created_at	string(date-time)
id	string(uuid)
integration_type	string
name	string
organization_id
push_products	boolean
push_service_base_url
updated_at	string(date-time)
user_id	string(uuid)
username	string

OVSIntegrationsPublic

Name	Type	Description
count	integer
created_at	string(date-time)
data	Array<OVSIntegrationPublic>
id	string(uuid)
updated_at	string(date-time)

OVSIntegrationUpdate

Name	Type	Description
base_url
name
organization_id		Organization to transfer this integration to
password
push_products
push_service_api_key
push_service_base_url
user_id		User to transfer this integration to (admin only)
username

OVSProductImportRequest

Name	Type	Description
is_filler	boolean
product_codes	Array<string>

OVSProductImportTaskPublic

Name	Type	Description
completed_at
created_at	string(date-time)
error_message
id	string(uuid)
integration_id	string(uuid)
is_filler	boolean
owner_id	string(uuid)
processed_items	integer
product_codes_count	integer
progress	integer
result_data
started_at
status	TaskStatus-Output
total_items	integer
updated_at	string(date-time)

OVSProductImportTasksPublic

Name	Type	Description
count	integer
data	Array<OVSProductImportTaskPublic>

SyncStatusResponse

Name	Type	Description
integration_id	string(uuid)	Integration ID
last_error_message		Error message from last failed sync
last_successful_sync_at		Last successful sync completion timestamp
last_sync_at		Last sync attempt timestamp (successful or failed)
last_sync_stats		Statistics from last sync run
sync_status	string	Current sync status: idle, running, completed, error
total_products_skipped	integer	Total number of products skipped (already exist)
total_products_synced	integer	Total number of products successfully synced (all time)
total_products_updated	integer	Total number of products updated (all time)

SyncTriggerResponse

Name	Type	Description
integration_id	string(uuid)	Integration ID that was triggered
message	string	Human-readable message about the sync trigger
status	string	Sync trigger status (e.g., 'queued', 'started')

TaskStatus-Output

Type: string

ValidationError

Name	Type	Description
ctx
input
loc	Array<>
msg	string
type	string

Security schemes

Name	Type	Scheme	Description
OAuth2PasswordBearer	oauth2