{
    "openapi": "3.0.3",
    "info": {
        "title": "Orca Scan REST API",
        "description": "REST API for managing barcode inventory sheets, rows, fields, webhooks, triggers, and users.",
        "version": "1.0.0",
        "contact": {
            "name": "Orca Scan",
            "url": "https://orcascan.com"
        }
    },
    "servers": [
        {
            "url": "https://api.orcascan.com/v1",
            "description": "Production"
        }
    ],
    "externalDocs": {
        "description": "Full guide",
        "url": "https://orcascan.com/guides/barcode-scanning-rest-api-f09a21c3"
    },
    "security": [
        {
            "apiKey": []
        }
    ],
    "paths": {
        "/sheets": {
            "get": {
                "summary": "List all sheets",
                "operationId": "listSheets",
                "tags": [
                    "sheets"
                ],
                "responses": {
                    "200": {
                        "description": "Object containing a data array of sheets the authenticated user can access",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "post": {
                "summary": "Create a new sheet",
                "operationId": "createSheet",
                "tags": [
                    "sheets"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "name"
                                ],
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "description": "Sheet name"
                                    },
                                    "description": {
                                        "type": "string"
                                    },
                                    "templateName": {
                                        "type": "string",
                                        "description": "Template to base the sheet on"
                                    },
                                    "includeTestData": {
                                        "type": "boolean",
                                        "description": "Include sample data from the template"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Created sheet wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "409": {
                        "$ref": "#/components/responses/Conflict"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "delete": {
                "summary": "Delete a sheet",
                "operationId": "deleteSheet",
                "tags": [
                    "sheets"
                ],
                "responses": {
                    "200": {
                        "description": "Sheet deleted"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/settings": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "get": {
                "summary": "Get sheet settings",
                "operationId": "getSheetSettings",
                "tags": [
                    "sheets"
                ],
                "responses": {
                    "200": {
                        "description": "Sheet settings wrapped in data envelope",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "put": {
                "summary": "Update sheet settings",
                "operationId": "updateSheetSettings",
                "tags": [
                    "sheets"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Settings updated"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/clear": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "put": {
                "summary": "Clear all rows in a sheet",
                "operationId": "clearSheet",
                "tags": [
                    "sheets"
                ],
                "responses": {
                    "200": {
                        "description": "All rows cleared"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/rename": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "put": {
                "summary": "Rename a sheet",
                "operationId": "renameSheet",
                "tags": [
                    "sheets"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "description": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Sheet renamed"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/fields": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "get": {
                "summary": "List fields (columns)",
                "operationId": "listFields",
                "tags": [
                    "fields"
                ],
                "responses": {
                    "200": {
                        "description": "Object containing a data array of field definitions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "post": {
                "summary": "Add a field",
                "operationId": "addField",
                "tags": [
                    "fields"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/NewField"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Created field wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "409": {
                        "$ref": "#/components/responses/Conflict"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "put": {
                "summary": "Bulk upsert fields",
                "operationId": "bulkUpsertFields",
                "tags": [
                    "fields"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/UpdateField"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Upserted fields wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/fields/{fieldKey}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                },
                {
                    "$ref": "#/components/parameters/fieldKey"
                }
            ],
            "put": {
                "summary": "Update a field",
                "operationId": "updateField",
                "tags": [
                    "fields"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateField"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated field wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "delete": {
                "summary": "Delete a field",
                "operationId": "deleteField",
                "tags": [
                    "fields"
                ],
                "responses": {
                    "200": {
                        "description": "Field deleted"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/rows": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "get": {
                "summary": "List rows",
                "operationId": "listRows",
                "tags": [
                    "rows"
                ],
                "parameters": [
                    {
                        "name": "barcode",
                        "in": "query",
                        "description": "Filter rows by barcode value",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "withTitles",
                        "in": "query",
                        "description": "Use field names as keys instead of internal keys",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Object containing a data array of rows",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "post": {
                "summary": "Add rows (single or bulk)",
                "operationId": "addRows",
                "tags": [
                    "rows"
                ],
                "parameters": [
                    {
                        "name": "partial",
                        "in": "query",
                        "description": "Allow partial row updates (bulk only)",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "withTitles",
                        "in": "query",
                        "description": "Use field names as keys instead of internal keys",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "oneOf": [
                                    {
                                        "type": "object",
                                        "description": "Single row"
                                    },
                                    {
                                        "type": "array",
                                        "description": "Array of rows for bulk upsert",
                                        "items": {
                                            "type": "object"
                                        }
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Created or upserted rows wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "put": {
                "summary": "Bulk update rows",
                "operationId": "bulkUpdateRows",
                "tags": [
                    "rows"
                ],
                "parameters": [
                    {
                        "name": "partial",
                        "in": "query",
                        "description": "Allow partial row updates",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "withTitles",
                        "in": "query",
                        "description": "Use field names as keys instead of internal keys",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated rows wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "delete": {
                "summary": "Bulk delete rows",
                "operationId": "bulkDeleteRows",
                "tags": [
                    "rows"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "pattern": "^[0-9a-fA-F]{24}$"
                                },
                                "description": "Array of row IDs to delete"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Rows deleted"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/rows/count": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "get": {
                "summary": "Get row count",
                "operationId": "countRows",
                "tags": [
                    "rows"
                ],
                "responses": {
                    "200": {
                        "description": "Row count wrapped in data envelope",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "count": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/rows/{rowId}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                },
                {
                    "$ref": "#/components/parameters/rowId"
                }
            ],
            "get": {
                "summary": "Get a single row",
                "operationId": "getRow",
                "tags": [
                    "rows"
                ],
                "parameters": [
                    {
                        "name": "withTitles",
                        "in": "query",
                        "description": "Use field titles as keys instead of internal keys",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Row wrapped in data envelope"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "put": {
                "summary": "Update a row",
                "operationId": "updateRow",
                "tags": [
                    "rows"
                ],
                "parameters": [
                    {
                        "name": "partial",
                        "in": "query",
                        "description": "Allow partial row update without requiring all fields",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "withTitles",
                        "in": "query",
                        "description": "Use field names as keys instead of internal keys",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated row wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "delete": {
                "summary": "Delete a row",
                "operationId": "deleteRow",
                "tags": [
                    "rows"
                ],
                "responses": {
                    "200": {
                        "description": "Row deleted"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/hooks": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "get": {
                "summary": "List webhooks",
                "operationId": "listHooks",
                "tags": [
                    "hooks"
                ],
                "responses": {
                    "200": {
                        "description": "Object containing a data array of webhooks",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "post": {
                "summary": "Create a webhook",
                "operationId": "createHook",
                "tags": [
                    "hooks"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "targetUrl",
                                    "eventName"
                                ],
                                "properties": {
                                    "targetUrl": {
                                        "type": "string",
                                        "format": "uri"
                                    },
                                    "eventName": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Created webhook wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/hooks/{hookId}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                },
                {
                    "$ref": "#/components/parameters/hookId"
                }
            ],
            "get": {
                "summary": "Get a webhook",
                "operationId": "getHook",
                "tags": [
                    "hooks"
                ],
                "responses": {
                    "200": {
                        "description": "Webhook details wrapped in data envelope"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "put": {
                "summary": "Update a webhook",
                "operationId": "updateHook",
                "tags": [
                    "hooks"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "targetUrl",
                                    "eventName"
                                ],
                                "properties": {
                                    "targetUrl": {
                                        "type": "string",
                                        "format": "uri"
                                    },
                                    "eventName": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated webhook wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "delete": {
                "summary": "Delete a webhook",
                "operationId": "deleteHook",
                "tags": [
                    "hooks"
                ],
                "responses": {
                    "200": {
                        "description": "Webhook deleted"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/hook-events": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "get": {
                "summary": "List webhook event types",
                "operationId": "listHookEvents",
                "tags": [
                    "hooks"
                ],
                "responses": {
                    "200": {
                        "description": "Object containing a data array of available event type names",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/triggers": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "get": {
                "summary": "List triggers",
                "operationId": "listTriggers",
                "tags": [
                    "triggers"
                ],
                "responses": {
                    "200": {
                        "description": "Object containing a data array of triggers",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "post": {
                "summary": "Create a trigger",
                "operationId": "createTrigger",
                "tags": [
                    "triggers"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/NewTrigger"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created trigger wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/triggers/{triggerId}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                },
                {
                    "$ref": "#/components/parameters/triggerId"
                }
            ],
            "get": {
                "summary": "Get a trigger",
                "operationId": "getTrigger",
                "tags": [
                    "triggers"
                ],
                "responses": {
                    "200": {
                        "description": "Trigger details wrapped in data envelope"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "put": {
                "summary": "Update a trigger",
                "operationId": "updateTrigger",
                "tags": [
                    "triggers"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/UpdateTrigger"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated trigger wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "delete": {
                "summary": "Delete a trigger",
                "operationId": "deleteTrigger",
                "tags": [
                    "triggers"
                ],
                "responses": {
                    "200": {
                        "description": "Trigger deleted"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/history": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "get": {
                "summary": "Get sheet history",
                "operationId": "getSheetHistory",
                "tags": [
                    "history"
                ],
                "responses": {
                    "200": {
                        "description": "Object containing a data array of history entries",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/{rowId}/history": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                },
                {
                    "$ref": "#/components/parameters/rowId"
                }
            ],
            "get": {
                "summary": "Get row history",
                "operationId": "getRowHistory",
                "tags": [
                    "history"
                ],
                "responses": {
                    "200": {
                        "description": "Object containing a data array of history entries for the row",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/users": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                }
            ],
            "get": {
                "summary": "List users",
                "operationId": "listUsers",
                "tags": [
                    "users"
                ],
                "responses": {
                    "200": {
                        "description": "Object containing a data array of users with access to the sheet",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/DataEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "post": {
                "summary": "Add a user to a sheet",
                "operationId": "addUser",
                "tags": [
                    "users"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "canUpdate": {
                                        "type": "boolean"
                                    },
                                    "canDelete": {
                                        "type": "boolean"
                                    },
                                    "canExport": {
                                        "type": "boolean"
                                    },
                                    "canAdmin": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Added user wrapped in data envelope"
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        },
        "/sheets/{sheetId}/users/{userId}": {
            "parameters": [
                {
                    "$ref": "#/components/parameters/sheetId"
                },
                {
                    "$ref": "#/components/parameters/userId"
                }
            ],
            "put": {
                "summary": "Update user permissions",
                "operationId": "updateUser",
                "tags": [
                    "users"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "email"
                                ],
                                "properties": {
                                    "email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "canUpdate": {
                                        "type": "boolean"
                                    },
                                    "canDelete": {
                                        "type": "boolean"
                                    },
                                    "canExport": {
                                        "type": "boolean"
                                    },
                                    "canAdmin": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Updated user wrapped in data envelope"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            },
            "delete": {
                "summary": "Remove a user from a sheet",
                "operationId": "removeUser",
                "tags": [
                    "users"
                ],
                "responses": {
                    "200": {
                        "description": "User removed"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Error": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "integer"
                    },
                    "error": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    }
                }
            },
            "DataEnvelope": {
                "type": "object",
                "description": "Standard response wrapper",
                "properties": {
                    "data": {
                        "description": "Response payload (object or array depending on endpoint)"
                    }
                }
            },
            "FieldProperties": {
                "type": "object",
                "description": "Writable field configuration properties",
                "properties": {
                    "label": {
                        "type": "string",
                        "description": "Field display name"
                    },
                    "format": {
                        "type": "string",
                        "description": "Field data type",
                        "enum": [
                            "text",
                            "barcode",
                            "number",
                            "number (auto increase on scan)",
                            "number (auto decrease on scan)",
                            "date",
                            "date (automatic)",
                            "date time",
                            "date time (automatic)",
                            "time",
                            "email",
                            "gps location",
                            "gps location (automatic)",
                            "true/false",
                            "currency",
                            "drop-down list",
                            "formula",
                            "signature",
                            "unique id",
                            "photo",
                            "attachment",
                            "url",
                            "created by",
                            "created date",
                            "last modified by",
                            "last modified date"
                        ]
                    },
                    "default": {
                        "type": "string",
                        "description": "Default value for new rows"
                    },
                    "listOptions": {
                        "description": "Options for drop-down list fields",
                        "oneOf": [
                            {
                                "type": "string"
                            },
                            {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        ]
                    },
                    "multiSelect": {
                        "type": "boolean",
                        "description": "Allow multiple selections for drop-down list fields"
                    },
                    "formula": {
                        "type": "string",
                        "description": "Formula expression for formula fields"
                    },
                    "currencyType": {
                        "type": "string",
                        "description": "3-letter currency code for currency fields",
                        "minLength": 3,
                        "maxLength": 3
                    },
                    "locked": {
                        "type": "boolean",
                        "description": "Prevent field from being edited"
                    },
                    "minLength": {
                        "type": "integer",
                        "description": "Minimum text length"
                    },
                    "maxLength": {
                        "type": "integer",
                        "description": "Maximum text length"
                    },
                    "minimum": {
                        "type": "number",
                        "description": "Minimum numeric value"
                    },
                    "maximum": {
                        "type": "number",
                        "description": "Maximum numeric value"
                    },
                    "placeholder": {
                        "type": "string",
                        "description": "Placeholder text shown when field is empty"
                    },
                    "prefix": {
                        "type": "string",
                        "description": "Text prefix displayed before the value"
                    },
                    "suffix": {
                        "type": "string",
                        "description": "Text suffix displayed after the value"
                    },
                    "length": {
                        "type": "integer",
                        "description": "Fixed length for unique ID fields"
                    },
                    "required": {
                        "type": "boolean",
                        "description": "Whether the field must have a value"
                    },
                    "autofocus": {
                        "type": "boolean",
                        "description": "Automatically focus this field on mobile"
                    },
                    "autoselect": {
                        "type": "boolean",
                        "description": "Automatically select field content on focus"
                    },
                    "emptyOnEdit": {
                        "type": "boolean",
                        "description": "Clear field value when editing a row"
                    },
                    "emptyOnScan": {
                        "type": "boolean",
                        "description": "Clear field value when scanning a barcode"
                    },
                    "hiddenMobile": {
                        "type": "boolean",
                        "description": "Hide field on mobile devices"
                    },
                    "hiddenWeb": {
                        "type": "boolean",
                        "description": "Hide field in web interface"
                    },
                    "readonlyWeb": {
                        "type": "boolean",
                        "description": "Make field read-only in web interface"
                    },
                    "readonlyMobile": {
                        "type": "boolean",
                        "description": "Make field read-only on mobile devices"
                    },
                    "useInMobileSearch": {
                        "type": "boolean",
                        "description": "Include field in mobile search results"
                    },
                    "useValueInList": {
                        "type": "boolean",
                        "description": "Show field value in mobile list view"
                    },
                    "index": {
                        "type": "integer",
                        "description": "Display order position"
                    }
                }
            },
            "NewField": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/FieldProperties"
                    },
                    {
                        "type": "object",
                        "required": [
                            "label",
                            "format"
                        ]
                    }
                ]
            },
            "UpdateField": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/FieldProperties"
                    },
                    {
                        "type": "object",
                        "properties": {
                            "key": {
                                "type": "string",
                                "description": "Field key identifier (used in bulk upsert to target existing fields)"
                            }
                        }
                    }
                ]
            },
            "TriggerProperties": {
                "type": "object",
                "description": "Writable trigger configuration properties",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Trigger name"
                    },
                    "conditionField": {
                        "type": "string",
                        "description": "Field title to evaluate"
                    },
                    "conditionType": {
                        "type": "string",
                        "description": "Condition operator",
                        "enum": [
                            "is empty",
                            "is not empty",
                            "contains",
                            "does not contain",
                            "starts with",
                            "does not start with",
                            "ends with",
                            "does not end with",
                            "equals",
                            "does not equal",
                            "is less than",
                            "is greater than",
                            "matches regex",
                            "does not match regex",
                            "contains GS1 AI",
                            "exists in",
                            "does not exist in"
                        ]
                    },
                    "conditionValue": {
                        "type": "string",
                        "description": "Value to compare against"
                    },
                    "actionType": {
                        "type": "string",
                        "description": "Action to perform when condition is met",
                        "enum": [
                            "show",
                            "hide",
                            "set value",
                            "clear value",
                            "set readonly",
                            "clear readonly",
                            "set required",
                            "clear required",
                            "notify me",
                            "play sound",
                            "move row",
                            "copy row"
                        ]
                    },
                    "actionField": {
                        "type": "string",
                        "description": "Target field for the action"
                    },
                    "actionValue": {
                        "type": "string",
                        "description": "Value to set when action is 'set value'"
                    },
                    "notifyMethod": {
                        "type": "string",
                        "description": "Notification delivery method",
                        "enum": [
                            "email",
                            "in app notification",
                            "in app dialog"
                        ]
                    },
                    "notifyEmails": {
                        "type": "string",
                        "description": "Comma-separated email addresses for notifications"
                    },
                    "notifyType": {
                        "type": "string",
                        "description": "Notification severity",
                        "enum": [
                            "success",
                            "warning",
                            "error"
                        ]
                    },
                    "soundType": {
                        "type": "string",
                        "description": "Sound to play",
                        "enum": [
                            "success",
                            "warning",
                            "error"
                        ]
                    },
                    "toSheet": {
                        "type": "string",
                        "description": "Target sheet for move/copy row actions"
                    },
                    "enabled": {
                        "type": "boolean",
                        "description": "Whether the trigger is active"
                    }
                }
            },
            "NewTrigger": {
                "allOf": [
                    {
                        "$ref": "#/components/schemas/TriggerProperties"
                    },
                    {
                        "type": "object",
                        "required": [
                            "name",
                            "conditionField",
                            "conditionType",
                            "actionType"
                        ]
                    }
                ]
            },
            "UpdateTrigger": {
                "$ref": "#/components/schemas/TriggerProperties"
            }
        },
        "securitySchemes": {
            "apiKey": {
                "type": "http",
                "scheme": "bearer",
                "description": "API key in the format orca_XXXXXXXXXXXXXXXXXXXXXXXXXXX"
            }
        },
        "parameters": {
            "sheetId": {
                "name": "sheetId",
                "in": "path",
                "required": true,
                "description": "24-character hex sheet identifier",
                "schema": {
                    "type": "string",
                    "pattern": "^[0-9a-fA-F]{24}$"
                }
            },
            "rowId": {
                "name": "rowId",
                "in": "path",
                "required": true,
                "description": "24-character hex row identifier",
                "schema": {
                    "type": "string",
                    "pattern": "^[0-9a-fA-F]{24}$"
                }
            },
            "hookId": {
                "name": "hookId",
                "in": "path",
                "required": true,
                "description": "24-character hex webhook identifier",
                "schema": {
                    "type": "string",
                    "pattern": "^[0-9a-fA-F]{24}$"
                }
            },
            "triggerId": {
                "name": "triggerId",
                "in": "path",
                "required": true,
                "description": "24-character hex trigger identifier",
                "schema": {
                    "type": "string",
                    "pattern": "^[0-9a-fA-F]{24}$"
                }
            },
            "userId": {
                "name": "userId",
                "in": "path",
                "required": true,
                "description": "24-character hex user identifier",
                "schema": {
                    "type": "string",
                    "pattern": "^[0-9a-fA-F]{24}$"
                }
            },
            "fieldKey": {
                "name": "fieldKey",
                "in": "path",
                "required": true,
                "description": "Field key identifier",
                "schema": {
                    "type": "string",
                    "pattern": "^[^/]+$"
                }
            }
        },
        "responses": {
            "BadRequest": {
                "description": "Invalid request",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Unauthorized": {
                "description": "Missing or invalid API key",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "Insufficient permissions",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "NotFound": {
                "description": "Resource not found",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Conflict": {
                "description": "Resource already exists",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "TooManyRequests": {
                "description": "Rate limit exceeded (15 requests/sec per IP). Retry after the specified delay.",
                "headers": {
                    "Retry-After": {
                        "description": "Seconds to wait before retrying",
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        }
    }
}