{
  "openapi": "3.1.0",
  "info": {
    "title": "Pralo Public API",
    "version": "1.0.0",
    "description": "Versioned workspace-scoped interface over existing Pralo services. Availability requires platform deployment. Pricing is centrally configured and disabled by default."
  },
  "servers": [
    {
      "url": "https://api.pralo.ai"
    }
  ],
  "security": [
    {
      "apiKey": []
    },
    {
      "oauth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Workspace-scoped pralo_test_ or pralo_live_ key. Treat as a server-side secret."
      },
      "oauth": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://pralo.ai/developers/authorize",
            "tokenUrl": "https://api.pralo.ai/oauth/token",
            "scopes": {
              "workspace:read": "workspace:read",
              "analytics:read": "analytics:read",
              "products:read": "products:read",
              "orders:read": "orders:read",
              "customers:read": "customers:read",
              "agents:read": "agents:read",
              "conversations:read": "conversations:read",
              "payments:read": "payments:read",
              "storefronts:read": "storefronts:read",
              "products:write": "products:write",
              "inventory:read": "inventory:read",
              "inventory:write": "inventory:write",
              "customers:write": "customers:write",
              "agents:write": "agents:write",
              "agents:run": "agents:run",
              "messages:email": "messages:email",
              "messages:whatsapp": "messages:whatsapp",
              "messages:sms": "messages:sms",
              "checkout:create": "checkout:create",
              "checkout:read": "checkout:read",
              "orders:write": "orders:write",
              "usage:read": "usage:read",
              "logs:read": "logs:read",
              "webhooks:read": "webhooks:read"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "request_id"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    }
  },
  "paths": {
    "/v1/workspace": {
      "get": {
        "operationId": "workspace_get",
        "summary": "Read the authorized workspace.",
        "tags": [
          "workspace"
        ],
        "x-pralo-scope": "workspace:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_workspace",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "workspace:read"
            ]
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "slug": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "environment": {
                          "type": "string",
                          "enum": [
                            "test",
                            "live"
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "slug",
                        "environment"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/commissions": {
      "get": {
        "operationId": "commissions_list",
        "summary": "Read append-only commission accruals and refund adjustments in minor currency units. These are not payout confirmations.",
        "tags": [
          "commissions"
        ],
        "x-pralo-scope": "analytics:read",
        "x-pralo-risk": "READ",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "analytics:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "beneficiary_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "website_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "order_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "beneficiary_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "award_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "currency": {
                                "type": "string"
                              },
                              "amount_minor": {
                                "type": "integer"
                              },
                              "refunded_amount": {
                                "type": "integer"
                              },
                              "entry_type": {
                                "type": "string",
                                "enum": [
                                  "accrual",
                                  "refund_adjustment"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "website_id",
                              "order_id",
                              "beneficiary_id",
                              "award_id",
                              "currency",
                              "amount_minor",
                              "refunded_amount",
                              "entry_type",
                              "created_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/commissions/{id}": {
      "get": {
        "operationId": "commissions_get",
        "summary": "Read one commission entry referenced by a commission.entry.created webhook.",
        "tags": [
          "commissions"
        ],
        "x-pralo-scope": "analytics:read",
        "x-pralo-risk": "READ",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "analytics:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "website_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "order_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "beneficiary_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "award_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "amount_minor": {
                          "type": "integer"
                        },
                        "refunded_amount": {
                          "type": "integer"
                        },
                        "entry_type": {
                          "type": "string",
                          "enum": [
                            "accrual",
                            "refund_adjustment"
                          ]
                        },
                        "created_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "website_id",
                        "order_id",
                        "beneficiary_id",
                        "award_id",
                        "currency",
                        "amount_minor",
                        "refunded_amount",
                        "entry_type",
                        "created_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/referral-members": {
      "get": {
        "operationId": "referral_members_list",
        "summary": "Read affiliate and sales rep identities for this workspace.",
        "tags": [
          "referral_members"
        ],
        "x-pralo-scope": "analytics:read",
        "x-pralo-risk": "READ",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "analytics:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "kind": {
                                "type": "string",
                                "enum": [
                                  "affiliate",
                                  "sales_rep"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "name",
                              "kind",
                              "created_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/products": {
      "get": {
        "operationId": "products_list",
        "summary": "List products in this workspace with cursor pagination.",
        "tags": [
          "products"
        ],
        "x-pralo-scope": "products:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_list_products",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "products:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "sku": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "description": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "currency": {
                                "type": "string"
                              },
                              "unit_price": {
                                "type": "number"
                              },
                              "retail_price": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "stock_quantity": {
                                "type": "integer"
                              },
                              "committed_stock": {
                                "type": "integer"
                              },
                              "is_active": {
                                "type": "boolean"
                              },
                              "website_id": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "name",
                              "sku",
                              "description",
                              "currency",
                              "unit_price",
                              "retail_price",
                              "stock_quantity",
                              "committed_stock",
                              "is_active",
                              "website_id",
                              "created_at",
                              "updated_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "products_create",
        "summary": "Create a canonical workspace inventory product. Stock starts at zero.",
        "tags": [
          "products"
        ],
        "x-pralo-scope": "products:write",
        "x-pralo-risk": "WRITE",
        "x-pralo-mcp-tool": "pralo_create_product",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "products:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "sku": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 100
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 4000
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "currency": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "default": "USD"
                  },
                  "unit_price": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 10000000,
                    "default": 0
                  },
                  "retail_price": {
                    "anyOf": [
                      {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 10000000
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "website_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "is_active": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "sku": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "currency": {
                          "type": "string"
                        },
                        "unit_price": {
                          "type": "number"
                        },
                        "retail_price": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "stock_quantity": {
                          "type": "integer"
                        },
                        "committed_stock": {
                          "type": "integer"
                        },
                        "is_active": {
                          "type": "boolean"
                        },
                        "website_id": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "sku",
                        "description",
                        "currency",
                        "unit_price",
                        "retail_price",
                        "stock_quantity",
                        "committed_stock",
                        "is_active",
                        "website_id",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/products/{id}": {
      "get": {
        "operationId": "products_get",
        "summary": "Read one product in this workspace.",
        "tags": [
          "products"
        ],
        "x-pralo-scope": "products:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_product",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "products:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "sku": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "currency": {
                          "type": "string"
                        },
                        "unit_price": {
                          "type": "number"
                        },
                        "retail_price": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "stock_quantity": {
                          "type": "integer"
                        },
                        "committed_stock": {
                          "type": "integer"
                        },
                        "is_active": {
                          "type": "boolean"
                        },
                        "website_id": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "sku",
                        "description",
                        "currency",
                        "unit_price",
                        "retail_price",
                        "stock_quantity",
                        "committed_stock",
                        "is_active",
                        "website_id",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "products_update",
        "summary": "Update product details without modifying stock reservations.",
        "tags": [
          "products"
        ],
        "x-pralo-scope": "products:write",
        "x-pralo-risk": "WRITE",
        "x-pralo-mcp-tool": "pralo_update_product",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "products:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "sku": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 100
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "description": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 4000
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "currency": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$",
                    "default": "USD"
                  },
                  "unit_price": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 10000000,
                    "default": 0
                  },
                  "retail_price": {
                    "anyOf": [
                      {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 10000000
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "website_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "is_active": {
                    "type": "boolean"
                  }
                },
                "required": [],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "sku": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "currency": {
                          "type": "string"
                        },
                        "unit_price": {
                          "type": "number"
                        },
                        "retail_price": {
                          "type": [
                            "number",
                            "null"
                          ]
                        },
                        "stock_quantity": {
                          "type": "integer"
                        },
                        "committed_stock": {
                          "type": "integer"
                        },
                        "is_active": {
                          "type": "boolean"
                        },
                        "website_id": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "sku",
                        "description",
                        "currency",
                        "unit_price",
                        "retail_price",
                        "stock_quantity",
                        "committed_stock",
                        "is_active",
                        "website_id",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders": {
      "get": {
        "operationId": "orders_list",
        "summary": "List orders in this workspace with cursor pagination.",
        "tags": [
          "orders"
        ],
        "x-pralo-scope": "orders:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_list_orders",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "orders:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "website_id": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "customer_email": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "status": {
                                "type": "string"
                              },
                              "currency": {
                                "type": "string"
                              },
                              "subtotal_amount": {
                                "type": "number"
                              },
                              "total_amount": {
                                "type": "number"
                              },
                              "paid_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "fulfillment_status": {
                                "type": "string",
                                "enum": [
                                  "unknown",
                                  "needs_label",
                                  "label_ready",
                                  "shipped"
                                ]
                              },
                              "shipped_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "website_id",
                              "customer_email",
                              "status",
                              "currency",
                              "subtotal_amount",
                              "total_amount",
                              "paid_at",
                              "fulfillment_status",
                              "shipped_at",
                              "created_at",
                              "updated_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "orders_create",
        "summary": "Create an order through checkout from an existing cart; also requires checkout:create.",
        "tags": [
          "orders"
        ],
        "x-pralo-scope": "orders:write",
        "x-pralo-risk": "EXTERNAL_ACTION",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "orders:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          },
          {
            "name": "X-Pralo-Approval",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Required for live external actions. Workspace owner/admin creates a five-minute approval for this credential and exact input in Developers → Logs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "website_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "cart_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "return_origin": {
                    "type": "string",
                    "format": "uri"
                  },
                  "success_path": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "cancel_path": {
                    "type": "string",
                    "maxLength": 300
                  }
                },
                "required": [
                  "website_id",
                  "cart_id",
                  "return_origin"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string"
                        },
                        "url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "storefront_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "payment_mode": {
                          "type": "string",
                          "enum": [
                            "TEST",
                            "PRODUCTION"
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "url",
                        "storefront_id",
                        "payment_mode"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/orders/{id}": {
      "get": {
        "operationId": "orders_get",
        "summary": "Read one order in this workspace.",
        "tags": [
          "orders"
        ],
        "x-pralo-scope": "orders:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_order",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "orders:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "website_id": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "customer_email": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "subtotal_amount": {
                          "type": "number"
                        },
                        "total_amount": {
                          "type": "number"
                        },
                        "paid_at": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "fulfillment_status": {
                          "type": "string",
                          "enum": [
                            "unknown",
                            "needs_label",
                            "label_ready",
                            "shipped"
                          ]
                        },
                        "shipped_at": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "website_id",
                        "customer_email",
                        "status",
                        "currency",
                        "subtotal_amount",
                        "total_amount",
                        "paid_at",
                        "fulfillment_status",
                        "shipped_at",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/customers": {
      "get": {
        "operationId": "customers_list",
        "summary": "List customers in this workspace with cursor pagination.",
        "tags": [
          "customers"
        ],
        "x-pralo-scope": "customers:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_list_customers",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "customers:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "full_name": {
                                "type": "string"
                              },
                              "email": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "whatsapp_number": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "tags": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "is_active": {
                                "type": "boolean"
                              },
                              "website_id": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "full_name",
                              "email",
                              "whatsapp_number",
                              "tags",
                              "is_active",
                              "website_id",
                              "created_at",
                              "updated_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "customers_create",
        "summary": "Create a workspace customer.",
        "tags": [
          "customers"
        ],
        "x-pralo-scope": "customers:write",
        "x-pralo-risk": "WRITE",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "customers:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "full_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "email": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "email",
                        "maxLength": 254
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "whatsapp_number": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^\\+[1-9]\\d{7,14}$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 50
                    },
                    "maxItems": 30
                  },
                  "website_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "full_name"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "full_name": {
                          "type": "string"
                        },
                        "email": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "whatsapp_number": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "is_active": {
                          "type": "boolean"
                        },
                        "website_id": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "full_name",
                        "email",
                        "whatsapp_number",
                        "tags",
                        "is_active",
                        "website_id",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/customers/{id}": {
      "get": {
        "operationId": "customers_get",
        "summary": "Read one customer in this workspace.",
        "tags": [
          "customers"
        ],
        "x-pralo-scope": "customers:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_customer",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "customers:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "full_name": {
                          "type": "string"
                        },
                        "email": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "whatsapp_number": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "is_active": {
                          "type": "boolean"
                        },
                        "website_id": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "full_name",
                        "email",
                        "whatsapp_number",
                        "tags",
                        "is_active",
                        "website_id",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "customers_update",
        "summary": "Update customer contact details.",
        "tags": [
          "customers"
        ],
        "x-pralo-scope": "customers:write",
        "x-pralo-risk": "WRITE",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "customers:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "full_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "email": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "email",
                        "maxLength": 254
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "whatsapp_number": {
                    "anyOf": [
                      {
                        "type": "string",
                        "pattern": "^\\+[1-9]\\d{7,14}$"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 50
                    },
                    "maxItems": 30
                  },
                  "website_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "full_name": {
                          "type": "string"
                        },
                        "email": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "whatsapp_number": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "is_active": {
                          "type": "boolean"
                        },
                        "website_id": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "full_name",
                        "email",
                        "whatsapp_number",
                        "tags",
                        "is_active",
                        "website_id",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents": {
      "get": {
        "operationId": "agents_list",
        "summary": "List agents in this workspace with cursor pagination.",
        "tags": [
          "agents"
        ],
        "x-pralo-scope": "agents:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_list_agents",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "agents:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "name",
                              "slug",
                              "status",
                              "created_at",
                              "updated_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "agents_create",
        "summary": "Create a draft in the existing agent catalog. Provision its Connections runtime in Pralo before running.",
        "tags": [
          "agents"
        ],
        "x-pralo-scope": "agents:write",
        "x-pralo-risk": "WRITE",
        "x-pralo-mcp-tool": "pralo_create_agent",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "agents:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "instructions": {
                    "type": "string",
                    "maxLength": 4000,
                    "default": ""
                  }
                },
                "required": [
                  "name"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "slug",
                        "status",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/{id}": {
      "get": {
        "operationId": "agents_get",
        "summary": "Read one agent in this workspace.",
        "tags": [
          "agents"
        ],
        "x-pralo-scope": "agents:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_agent",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "agents:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "slug",
                        "status",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/conversations": {
      "get": {
        "operationId": "conversations_list",
        "summary": "List conversations in this workspace with cursor pagination.",
        "tags": [
          "conversations"
        ],
        "x-pralo-scope": "conversations:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_list_conversations",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "conversations:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "channel": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "last_message_at": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "channel",
                              "status",
                              "last_message_at",
                              "created_at",
                              "updated_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/conversations/{id}": {
      "get": {
        "operationId": "conversations_get",
        "summary": "Read one conversation in this workspace.",
        "tags": [
          "conversations"
        ],
        "x-pralo-scope": "conversations:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_conversation",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "conversations:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "channel": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "last_message_at": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "channel",
                        "status",
                        "last_message_at",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments": {
      "get": {
        "operationId": "payments_list",
        "summary": "List payments in this workspace with cursor pagination.",
        "tags": [
          "payments"
        ],
        "x-pralo-scope": "payments:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_list_payments",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "payments:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "order_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "website_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "status": {
                                "type": "string"
                              },
                              "currency": {
                                "type": "string"
                              },
                              "total_amount": {
                                "type": "number"
                              },
                              "refunded_amount": {
                                "type": "number"
                              },
                              "paid_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "order_id",
                              "website_id",
                              "status",
                              "currency",
                              "total_amount",
                              "refunded_amount",
                              "paid_at",
                              "created_at",
                              "updated_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}": {
      "get": {
        "operationId": "payments_get",
        "summary": "Read one payment in this workspace.",
        "tags": [
          "payments"
        ],
        "x-pralo-scope": "payments:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_payment",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "payments:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "order_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "website_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string"
                        },
                        "currency": {
                          "type": "string"
                        },
                        "total_amount": {
                          "type": "number"
                        },
                        "refunded_amount": {
                          "type": "number"
                        },
                        "paid_at": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "order_id",
                        "website_id",
                        "status",
                        "currency",
                        "total_amount",
                        "refunded_amount",
                        "paid_at",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/storefronts": {
      "get": {
        "operationId": "storefronts_list",
        "summary": "List storefronts in this workspace with cursor pagination.",
        "tags": [
          "storefronts"
        ],
        "x-pralo-scope": "storefronts:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_list_storefronts",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "storefronts:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "slug": {
                                "type": "string"
                              },
                              "primary_domain": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "status": {
                                "type": "string"
                              },
                              "environment": {
                                "type": "string"
                              },
                              "default_currency": {
                                "type": "string"
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "name",
                              "slug",
                              "primary_domain",
                              "status",
                              "environment",
                              "default_currency",
                              "created_at",
                              "updated_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/storefronts/{id}": {
      "get": {
        "operationId": "storefronts_get",
        "summary": "Read one storefront in this workspace.",
        "tags": [
          "storefronts"
        ],
        "x-pralo-scope": "storefronts:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_storefront",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "storefronts:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "primary_domain": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "status": {
                          "type": "string"
                        },
                        "environment": {
                          "type": "string"
                        },
                        "default_currency": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "slug",
                        "primary_domain",
                        "status",
                        "environment",
                        "default_currency",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inventory": {
      "get": {
        "operationId": "inventory_list",
        "summary": "Read physical and reserved inventory quantities.",
        "tags": [
          "inventory"
        ],
        "x-pralo-scope": "inventory:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_inventory",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "inventory:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": "string"
                              },
                              "sku": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "stock_quantity": {
                                "type": "integer"
                              },
                              "committed_stock": {
                                "type": "integer"
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "name",
                              "sku",
                              "stock_quantity",
                              "committed_stock",
                              "created_at",
                              "updated_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/inventory/{id}": {
      "patch": {
        "operationId": "inventory_update",
        "summary": "Set physical stock only if expected stock still matches. Reserved stock remains protected.",
        "tags": [
          "inventory"
        ],
        "x-pralo-scope": "inventory:write",
        "x-pralo-risk": "WRITE",
        "x-pralo-mcp-tool": "pralo_update_inventory",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "inventory:write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stock_quantity": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000000
                  },
                  "expected_stock_quantity": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000000
                  }
                },
                "required": [
                  "stock_quantity",
                  "expected_stock_quantity"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "sku": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "stock_quantity": {
                          "type": "integer"
                        },
                        "committed_stock": {
                          "type": "integer"
                        },
                        "created_at": {
                          "type": "string"
                        },
                        "updated_at": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "sku",
                        "stock_quantity",
                        "committed_stock",
                        "created_at",
                        "updated_at"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/customers/search": {
      "get": {
        "operationId": "customers_search",
        "summary": "Search customers by name or exact email.",
        "tags": [
          "customers"
        ],
        "x-pralo-scope": "customers:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_search_customers",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "customers:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "full_name": {
                                "type": "string"
                              },
                              "email": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "whatsapp_number": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "tags": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "is_active": {
                                "type": "boolean"
                              },
                              "website_id": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "full_name",
                              "email",
                              "whatsapp_number",
                              "tags",
                              "is_active",
                              "website_id",
                              "created_at",
                              "updated_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/agents/{id}/run": {
      "post": {
        "operationId": "agents_run",
        "summary": "Ask a provisioned agent a knowledge-only question. Does not authorize tool actions or sending messages.",
        "tags": [
          "agents"
        ],
        "x-pralo-scope": "agents:run",
        "x-pralo-risk": "EXTERNAL_ACTION",
        "x-pralo-mcp-tool": "pralo_run_agent",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "agents:run"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          },
          {
            "name": "X-Pralo-Approval",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Required for live external actions. Workspace owner/admin creates a five-minute approval for this credential and exact input in Developers → Logs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 8000
                  }
                },
                "required": [
                  "message"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "reply": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "completed",
                            "simulated"
                          ]
                        },
                        "simulated": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "id",
                        "reply",
                        "status",
                        "simulated"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/email": {
      "post": {
        "operationId": "messages_email",
        "summary": "Send email through the existing Pralo integration after owner approval. Test mode simulates delivery.",
        "tags": [
          "messages"
        ],
        "x-pralo-scope": "messages:email",
        "x-pralo-risk": "EXTERNAL_ACTION",
        "x-pralo-mcp-tool": "pralo_send_email",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "messages:email"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          },
          {
            "name": "X-Pralo-Approval",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Required for live external actions. Workspace owner/admin creates a five-minute approval for this credential and exact input in Developers → Logs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "to": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "email"
                    },
                    "minItems": 1,
                    "maxItems": 25
                  },
                  "subject": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500
                  },
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 50000
                  }
                },
                "required": [
                  "account_id",
                  "to",
                  "subject",
                  "body"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "simulated": {
                          "type": "boolean"
                        },
                        "delivered": {
                          "type": "boolean",
                          "const": false
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "simulated",
                        "delivered"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/whatsapp": {
      "post": {
        "operationId": "messages_whatsapp",
        "summary": "Send whatsapp through the existing Pralo integration after owner approval. Test mode simulates delivery.",
        "tags": [
          "messages"
        ],
        "x-pralo-scope": "messages:whatsapp",
        "x-pralo-risk": "EXTERNAL_ACTION",
        "x-pralo-mcp-tool": "pralo_send_whatsapp",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "messages:whatsapp"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          },
          {
            "name": "X-Pralo-Approval",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Required for live external actions. Workspace owner/admin creates a five-minute approval for this credential and exact input in Developers → Logs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "conversation_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4000
                  }
                },
                "required": [
                  "conversation_id",
                  "text"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "simulated": {
                          "type": "boolean"
                        },
                        "delivered": {
                          "type": "boolean",
                          "const": false
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "simulated",
                        "delivered"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/sms": {
      "post": {
        "operationId": "messages_sms",
        "summary": "Send sms through the existing Pralo integration after owner approval. Test mode simulates delivery.",
        "tags": [
          "messages"
        ],
        "x-pralo-scope": "messages:sms",
        "x-pralo-risk": "EXTERNAL_ACTION",
        "x-pralo-mcp-tool": "pralo_send_sms",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "messages:sms"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          },
          {
            "name": "X-Pralo-Approval",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Required for live external actions. Workspace owner/admin creates a five-minute approval for this credential and exact input in Developers → Logs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "pattern": "^\\+[1-9]\\d{7,14}$"
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1600
                  }
                },
                "required": [
                  "to",
                  "text"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "simulated": {
                          "type": "boolean"
                        },
                        "delivered": {
                          "type": "boolean",
                          "const": false
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "simulated",
                        "delivered"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/checkout": {
      "post": {
        "operationId": "checkout_create",
        "summary": "Create checkout using an existing cart and Pralo checkout rules. No charge is made by this operation.",
        "tags": [
          "checkout"
        ],
        "x-pralo-scope": "checkout:create",
        "x-pralo-risk": "EXTERNAL_ACTION",
        "x-pralo-mcp-tool": "pralo_create_checkout",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "checkout:create"
            ]
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            },
            "description": "Reuse this key only for the identical operation and input. Concurrent requests cannot execute twice."
          },
          {
            "name": "X-Pralo-Approval",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Required for live external actions. Workspace owner/admin creates a five-minute approval for this credential and exact input in Developers → Logs."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "website_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "cart_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "return_origin": {
                    "type": "string",
                    "format": "uri"
                  },
                  "success_path": {
                    "type": "string",
                    "maxLength": 300
                  },
                  "cancel_path": {
                    "type": "string",
                    "maxLength": 300
                  }
                },
                "required": [
                  "website_id",
                  "cart_id",
                  "return_origin"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string"
                        },
                        "url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "storefront_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "payment_mode": {
                          "type": "string",
                          "enum": [
                            "TEST",
                            "PRODUCTION"
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "url",
                        "storefront_id",
                        "payment_mode"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/checkout/{id}": {
      "get": {
        "operationId": "checkout_get",
        "summary": "Read a checkout using its order ID.",
        "tags": [
          "checkout"
        ],
        "x-pralo-scope": "checkout:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_checkout",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "checkout:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "status": {
                          "type": "string"
                        },
                        "url": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "storefront_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "payment_mode": {
                          "type": "string",
                          "enum": [
                            "TEST",
                            "PRODUCTION"
                          ]
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "url",
                        "storefront_id",
                        "payment_mode"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics": {
      "get": {
        "operationId": "analytics_get",
        "summary": "Summarize orders by currency over at most 93 days.",
        "tags": [
          "analytics"
        ],
        "x-pralo-scope": "analytics:read",
        "x-pralo-risk": "READ",
        "x-pralo-mcp-tool": "pralo_get_analytics",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "analytics:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "website_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "from": {
                          "type": "string"
                        },
                        "to": {
                          "type": "string"
                        },
                        "currencies": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "currency": {
                                "type": "string"
                              },
                              "orders": {
                                "type": "number"
                              },
                              "paid_orders": {
                                "type": "number"
                              },
                              "paid_amount": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "currency",
                              "orders",
                              "paid_orders",
                              "paid_amount"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "from",
                        "to",
                        "currencies"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "operationId": "usage_get",
        "summary": "Read the existing Pralo credit wallet and current month usage. No new subscription is created.",
        "tags": [
          "usage"
        ],
        "x-pralo-scope": "usage:read",
        "x-pralo-risk": "READ",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "usage:read"
            ]
          }
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "monthly_included_credits": {
                          "type": "number"
                        },
                        "purchased_credits": {
                          "type": "number"
                        },
                        "used_credits": {
                          "type": "number"
                        },
                        "remaining_credits": {
                          "type": "number"
                        },
                        "reserved_credits": {
                          "type": "number"
                        },
                        "pricing_active": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "monthly_included_credits",
                        "purchased_credits",
                        "used_credits",
                        "remaining_credits",
                        "reserved_credits",
                        "pricing_active"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/logs": {
      "get": {
        "operationId": "logs_list",
        "summary": "Read sanitized developer request logs. Credentials and request bodies are never returned.",
        "tags": [
          "logs"
        ],
        "x-pralo-scope": "logs:read",
        "x-pralo-risk": "READ",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "logs:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "request_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "operation": {
                                "type": "string"
                              },
                              "method": {
                                "type": "string"
                              },
                              "endpoint": {
                                "type": "string"
                              },
                              "status": {
                                "type": "number"
                              },
                              "latency_ms": {
                                "type": "number"
                              },
                              "credits": {
                                "type": "number"
                              },
                              "error_code": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "request_id",
                              "operation",
                              "method",
                              "endpoint",
                              "status",
                              "latency_ms",
                              "credits",
                              "error_code",
                              "created_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/deliveries": {
      "get": {
        "operationId": "webhooks_deliveries",
        "summary": "Read developer webhook delivery receipts without signing material or response bodies.",
        "tags": [
          "webhooks"
        ],
        "x-pralo-scope": "webhooks:read",
        "x-pralo-risk": "READ",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "webhooks:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "event_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "resource_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "webhook_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "event_id": {
                                "type": "string"
                              },
                              "event_type": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "attempt_count": {
                                "type": "integer"
                              },
                              "response_status": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "next_attempt_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "delivered_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "last_error": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "resource_id",
                              "webhook_id",
                              "event_id",
                              "event_type",
                              "status",
                              "attempt_count",
                              "response_status",
                              "next_attempt_at",
                              "delivered_at",
                              "last_error",
                              "created_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/usage/events": {
      "get": {
        "operationId": "usage_events",
        "summary": "Read a shared, sanitized usage view across existing Pralo API, MCP, agent and provider records.",
        "tags": [
          "usage"
        ],
        "x-pralo-scope": "usage:read",
        "x-pralo-risk": "READ",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauth": [
              "usage:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation. Idempotent replays retain the original request_id in the body.",
            "headers": {
              "X-Request-ID": {
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Unix timestamp in seconds when the rate window resets."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "request_id"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "source": {
                                "type": "string"
                              },
                              "operation": {
                                "type": "string"
                              },
                              "quantity": {
                                "type": "number"
                              },
                              "credits": {
                                "type": "number"
                              },
                              "provider_cost": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "provider_currency": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "credential_id": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "developer_app_id": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "created_at": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "id",
                              "source",
                              "operation",
                              "quantity",
                              "credits",
                              "provider_cost",
                              "provider_currency",
                              "credential_id",
                              "developer_app_id",
                              "created_at"
                            ],
                            "additionalProperties": false
                          }
                        },
                        "next_cursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "next_cursor"
                      ],
                      "additionalProperties": false
                    },
                    "request_id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  },
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired or revoked credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient Pralo credits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing permission or required approval; workspace disabled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable in this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Concurrent request, stock or idempotency conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Requested range cannot be processed safely",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached; use Retry-After",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable or uncertain outcome; retain the idempotency key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}
