{ "openapi": "3.1.0", "x-stoplight": { "id": "qiz1rcfqd2jy6" }, "info": { "title": "NocoDB v3", "version": "", "description": "NocoDB API Documentation" }, "x-tagGroups": [ { "name": "Meta APIs", "tags": [ "Workspaces", "Bases", "Tables", "Views", "Fields", "View Filters", "View Sorts", "Scripts", "Dashboards", "Documents", "Hooks", "Comments" ] }, { "name": "Collaboration APIs", "tags": [ "Workspace Members", "Base Members" ] } ], "servers": [ { "url": "https://app.nocodb.com" } ], "paths": { "/api/v3/meta/workspaces": { "get": { "summary": "List workspaces", "operationId": "workspace-list", "description": "Retrieve a list of all workspaces accessible to the user.\n\n**Note**: Workspace APIs are available only with self-hosted **Enterprise** plans and cloud-hosted **Enterprise** plans.", "tags": [ "Workspaces" ], "responses": { "200": { "description": "Workspaces retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceV3ListResponse" }, "examples": { "Workspaces List": { "value": { "list": [ { "id": "w6dw3fo0", "title": "My Workspace", "org_id": "org123", "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-16T06:04:18.000Z" } ] } } } } } }, "400": { "description": "Bad request." }, "500": { "description": "The server encountered an unexpected error while processing the request." } } }, "post": { "summary": "Create workspace", "operationId": "workspace-create", "description": "Create a new workspace with the specified title and optional organization ID.\n\n**Note**: Workspace APIs are available only with self-hosted **Enterprise** plans and cloud-hosted **Enterprise** plans.", "tags": [ "Workspaces" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceV3Create" }, "examples": { "Create Workspace": { "value": { "title": "New Workspace", "org_id": "org123" } }, "Create Workspace (On-prem)": { "value": { "title": "New Workspace" } } } } } }, "responses": { "200": { "description": "Workspace created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceV3" }, "examples": { "Created Workspace": { "value": { "id": "w7xyz123", "title": "New Workspace", "org_id": "org123", "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-16T06:04:18.000Z" } } } } } }, "400": { "description": "Bad request." }, "500": { "description": "The server encountered an unexpected error while processing the request." } } } }, "/api/v3/meta/workspaces/{workspaceId}": { "get": { "summary": "Get workspace", "operationId": "workspace-read", "description": "Retrieve details of a specific workspace.\n\n**Note**: Workspace APIs are available only with self-hosted **Enterprise** plans and cloud-hosted **Enterprise** plans.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the workspace." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Include additional data. Use 'members' to include workspace member information.", "example": "members" } ], "responses": { "200": { "description": "Workspace retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceV3" }, "examples": { "Workspace": { "value": { "id": "w6dw3fo0", "title": "My Workspace", "org_id": "org123", "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-16T06:04:18.000Z" } } } } } }, "404": { "description": "Workspace not found." }, "500": { "description": "The server encountered an unexpected error while processing the request." } } }, "patch": { "summary": "Update workspace", "operationId": "workspace-update", "description": "Update workspace details.\n\n**Note**: Workspace APIs are available only with self-hosted **Enterprise** plans and cloud-hosted **Enterprise** plans.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the workspace." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceV3Update" }, "examples": { "Update Workspace": { "value": { "title": "Updated Workspace Title" } } } } } }, "responses": { "200": { "description": "Workspace updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceV3" }, "examples": { "Updated Workspace": { "value": { "id": "w6dw3fo0", "title": "Updated Workspace Title", "org_id": "org123", "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-17T06:04:18.000Z" } } } } } }, "400": { "description": "Bad request." }, "404": { "description": "Workspace not found." }, "500": { "description": "The server encountered an unexpected error while processing the request." } } }, "delete": { "summary": "Delete workspace", "operationId": "workspace-delete", "description": "Delete a workspace.\n\n**Note**: Workspace APIs are available only with self-hosted **Enterprise** plans and cloud-hosted **Enterprise** plans.", "tags": [ "Workspaces" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the workspace." } ], "responses": { "200": { "description": "Workspace deleted successfully." }, "404": { "description": "Workspace not found." }, "500": { "description": "The server encountered an unexpected error while processing the request." } } } }, "/api/v3/meta/workspaces/{workspaceId}/bases": { "get": { "summary": "List bases", "operationId": "bases-list", "description": "Retrieve a list of bases associated with a specific workspace.", "tags": [ "Bases" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the workspace." } ], "responses": { "200": { "description": "The request was successful, and a list of bases is returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Base" }, "description": "List of bases." } } }, "examples": { "Example 1": { "value": { "list": [ { "id": "pgfqcp0ocloo1j3", "title": "Getting Started", "meta": { "icon_color": "#36BFFF" }, "created_at": "2025-01-16 06:04:18+00:00", "updated_at": "2025-01-16 06:04:18+00:00", "workspace_id": "w6dw3fo0" }, { "id": "p1go4ju5jcwqf8v", "title": "Base2", "meta": { "icon_color": "#36BFFF" }, "created_at": "2025-01-16 06:04:48+00:00", "updated_at": "2025-01-16 06:04:48+00:00", "workspace_id": "w6dw3fo0" }, { "id": "pho1grz3alkye0t", "title": "Base3", "meta": { "icon_color": "#FA8231" }, "created_at": "2025-01-16 06:04:52+00:00", "updated_at": "2025-01-16 06:04:52+00:00", "workspace_id": "w6dw3fo0" } ] } } } } } }, "500": { "description": "The server encountered an unexpected error while processing the request." } } }, "post": { "summary": "Create base", "description": "Create a new base in a specified workspace. The request requires the workspace identifier in the path and base details in the request body.", "operationId": "base-create", "tags": [ "Bases" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the workspace where the base will be created." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseCreate" }, "examples": { "Example 1": { "value": { "title": "New Base", "meta": { "icon_color": "#36BFFF" } } } } } } }, "responses": { "200": { "description": "Base was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base" }, "examples": { "Example 1": { "value": { "id": "p7nwavd2gcdkzvd", "title": "New Base", "meta": { "icon_color": "#36BFFF" }, "created_at": "2024-12-28 09:52:29+00:00", "updated_at": "2024-12-28 09:52:29+00:00", "workspace_id": "w6dw3fo0" } } } } } }, "400": { "description": "Invalid request body." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/workspaces/{workspaceId}?include[]=members": { "get": { "summary": "List workspace members", "operationId": "workspace-members-read", "description": "Retrieve details of a specific workspace, including its members.\n\nNotes:\n- To include member details, use the query parameter `include[]=members`.\n- Workspace collaboration APIs are available only with self-hosted Enterprise plans and cloud-hosted Enterprise plans.", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the workspace." }, { "name": "include", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "enum": [ "members" ] }, { "type": "array", "items": { "type": "string", "enum": [ "members" ] } } ] }, "description": "Include additional data. Use 'members' to include workspace member information.", "example": "members" } ], "responses": { "200": { "description": "Workspace metadata retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceWithMembers" }, "examples": { "Workspace with Members": { "value": { "id": "w6dw3fo0", "title": "My Workspace", "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-16T06:04:18.000Z", "individual_members": { "workspace_members": [ { "email": "user@example.com", "user_id": "usrL2PNC5o3H4lBEi", "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-16T06:04:18.000Z", "workspace_role": "workspace-level-owner" } ] } } } } } } }, "404": { "description": "Workspace not found." }, "500": { "description": "The server encountered an unexpected error while processing the request." } } } }, "/api/v3/meta/workspaces/{workspaceId}/members": { "post": { "summary": "Add workspace members", "description": "Add new members to a workspace. The request requires the workspace identifier in the path and member details in the request body.\n\nNotes: Workspace collaboration APIs are available only with self-hosted Enterprise plans and cloud-hosted Enterprise plans.", "operationId": "workspace-members-invite", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the workspace where the members will be added." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUserCreate" }, "examples": { "Example 1": { "value": [ { "email": "user@example.com", "workspace_role": "workspace-level-viewer" } ] }, "Example 2": { "value": [ { "email": "user1@example.com", "workspace_role": "workspace-level-editor" }, { "email": "user2@example.com", "workspace_role": "workspace-level-viewer" } ] } } } } }, "responses": { "200": { "description": "Workspace members were added successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceUser" } } } } }, "400": { "description": "Invalid request body." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update workspace members", "description": "Update roles of existing workspace members. The request requires the workspace identifier in the path and member update details in the request body.\n\nNotes: Workspace collaboration APIs are available only with self-hosted Enterprise plans and cloud-hosted Enterprise plans.", "operationId": "workspace-members-update", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the workspace where the members will be updated." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUserUpdate" }, "examples": { "Example 1": { "value": [ { "user_id": "user123", "workspace_role": "workspace-level-editor" } ] }, "Example 2": { "value": [ { "user_id": "user123", "workspace_role": "workspace-level-editor" }, { "user_id": "user456", "workspace_role": "workspace-level-viewer" } ] } } } } }, "responses": { "200": { "description": "Workspace members were updated successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceUser" } } } } }, "400": { "description": "Invalid request body." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete workspace members", "description": "Remove members from a workspace. The request requires the workspace identifier in the path and member details in the request body.\n\nNotes: Workspace collaboration APIs are available only with self-hosted Enterprise plans and cloud-hosted Enterprise plans.", "operationId": "workspace-members-delete", "tags": [ "Workspace Members" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the workspace where the members will be removed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceUserDelete" }, "examples": { "Example 1": { "value": [ { "user_id": "user123" } ] }, "Example 2": { "value": [ { "user_id": "user123" }, { "user_id": "user456" } ] } } } } }, "responses": { "200": { "description": "Workspace members were removed successfully." }, "400": { "description": "Invalid request body." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}": { "get": { "summary": "Get base meta", "description": "Retrieve meta details of a specific base using its unique identifier.", "operationId": "base-read", "tags": [ "Bases" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the base." } ], "responses": { "200": { "description": "Base meta was retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base" }, "examples": { "Example 1": { "value": { "id": "p7nwavd2gcdkzvd", "title": "Getting Started", "meta": { "icon_color": "#36BFFF" }, "created_at": "2024-12-28 09:52:29+00:00", "updated_at": "2024-12-28 09:52:30+00:00", "workspace_id": "w6dw3fo0", "sources": [ { "id": "biv0qz3hgg191s5", "title": "jango_fett", "type": "pg", "is_schema_readonly": false, "is_data_readonly": false, "integration_id": "biv0qz3hgg191s5" } ] } } } } } }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update base", "description": "Update properties of a specific base. You can modify fields such as the title and metadata of the base. The baseId parameter identifies the base to be updated, and the new details must be provided in the request body. At least one of title or meta must be provided.", "operationId": "base-update", "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "tags": [ "Bases" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseUpdate" }, "examples": { "Example 1": { "value": { "title": "Updated Base Title", "meta": { "icon_color": "#36BFFF" } } } } } } }, "responses": { "200": { "description": "The base was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Base" }, "examples": { "Example 1": { "value": { "id": "p7nwavd2gcdkzvd", "title": "Updated Base Title", "meta": { "icon_color": "#36BFFF" }, "created_at": "2024-12-28 09:52:29+00:00", "updated_at": "2024-12-28 09:52:29+00:00", "workspace_id": "w6dw3fo0" } } } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete base", "description": "Delete a specific base using its unique identifier. Once deleted, the base and its associated data cannot be recovered.", "operationId": "base-delete", "tags": [ "Bases" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "responses": { "204": { "description": "Base was deleted." }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{base_id}/tables": { "get": { "summary": "List tables", "description": "Retrieve list of all tables within the specified base.", "operationId": "tables-list", "tags": [ "Tables" ], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "responses": { "200": { "description": "List of tables retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableList" }, "examples": { "Example 1": { "value": { "list": [ { "id": "mq31p5ngbwj5o7u", "title": "Features", "description": "Sample table description.", "base_id": "pgfqcp0ocloo1j3", "workspace_id": "w6dw3fo0" }, { "id": "mwmlsgaek7932m4", "title": "Table-1", "meta": { "icon": "🚞" }, "base_id": "pgfqcp0ocloo1j3", "workspace_id": "w6dw3fo0" }, { "id": "m56zsedzrpz6p9w", "title": "Table-2", "meta": { "icon": "🏞️" }, "base_id": "pgfqcp0ocloo1j3", "workspace_id": "w6dw3fo0" } ] } } } } } }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } }, "post": { "summary": "Create table", "description": "Create a new table within the specified base by providing the required table details in the request body.", "operationId": "table-create", "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "tags": [ "Tables" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableCreate" }, "examples": { "Example 1": { "value": { "title": "Sample Table20", "description": "Sample Description", "fields": [ { "title": "SingleLineText", "type": "SingleLineText", "default_value": "Default Title" }, { "title": "LongText", "type": "LongText", "default_value": "Default Description" }, { "title": "RichText", "type": "LongText", "default_value": "**Default Description**", "options": { "rich_text": true } }, { "title": "UniqueEmail", "type": "Email", "unique": true }, { "title": "Email", "type": "Email", "default_value": "user@nocodb.com", "options": { "validation": true } }, { "title": "URL", "type": "URL", "default_value": "https://nocodb.com", "options": { "validation": true } }, { "title": "Phone", "type": "PhoneNumber", "default_value": "1234567890", "options": { "validation": true } }, { "title": "Number", "type": "Number", "default_value": "34", "options": { "separator": "comma_period" } }, { "title": "Decimal", "type": "Decimal", "default_value": "34.56", "options": { "precision": 2 } }, { "title": "Currency", "type": "Currency", "default_value": "34.56", "options": { "locale": "en-US", "code": "USD" } }, { "title": "Percent", "type": "Percent", "default_value": "0.34", "options": { "show_as_progress": true } }, { "title": "Date", "type": "Date", "default_value": "2021-09-30", "options": { "date_format": "YYYY-MM-DD" } }, { "title": "DateTime", "type": "DateTime", "default_value": "2021-09-30 12:34:56", "options": { "date_format": "YYYY-MM-DD HH:mm:ss", "time_format": "HH:mm:ss", "12hr_format": true } }, { "title": "SingleSelect", "type": "SingleSelect", "default_value": "Option 1", "options": { "choices": [ { "title": "Option 1", "color": "#36BFFF" }, { "title": "Option 2", "color": "#36BFFF" } ] } }, { "title": "MultiSelect", "type": "MultiSelect", "default_value": "[\"Option 1\"]", "options": { "choices": [ { "title": "Option 1", "color": "#36BFFF" }, { "title": "Option 2", "color": "#36BFFF" } ] } }, { "title": "Checkbox", "type": "Checkbox", "default_value": true, "options": { "icon": "heart", "color": "#36BFFF" } }, { "title": "Rating", "type": "Rating", "default_value": "3", "options": { "icon": "heart", "max_value": 5, "color": "#36BFFF" } }, { "title": "Attachment", "type": "Attachment" }, { "title": "JSON", "type": "JSON", "default_value": "{\"key\": \"value\"}" }, { "title": "User", "type": "User", "default_value": "uskfsbdfved8c03z", "options": { "allow_multiple_users": true } }, { "title": "CreatedTime", "type": "CreatedTime" }, { "title": "CreatedBy", "type": "CreatedBy" }, { "title": "UpdatedBy", "type": "LastModifiedBy" }, { "title": "UpdatedTime", "type": "LastModifiedTime" } ] } } } } } }, "responses": { "200": { "description": "Table created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" }, "examples": { "Example 1": { "value": { "id": "mo0tpvd1hjvfbrx", "title": "Sample Table", "description": "Sample Description", "source_id": "bzyr9k9ui4oudwx", "base_id": "p13yxf5plzg73jm", "workspace_id": "wsdkr9ub", "display_field_id": "c455mde7px2yidt", "fields": [ { "id": "c455mde7px2yidt", "title": "SingleLineText", "type": "SingleLineText", "default_value": "Default Title" }, { "id": "c9zh8dmi7710mao", "title": "LongText", "type": "LongText", "default_value": "Default Description" }, { "id": "c57o8n0cbyss84l", "title": "RichText", "type": "LongText", "default_value": "**Default Description**", "options": { "rich_text": true } }, { "id": "cnl62kaut6jp5rg", "title": "Email", "type": "Email", "default_value": "user@nocodb.com", "options": { "validation": true } }, { "id": "cx4mpq7zm4offr8", "title": "URL", "type": "URL", "default_value": "https://nocodb.com", "options": { "validation": true } }, { "id": "cx7i90tmjjbh50g", "title": "Phone", "type": "PhoneNumber", "default_value": "1234567890", "options": { "validation": true } }, { "id": "chcb0o99ricceek", "title": "Number", "type": "Number", "default_value": "34", "options": { "separator": "comma_period" } }, { "id": "csumykirz5i02pg", "title": "Decimal", "type": "Decimal", "default_value": "34.56", "options": { "precision": 2 } }, { "id": "cs1tvrdevhwf4r2", "title": "Currency", "type": "Currency", "default_value": "34.56", "options": { "locale": "en-US", "code": "USD" } }, { "id": "crpqkxsq8d1ljgz", "title": "Percent", "type": "Percent", "default_value": "0.34", "options": { "show_as_progress": true } }, { "id": "crnzx3dtlnjjr5z", "title": "Date", "type": "Date", "default_value": "2021-09-30", "options": { "date_format": "YYYY-MM-DD" } }, { "id": "c26ypextdeug3qd", "title": "DateTime", "type": "DateTime", "default_value": "2021-09-30 12:34:56", "options": { "date_format": "YYYY-MM-DD HH:mm:ss", "time_format": "HH:mm:ss", "12hr_format": true } }, { "id": "cyllf65uowcvw1b", "title": "SingleSelect", "type": "SingleSelect", "default_value": "Option 1", "options": { "choices": [ { "title": "Option 1", "color": "#36BFFF", "id": "spd7exnmjz5uch8" }, { "title": "Option 2", "color": "#36BFFF", "id": "sytp5rjfte78p8k" } ] } }, { "id": "clhlbmjw6dpz9ts", "title": "MultiSelect", "type": "MultiSelect", "default_value": "[\"Option 1\"]", "options": { "choices": [ { "title": "Option 1", "color": "#36BFFF", "id": "ssig2048lvr9puw" }, { "title": "Option 2", "color": "#36BFFF", "id": "sz7etgbnhm84e9w" } ] } }, { "id": "c86vpwa0qzexf8i", "title": "Checkbox", "type": "Checkbox", "default_value": "true", "options": { "color": "#36BFFF", "icon": "heart" } }, { "id": "c6h2p5nmlmynbiv", "title": "Rating", "type": "Rating", "default_value": "3", "options": { "max_value": 5, "color": "#36BFFF", "icon": "heart" } }, { "id": "cqh7kupxqaw7itc", "title": "Attachment", "type": "Attachment" }, { "id": "cp1d7w6surl8juh", "title": "JSON", "type": "JSON", "default_value": "{\"key\": \"value\"}" }, { "id": "cebdv0v3uy7tyiy", "title": "User", "type": "User", "default_value": "uskfsbdfved8c03z", "options": { "allow_multiple_users": true } }, { "id": "cb4vptiuveysb5a", "title": "Links", "type": "Links", "options": { "relation_type": "mm", "related_table_id": "mnkgbmqwkls36fg" } }, { "id": "cavokt1gde5dy2m", "title": "id", "type": "ID" }, { "id": "csiwamkqrm08slv", "title": "CreatedTime", "type": "CreatedTime" }, { "id": "cczd61fh2m0mn8a", "title": "CreatedBy", "type": "CreatedBy" }, { "id": "chshjlwe59glff7", "title": "UpdatedBy", "type": "LastModifiedBy" }, { "id": "ctlyu6sbs77whvj", "title": "UpdatedTime", "type": "LastModifiedTime" } ], "views": [ { "id": "vwuke35pn7bcoqmb", "title": "Sample Table", "view_type": "grid" } ] } } } } } }, "400": { "description": "Invalid request body." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/tables/{tableId}": { "get": { "summary": "Get table schema", "description": "Retrieve the details of a specific table.", "operationId": "table-read", "tags": [ "Tables" ], "parameters": [ { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." }, { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "responses": { "200": { "description": "Table details are retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" }, "examples": { "Example 1": { "value": { "id": "mo0tpvd1hjvfbrx", "title": "Sample Table", "description": "Sample Description", "source_id": "bzyr9k9ui4oudwx", "base_id": "p13yxf5plzg73jm", "workspace_id": "wsdkr9ub", "display_field_id": "c455mde7px2yidt", "fields": [ { "id": "c455mde7px2yidt", "title": "SingleLineText", "type": "SingleLineText", "default_value": "Default Title" }, { "id": "c9zh8dmi7710mao", "title": "LongText", "type": "LongText", "default_value": "Default Description" }, { "id": "c57o8n0cbyss84l", "title": "RichText", "type": "LongText", "default_value": "**Default Description**", "options": { "rich_text": true } }, { "id": "cnl62kaut6jp5rg", "title": "Email", "type": "Email", "default_value": "user@nocodb.com", "options": { "validation": true } }, { "id": "cx4mpq7zm4offr8", "title": "URL", "type": "URL", "default_value": "https://nocodb.com", "options": { "validation": true } }, { "id": "cx7i90tmjjbh50g", "title": "Phone", "type": "PhoneNumber", "default_value": "1234567890", "options": { "validation": true } }, { "id": "chcb0o99ricceek", "title": "Number", "type": "Number", "default_value": "34", "options": { "separator": "comma_period" } }, { "id": "csumykirz5i02pg", "title": "Decimal", "type": "Decimal", "default_value": "34.56", "options": { "precision": 2 } }, { "id": "cs1tvrdevhwf4r2", "title": "Currency", "type": "Currency", "default_value": "34.56", "options": { "locale": "en-US", "code": "USD" } }, { "id": "crpqkxsq8d1ljgz", "title": "Percent", "type": "Percent", "default_value": "0.34", "options": { "show_as_progress": true } }, { "id": "crnzx3dtlnjjr5z", "title": "Date", "type": "Date", "default_value": "2021-09-30", "options": { "date_format": "YYYY-MM-DD" } }, { "id": "c26ypextdeug3qd", "title": "DateTime", "type": "DateTime", "default_value": "2021-09-30 12:34:56", "options": { "date_format": "YYYY-MM-DD HH:mm:ss", "time_format": "HH:mm:ss", "12hr_format": true } }, { "id": "cyllf65uowcvw1b", "title": "SingleSelect", "type": "SingleSelect", "default_value": "Option 1", "options": { "choices": [ { "title": "Option 1", "color": "#36BFFF", "id": "spd7exnmjz5uch8" }, { "title": "Option 2", "color": "#36BFFF", "id": "sytp5rjfte78p8k" } ] } }, { "id": "clhlbmjw6dpz9ts", "title": "MultiSelect", "type": "MultiSelect", "default_value": "[\"Option 1\"]", "options": { "choices": [ { "title": "Option 1", "color": "#36BFFF", "id": "ssig2048lvr9puw" }, { "title": "Option 2", "color": "#36BFFF", "id": "sz7etgbnhm84e9w" } ] } }, { "id": "c86vpwa0qzexf8i", "title": "Checkbox", "type": "Checkbox", "default_value": "true", "options": { "color": "#36BFFF", "icon": "heart" } }, { "id": "c6h2p5nmlmynbiv", "title": "Rating", "type": "Rating", "default_value": "3", "options": { "max_value": 5, "color": "#36BFFF", "icon": "heart" } }, { "id": "cqh7kupxqaw7itc", "title": "Attachment", "type": "Attachment" }, { "id": "cp1d7w6surl8juh", "title": "JSON", "type": "JSON", "default_value": "{\"key\": \"value\"}" }, { "id": "cebdv0v3uy7tyiy", "title": "User", "type": "User", "default_value": "uskfsbdfved8c03z", "options": { "allow_multiple_users": true } }, { "id": "cb4vptiuveysb5a", "title": "Links", "type": "Links", "options": { "relation_type": "mm", "related_table_id": "mnkgbmqwkls36fg" } }, { "id": "cavokt1gde5dy2m", "title": "id", "type": "ID" }, { "id": "csiwamkqrm08slv", "title": "CreatedTime", "type": "CreatedTime" }, { "id": "cczd61fh2m0mn8a", "title": "CreatedBy", "type": "CreatedBy" }, { "id": "chshjlwe59glff7", "title": "UpdatedBy", "type": "LastModifiedBy" }, { "id": "ctlyu6sbs77whvj", "title": "UpdatedTime", "type": "LastModifiedTime" } ], "views": [ { "id": "vwuke35pn7bcoqmb", "title": "Sample Table", "view_type": "grid" } ] } } } } } }, "404": { "description": "Table not found." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update table", "description": "Update the details of a specific table.", "operationId": "table-update", "tags": [ "Tables" ], "parameters": [ { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." }, { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TableUpdate" }, "examples": { "Example 1": { "value": { "title": "Updated Table Title", "description": "Updated Description", "display_field_id": "c455mde7px2yidt", "meta": { "icon": "🚞" } } } } } } }, "responses": { "200": { "description": "Table meta updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Table" }, "examples": { "Example 1": { "value": { "id": "m0nibecfkcfsz2x", "title": "Features", "meta": { "icon": "🚞" }, "source_id": "bbtx6pvj7b8yszy", "base_id": "pn9mmowpquxj60w", "workspace_id": "w6wqiisd", "views": [ { "id": "vwuke35pn7bcoqmb", "title": "Features", "view_type": "grid" } ], "display_field_id": "cb51p6e2r4gpxpv", "fields": [ { "id": "cz0jslmqdvcv68n", "title": "Id", "type": "ID" }, { "id": "cb51p6e2r4gpxpv", "title": "Title", "type": "SingleLineText" } ] } } } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "Table not found." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete table", "description": "Delete a specific table.", "operationId": "table-delete", "tags": [ "Tables" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." } ], "responses": { "204": { "description": "Table deleted successfully." }, "404": { "description": "Table not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/tables/{tableId}/views": { "get": { "summary": "List views", "operationId": "views-list", "tags": [ "Views" ], "description": "Retrieve a list of all views for a specific table.\n\n**Note**: View APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." } ], "responses": { "200": { "description": "List of views retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewList" }, "examples": { "Example 1": { "value": { "list": [ { "id": "vwpwk5v4urgbu85g", "table_id": "mrc5unwjdov67vr", "title": "Grid View", "type": "grid", "lock_type": "collaborative", "created_at": "2025-06-26 15:02:56+00:00", "updated_at": "2025-06-26 15:36:25+00:00" }, { "id": "vwfqa5qnmcaxt9yp", "table_id": "mrc5unwjdov67vr", "title": "Grid View 2", "type": "grid", "lock_type": "collaborative", "created_at": "2025-06-26 15:40:01+00:00", "updated_at": "2025-06-26 15:40:48+00:00", "description": "Grid view with some description", "created_by": "usq6o3vavwf0twzr" }, { "id": "vwx2x5ietbis99xg", "table_id": "mrc5unwjdov67vr", "title": "Grid Group By", "type": "grid", "lock_type": "collaborative", "created_at": "2025-06-26 15:40:41+00:00", "updated_at": "2025-06-26 15:40:41+00:00", "created_by": "usq6o3vavwf0twzr" }, { "id": "vwjctk8vdhbhxtd4", "table_id": "mrc5unwjdov67vr", "title": "Gallery View", "type": "gallery", "lock_type": "collaborative", "created_at": "2025-06-26 15:45:30+00:00", "updated_at": "2025-06-26 15:45:30+00:00", "created_by": "usq6o3vavwf0twzr" }, { "id": "vwnyxj93jfswla29", "table_id": "mrc5unwjdov67vr", "title": "Kanban View", "type": "kanban", "lock_type": "collaborative", "created_at": "2025-06-26 15:45:40+00:00", "updated_at": "2025-06-26 15:45:40+00:00", "created_by": "usq6o3vavwf0twzr" }, { "id": "vw7hwhx551tbr44z", "table_id": "mrc5unwjdov67vr", "title": "Calendar View", "type": "calendar", "lock_type": "collaborative", "created_at": "2025-06-26 15:45:47+00:00", "updated_at": "2025-06-26 15:45:47+00:00", "created_by": "usq6o3vavwf0twzr" } ] } } } } } }, "404": { "description": "Table not found." }, "500": { "description": "Server error." } } }, "post": { "summary": "Create view", "description": "Create a view for table.\n\n**Note**: View APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "view-create", "tags": [ "Views" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewCreate" }, "examples": { "Example 1": { "value": { "title": "Created View Title", "type": "grid" } } } } } }, "responses": { "200": { "description": "View meta updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/View" }, "examples": { "Example 1": { "value": { "id": "vw5rakj00x28vdht", "table_id": "mrc5unwjdov67vr", "title": "myFilterView2", "type": "grid", "lock_type": "collaborative", "created_at": "2025-08-13 07:36:03+00:00", "updated_at": "2025-08-13 07:36:03+00:00", "created_by": "uspf4n7qlp704qrj", "fields": [ { "field_id": "csd3tnc2t8ccbw2", "show": true }, { "field_id": "cwy23c7tglso0zp", "show": true }, { "field_id": "clljtnye0his0wv", "show": true }, { "field_id": "cmbwwvp0mhyw6uv", "show": true }, { "field_id": "c1kzoujfb6on9ba", "show": true }, { "field_id": "c711uewjhfevrjj", "show": true }, { "field_id": "cjgsfkb3307h4gj", "show": true }, { "field_id": "ck6lswg0z3h6ase", "show": true }, { "field_id": "cxlnws1ojnocsr3", "show": true } ], "options": { "row_height": "short" } } } } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "Table not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/tables/{tableId}/fields": { "post": { "summary": "Create field", "description": "Create a new field within the specified table.", "operationId": "field-create", "tags": [ "Fields" ], "parameters": [ { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." }, { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateField" }, "examples": { "SingleLineText / LongText": { "value": { "title": "New Field", "type": "SingleLineText", "default_value": "Default Value", "description": "Sample Description" } }, "RichText": { "value": { "title": "New Field", "type": "LongText", "default_value": "Default Value", "description": "Sample Description", "options": { "rich_text": true } } }, "Email / URL / PhoneNumber": { "value": { "title": "New Field", "type": "Email", "default_value": "user@nocodb.com", "description": "Sample Description", "options": { "validation": true } } }, "Number / Decimal": { "value": { "title": "New Field", "type": "Number", "default_value": "23", "description": "Sample Description", "options": { "precision": "4" } } }, "Unique Constraint": { "value": { "title": "Unique Email", "type": "Email", "unique": true, "description": "Email field with unique constraint - no duplicate values allowed" }, "summary": "Example of creating a field with unique constraint" } } } } }, "responses": { "200": { "description": "Field was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateField" } } } }, "400": { "description": "Invalid request body." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/fields/{fieldId}": { "get": { "summary": "Get field", "description": "Retrieve the details of a specific field.", "operationId": "field-read", "tags": [ "Fields" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the field being updated." } ], "responses": { "200": { "description": "Field details are retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Field" } } } }, "404": { "description": "Field not found." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update field", "description": "Update the details of a specific field.", "operationId": "field-update", "tags": [ "Fields" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the field being updated." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldUpdate" }, "examples": { "SingleLineText / LongText": { "value": { "title": "New Field", "type": "SingleLineText", "default_value": "Default Value", "description": "Sample Description" } }, "RichText": { "value": { "title": "New Field", "type": "LongText", "default_value": "Default Value", "description": "Sample Description", "options": { "rich_text": true } } }, "Email / URL / PhoneNumber": { "value": { "title": "New Field", "type": "Email", "default_value": "user@nocodb.com", "description": "Sample Description", "options": { "validation": true } } }, "Number / Decimal": { "value": { "title": "New Field", "type": "Number", "default_value": "23", "description": "Sample Description", "options": { "precision": "4" } } } } } } }, "responses": { "201": { "description": "Field was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateField" } } } }, "400": { "description": "Invalid request body." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete field", "description": "Delete a specific field.", "operationId": "field-delete", "tags": [ "Fields" ], "parameters": [ { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the field." }, { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "responses": { "204": { "description": "Field was deleted." }, "404": { "description": "Field not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/fields/{fieldId}/options": { "post": { "summary": "Add field options", "description": "Add one or more choices (options) to a SingleSelect or MultiSelect field. Existing choices are kept. Choices whose `title` already exists on the field are skipped (idempotent). Returns the updated field.", "operationId": "field-options-create", "tags": [ "Fields" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the field." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldOptionsAddReq" }, "examples": { "Add choices": { "value": { "choices": [ { "title": "In Progress" }, { "title": "Done", "color": "#36BFFF" } ] } } } } } }, "responses": { "200": { "description": "Choices were added. Returns the updated field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Field" } } } }, "400": { "description": "Invalid request body, or the field is not a select field." }, "422": { "description": "Field not found." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Remove field options", "description": "Remove one or more choices (options) from a SingleSelect or MultiSelect field, addressed by `id`. Ids not present on the field are ignored (idempotent). Removing a choice clears that value from existing records. At least one choice must remain. Returns the updated field.", "operationId": "field-options-delete", "tags": [ "Fields" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "fieldId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the field." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldOptionsDeleteReq" }, "examples": { "Remove choices": { "value": { "choices": [ { "id": "sl_xxxxxxxxxxxxxx" } ] } } } } } }, "responses": { "200": { "description": "Choices were removed. Returns the updated field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Field" } } } }, "400": { "description": "Invalid request body, the field is not a select field, or the request would remove the last remaining choice." }, "422": { "description": "Field not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/tables/{tableId}/hooks": { "get": { "summary": "List hooks", "operationId": "hooks-list", "tags": [ "Hooks" ], "description": "Retrieve a list of all hooks for a specific table.\n\n**Note**: Hook APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." } ], "responses": { "200": { "description": "List of hooks retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookV3List" }, "examples": { "Example 1": { "value": { "list": [ { "id": "hk1abc123xyz", "table_id": "tbl456def", "title": "Send Email on Insert", "description": "Sends email notification when a new record is inserted", "event": "record", "operation": ["insert"], "notification": { "type": "URL", "payload": { "path": "https://example.com/webhook" } }, "active": true, "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-16T06:04:18.000Z" } ] } } } } } }, "404": { "description": "Table not found." }, "500": { "description": "Server error." } } }, "post": { "summary": "Create hook", "description": "Create a new hook for a table.\n\n**Note**: Hook APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "hook-create", "tags": [ "Hooks" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookV3Create" }, "examples": { "Webhook Example": { "value": { "title": "New Record Webhook", "event": "record", "operation": ["insert"], "notification": { "type": "URL", "payload": { "path": "https://example.com/webhook", "method": "POST", "body": "{{ json data }}", "headers": [ { "name": "Content-Type", "value": "application/json", "enabled": true } ] } }, "active": true } } } } } }, "responses": { "200": { "description": "Hook created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookV3" }, "examples": { "Example 1": { "value": { "id": "hk1abc123xyz", "table_id": "tbl456def", "title": "New Record Webhook", "event": "record", "operation": ["insert"], "notification": { "type": "URL", "payload": { "path": "https://example.com/webhook", "method": "POST", "body": "{{ json data }}", "headers": [ { "name": "Content-Type", "value": "application/json", "enabled": true } ] } }, "active": true, "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-16T06:04:18.000Z" } } } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "Table not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/hooks/{hookId}": { "get": { "summary": "Get hook", "description": "Retrieve the details of a specific hook.\n\n**Note**: Hook APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "hook-read", "tags": [ "Hooks" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "hookId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the hook." } ], "responses": { "200": { "description": "Hook details retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookV3" }, "examples": { "Example 1": { "value": { "id": "hk1abc123xyz", "table_id": "tbl456def", "title": "Send Email on Insert", "description": "Sends email notification when a new record is inserted", "event": "record", "operation": ["insert"], "notification": { "type": "URL", "payload": { "path": "https://example.com/webhook" } }, "active": true, "trigger_fields": ["fldAbc123"], "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-16T06:04:18.000Z" } } } } } }, "404": { "description": "Hook not found." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update hook", "description": "Update the details of a specific hook.\n\n**Note**: Hook APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "hook-update", "tags": [ "Hooks" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "hookId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the hook." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookV3Update" }, "examples": { "Update Title": { "value": { "title": "Updated Hook Title" } }, "Update Active Status": { "value": { "active": false } }, "Update Notification Payload": { "value": { "notification": { "type": "URL", "payload": { "path": "https://example.com/webhook", "method": "POST", "body": "{{ json data }}", "headers": [ { "name": "Content-Type", "value": "application/json", "enabled": true } ] } } } } } } } }, "responses": { "200": { "description": "Hook updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookV3" }, "examples": { "Example 1": { "value": { "id": "hk1abc123xyz", "table_id": "tbl456def", "title": "Updated Hook Title", "event": "record", "operation": ["insert"], "notification": { "type": "URL", "payload": { "path": "https://example.com/webhook", "method": "POST", "body": "{{ json data }}", "headers": [ { "name": "Content-Type", "value": "application/json", "enabled": true } ] } }, "active": true, "created_at": "2025-01-16T06:04:18.000Z", "updated_at": "2025-01-16T06:04:18.000Z" } } } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "Hook not found." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete hook", "description": "Delete a specific hook.\n\n**Note**: Hook APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "hook-delete", "tags": [ "Hooks" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "hookId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the hook." } ], "responses": { "200": { "description": "Hook deleted successfully." }, "404": { "description": "Hook not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/views/{viewId}": { "get": { "summary": "Get view schema", "description": "Retrieve the details of a specific view.\n\n**Note**: View APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "view-read", "tags": [ "Views" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the view." } ], "responses": { "200": { "description": "View details are retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/View" }, "examples": { "Example 1": { "value": { "id": "vw5rakj00x28vdht", "table_id": "mrc5unwjdov67vr", "title": "myFilterView2", "type": "grid", "lock_type": "collaborative", "created_at": "2025-08-13 07:36:03+00:00", "updated_at": "2025-08-13 07:36:03+00:00", "created_by": "uspf4n7qlp704qrj", "fields": [ { "field_id": "csd3tnc2t8ccbw2", "show": true }, { "field_id": "cwy23c7tglso0zp", "show": true }, { "field_id": "clljtnye0his0wv", "show": true }, { "field_id": "cmbwwvp0mhyw6uv", "show": true }, { "field_id": "c1kzoujfb6on9ba", "show": true }, { "field_id": "c711uewjhfevrjj", "show": true }, { "field_id": "cjgsfkb3307h4gj", "show": true }, { "field_id": "ck6lswg0z3h6ase", "show": true }, { "field_id": "cxlnws1ojnocsr3", "show": true } ], "options": { "row_height": "short" } } } } } } }, "404": { "description": "View not found." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update view", "description": "Update the details of a specific view. The request body should contain the fields to be updated. Fields not included in the request body will remain unchanged. Fields included will overwrite the existing values. There is no provision for partial updates of fields, sort or filter using this PATCH request.\n\n**Note**: View APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "view-update", "tags": [ "Views" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the view." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewUpdate" }, "examples": { "Example 1": { "value": { "title": "Updated View Title" } } } } } }, "responses": { "200": { "description": "View meta updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/View" }, "examples": { "Example 1": { "value": { "id": "vw5rakj00x28vdht", "table_id": "mrc5unwjdov67vr", "title": "myFilterView2", "type": "grid", "lock_type": "collaborative", "created_at": "2025-08-13 07:36:03+00:00", "updated_at": "2025-08-13 07:36:03+00:00", "created_by": "uspf4n7qlp704qrj", "fields": [ { "field_id": "csd3tnc2t8ccbw2", "show": true }, { "field_id": "cwy23c7tglso0zp", "show": true }, { "field_id": "clljtnye0his0wv", "show": true }, { "field_id": "cmbwwvp0mhyw6uv", "show": true }, { "field_id": "c1kzoujfb6on9ba", "show": true }, { "field_id": "c711uewjhfevrjj", "show": true }, { "field_id": "cjgsfkb3307h4gj", "show": true }, { "field_id": "ck6lswg0z3h6ase", "show": true }, { "field_id": "cxlnws1ojnocsr3", "show": true } ], "options": { "row_height": "short" } } } } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "Table not found." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete view", "description": "Delete a specific view.\n\n**Note**: View APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "view-delete", "tags": [ "Views" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the view." } ], "responses": { "204": { "description": "View deleted successfully." }, "404": { "description": "View not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/views/{viewId}/filters": { "get": { "summary": "List view filters", "description": "Retrieve a list of all filters and groups for a specific view.", "operationId": "view-filters-list", "tags": [ "View Filters" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the view." } ], "responses": { "200": { "description": "List of filters and groups retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterListResponse" }, "examples": { "Example 1": { "value": { "list": [ { "id": "root", "group_operator": "AND", "filters": [ { "id": "fiml6n8qzam4wmvl", "field_id": "c580jyan91qwrbx", "operator": "eq", "value": "Midmarket" }, { "id": "fi3egizdiubzfo9u", "group_operator": "OR", "filters": [ { "id": "fih624x0srskaf1i", "field_id": "caymvuj3az60wyk", "operator": "eq", "value": "Mexico" }, { "id": "fi1pjkf0f88r8s6l", "field_id": "caymvuj3az60wyk", "operator": "eq", "value": "Canada" } ] } ] } ] } } } } } }, "404": { "description": "View not found." }, "500": { "description": "Server error." } } }, "post": { "summary": "Create filter", "description": "Create a new filter or filter-group for a specific view.", "operationId": "view-filter-create", "tags": [ "View Filters" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the view." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterCreateUpdate" } } } }, "responses": { "201": { "description": "Filter or group created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterCreateUpdate" } } } }, "400": { "description": "Invalid request body." }, "500": { "description": "Server error." } } }, "put": { "summary": "Replace filter", "description": "Replace filters for a specific view. All the existing filters will be overwritten with the new filters specified in this request.", "operationId": "view-filter-replace", "tags": [ "View Filters" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the view. It overwrites all existing filters." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterCreateUpdate" } } } }, "responses": { "200": { "description": "Filter or group updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterCreateUpdate" } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "Filter or group not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/filters/{filterId}": { "patch": { "summary": "Update filter", "description": "Update the details of an existing filter or group.", "operationId": "view-filter-update", "tags": [ "View Filters" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "filterId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the filter or group." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterCreateUpdate" } } } }, "responses": { "200": { "description": "Filter or group updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterCreateUpdate" } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "Filter or group not found." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete filter", "description": "Delete an existing filter or filter-group.", "operationId": "view-filter-delete", "tags": [ "View Filters" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "filterId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the filter or group." } ], "responses": { "204": { "description": "Filter or group deleted successfully." }, "404": { "description": "Filter or group not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/views/{viewId}/sorts": { "get": { "summary": "List view sorts", "operationId": "view-sorts-list", "tags": [ "View Sorts" ], "description": "Retrieve a list of all sorts for a specific view.", "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the view." } ], "responses": { "200": { "description": "List of sorts retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortListResponse" }, "examples": { "Example 1": { "value": { "list": [ { "id": "so3o7c6po0tktghc", "field_id": "c580jyan91qwrbx", "order": "asc" }, { "id": "so1n4x4w7dou8p0v", "field_id": "caymvuj3az60wyk", "order": "desc" } ] } } } } } }, "404": { "description": "View not found." }, "500": { "description": "Server error." } } }, "post": { "summary": "Add sort", "operationId": "view-sort-create", "description": "Create a new sort for a specific view.", "tags": [ "View Sorts" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the view." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortCreate" }, "examples": { "Example 1": { "value": { "field_id": "c580jyan91qwrbx", "order": "asc" } } } } } }, "responses": { "200": { "description": "Sort created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sort" } } } }, "400": { "description": "Invalid request body." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}/sorts/{sortId}": { "delete": { "summary": "Delete sort", "description": "Delete an existing sort.", "operationId": "view-sort-delete", "tags": [ "View Sorts" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "sortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the sort." } ], "responses": { "204": { "description": "Sort deleted successfully." }, "404": { "description": "Sort not found." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update sort", "description": "Update the details of an existing sort.", "operationId": "view-sort-update", "tags": [ "View Sorts" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "sortId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the sort." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SortUpdate" }, "examples": { "Example 1": { "value": { "id": "so3o7c6po0tktghc", "order": "desc" } } } } } }, "responses": { "200": { "description": "Sort updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sort" } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "Sort not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{baseId}?include[]=members": { "get": { "summary": "List base members", "description": "Retrieve all details of a specific base, including its members.\n\nNotes: Base collaboration APIs are available only with self-hosted Enterprise plans and cloud-hosted Enterprise plans.", "operationId": "base-members-list", "tags": [ "Base Members" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the base." } ], "responses": { "200": { "description": "Base meta with members & their access information was retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseWithMembers" }, "examples": { "Example 1": { "value": { "id": "p7nwavd2gcdkzvd", "title": "Getting Started", "meta": { "icon_color": "#36BFFF" }, "created_at": "2024-12-28 09:52:29+00:00", "updated_at": "2024-12-28 09:52:30+00:00", "workspace_id": "w6dw3fo0", "individual_members": { "base_members": [ { "email": "user@nocodb.com", "user_id": "usobpjptvj3m5nu3", "created_at": "2025-08-12 11:17:47+00:00", "updated_at": "2025-08-12 11:17:47+00:00", "base_role": "owner", "workspace_role": "workspace-level-owner" } ], "workspace_members": [ { "user_id": "ussbqtx9b2qjejht", "created_at": "2025-08-12 11:18:27+00:00", "updated_at": "2025-08-12 11:18:27+00:00", "email": "editor@nocodb.com", "display_name": "", "workspace_role": "workspace-level-editor" } ] } } } } } } }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{base_id}/members": { "post": { "summary": "Invite base members", "description": "Invite new members to a specific base using their User ID or Email address.\n\nNotes: Base collaboration APIs are available only with self-hosted Enterprise plans and cloud-hosted Enterprise plans.", "operationId": "base-members-invite", "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "tags": [ "Base Members" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseMemberCreate" } } } }, "responses": { "200": { "description": "Users invited successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseMember" }, "description": "List of successfully invited users." } } } }, "400": { "description": "Invalid request body or parameters." }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update base members", "description": "Update roles for existing members in a base.\n\nNotes: Base collaboration APIs are available only with self-hosted Enterprise plans and cloud-hosted Enterprise plans.", "operationId": "base-members-update", "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "tags": [ "Base Members" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseMemberUpdate" } } } }, "responses": { "200": { "description": "Users updated successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BaseMember" }, "description": "List of successfully updated users." } } } }, "400": { "description": "Invalid request body or parameters." }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete base members", "description": "Remove members from a specific base using their IDs.\n\nNotes: Base collaboration APIs are available only with self-hosted Enterprise plans and cloud-hosted Enterprise plans.", "operationId": "base-members-delete", "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "tags": [ "Base Members" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseMemberDelete" } } } }, "responses": { "200": { "description": "Users deleted successfully." }, "400": { "description": "Invalid request body or parameters." }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{base_id}/scripts": { "get": { "summary": "List Scripts", "description": "Retrieve a list of scripts associated with a specific base.\n\n**Note**: Script APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "scripts-list", "tags": [ "Scripts" ], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "responses": { "200": { "description": "List of scripts retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScriptList" }, "examples": { "scriptList": { "value": { "list": [ { "id": "scrn8jzaljnw05eu1", "title": "Validate Emails", "description": "Validates email addresses in the 'Email' field of the 'Contacts' table.", "base_id": "pgfqcp0ocloo1j3", "workspace_id": "w6dw3fo0" }, { "id": "scrna4t7xkmq92bf8", "title": "Normalize Phone Numbers", "description": "Cleans and standardizes phone numbers in the 'Phone' field of the 'Leads' table by removing non-numeric characters and applying a consistent format.", "base_id": "pgfqcp0ocloo1j3", "workspace_id": "w6dw3fo0" } ] } } } } } }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } }, "post": { "summary": "Create script", "description": "Create a new script within the specified base by providing the required script details in the request body.\n\n**Note**: Script APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "script-create", "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "tags": [ "Scripts" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScriptCreateReq" }, "examples": { "Example 1": { "value": { "title": "Sample Script", "description": "Sample Description", "script": "Sample Script", "config": {}, "meta": {} } } } } } }, "responses": { "200": { "description": "Script created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScriptGetResponse" }, "examples": { "Example 1": { "value": { "id": "screjw3n23233lk3", "title": "This is Script Title", "description": "Hello Script", "script": "const config = input.config({\n title: \"My Script\",\n description: \"This script processes data based on your configuration.\",\n items: [\n input.config.number('limit', {\n label: 'Processing Limit',\n description: 'Maximum number of records to process'\n })\n ]\n});\n\n// Use the configured values\n\n\nconst limit = config.limit;\n\noutput.text(`Processing limit: ${limit}`);", "config": { "limit": "23" }, "meta": {}, "base_id": "bas3jh4h43k4j3d", "workspace_id": "ws3n3e3nf", "created_at": "2025-01-16 06:04:18+00:00", "updated_at": "2025-01-16 06:04:18+00:00" } } } } } } } } }, "/api/v3/meta/bases/{base_id}/scripts/{script_id}": { "get": { "summary": "Get Script Info", "description": "Retrieve the details of a specific script.\n\n**Note**: Script APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "script-read", "tags": [ "Scripts" ], "parameters": [ { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the script." }, { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "responses": { "200": { "description": "Script retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScriptGetResponse" }, "examples": { "Example 1": { "value": { "id": "screjw3n23233lk3", "title": "This is Script Title", "description": "Hello Script", "script": "output.inspect(base)", "config": {}, "meta": {}, "base_id": "bas3jh4h43k4j3d", "workspace_id": "ws3n3e3nf", "created_at": "2025-01-16 06:04:18+00:00", "updated_at": "2025-01-16 06:04:18+00:00" } } } } } } } }, "patch": { "summary": "Update script", "description": "Update the script.\n\n**Note**: Script APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "script-update", "tags": [ "Scripts" ], "parameters": [ { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the script." }, { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScriptUpdateReq" } } } }, "responses": { "200": { "description": "Script updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScriptGetResponse" } } } } } }, "delete": { "summary": "Delete script", "description": "Delete the script.\n\n**Note**: Script APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "script-delete", "tags": [ "Scripts" ], "parameters": [ { "name": "script_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the script." }, { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "responses": { "200": { "description": "Script deleted." } } } }, "/api/v3/meta/bases/{base_id}/dashboards": { "get": { "summary": "List Dashboards", "description": "Retrieve a list of dashboards in the specified base.\n\n**Note**: Dashboard APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "dashboards-list", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "responses": { "200": { "description": "List of dashboards retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardList" } } } }, "404": { "description": "Base not found." }, "500": { "description": "Server error." } } }, "post": { "summary": "Create Dashboard", "description": "Create a new dashboard within the specified base.\n\n**Note**: Dashboard APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "dashboard-create", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardCreateReq" } } } }, "responses": { "200": { "description": "Dashboard created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardGetResponse" } } } }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}": { "get": { "summary": "Get Dashboard", "description": "Retrieve details of a specific dashboard. Optionally include widgets by setting the `includeWidgets` query parameter to `true`.\n\n**Note**: Dashboard APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "dashboard-read", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Include additional data. Use 'widgets' to include widget information.", "example": "widgets" } ], "responses": { "200": { "description": "Dashboard details retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardGetResponse" } } } }, "422": { "description": "Dashboard not found." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update Dashboard", "description": "Update the specified dashboard.\n\n**Note**: Dashboard APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "dashboard-update", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardUpdateReq" } } } }, "responses": { "200": { "description": "Dashboard updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardGetResponse" } } } }, "422": { "description": "Dashboard not found." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete Dashboard", "description": "Delete the specified dashboard.\n\n**Note**: Dashboard APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "dashboard-delete", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." } ], "responses": { "200": { "description": "Dashboard deleted." } } } }, "/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/data": { "get": { "summary": "Get Dashboard Data", "description": "Retrieve data for all widgets in the specified dashboard. Returns a map of widget IDs to their data.\n\n**Note**: Dashboard APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "dashboard-data-read", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." } ], "responses": { "200": { "description": "Dashboard data retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardDataResponse" } } } }, "422": { "description": "Dashboard not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/widgets": { "get": { "summary": "List Widgets", "description": "Retrieve a list of widgets in the specified dashboard.\n\n**Note**: Widget APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "widgets-list", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." } ], "responses": { "200": { "description": "List of widgets retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetList" } } } }, "422": { "description": "Dashboard not found." }, "500": { "description": "Server error." } } }, "post": { "summary": "Create Widget", "description": "Create a new widget within the specified dashboard.\n\n**Note**: Widget APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "widget-create", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetCreateReq" } } } }, "responses": { "200": { "description": "Widget created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetRead" } } } }, "422": { "description": "Dashboard not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/widgets/{widget_id}": { "get": { "summary": "Get Widget", "description": "Retrieve details of a specific widget.\n\n**Note**: Widget APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "widget-read", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." }, { "name": "widget_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the widget." } ], "responses": { "200": { "description": "Widget details retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetRead" } } } }, "422": { "description": "Widget not found." }, "500": { "description": "Server error." } } }, "patch": { "summary": "Update Widget", "description": "Update the specified widget.\n\n**Note**: Widget APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "widget-update", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." }, { "name": "widget_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the widget." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetUpdateReq" } } } }, "responses": { "200": { "description": "Widget updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WidgetRead" } } } }, "422": { "description": "Widget not found." }, "500": { "description": "Server error." } } }, "delete": { "summary": "Delete Widget", "description": "Delete the specified widget.\n\n**Note**: Widget APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "widget-delete", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." }, { "name": "widget_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the widget." } ], "responses": { "200": { "description": "Widget deleted." } } } }, "/api/v3/meta/bases/{base_id}/dashboards/{dashboard_id}/widgets/{widget_id}/data": { "get": { "summary": "Get Widget Data", "description": "Retrieve data for a specific widget.\n\n**Note**: Widget APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "widget-data-read", "tags": ["Dashboards"], "parameters": [ { "name": "base_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "dashboard_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the dashboard." }, { "name": "widget_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the widget." } ], "responses": { "200": { "description": "Widget data retrieved.", "content": { "application/json": { "schema": { "type": "object", "description": "Widget data. Structure varies by widget type." } } } }, "422": { "description": "Widget not found." }, "500": { "description": "Server error." } } } }, "/api/v3/meta/bases/{base_id}/workflows": { "get": { "summary": "List Workflows", "description": "Retrieve a list of workflows associated with a specific base.\n\n**Note**: Workflow APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "workflows-list", "tags": ["Workflows"], "parameters": [ { "schema": { "type": "string" }, "name": "base_id", "in": "path", "required": true, "description": "Unique identifier for the base." } ], "responses": { "200": { "description": "Workflow list retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowList" } } } } } } }, "/api/v3/meta/bases/{base_id}/workflows/{workflow_id}": { "get": { "summary": "Get Workflow", "description": "Retrieve the details of a specific workflow.\n\n**Note**: Workflow APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "workflow-read", "tags": ["Workflows"], "parameters": [ { "schema": { "type": "string" }, "name": "base_id", "in": "path", "required": true, "description": "Unique identifier for the base." }, { "schema": { "type": "string" }, "name": "workflow_id", "in": "path", "required": true, "description": "Unique identifier for the workflow." } ], "responses": { "200": { "description": "Workflow retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowGetResponse" } } } } } } }, "/api/v3/meta/bases/{base_id}/workflows/{workflow_id}/execute": { "post": { "summary": "Execute Workflow", "description": "Manually trigger a workflow execution. This endpoint only works for workflows whose trigger type is `manual-trigger`.\n\n**Note**: Workflow APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "workflow-execute", "tags": ["Workflows"], "parameters": [ { "schema": { "type": "string" }, "name": "base_id", "in": "path", "required": true, "description": "Unique identifier for the base." }, { "schema": { "type": "string" }, "name": "workflow_id", "in": "path", "required": true, "description": "Unique identifier for the workflow." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecuteReq" } } } }, "responses": { "200": { "description": "Workflow execution queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Execution identifier. Use this ID with the `GET /api/v3/meta/bases/{base_id}/workflows/{workflow_id}/executions/{execution_id}` endpoint to poll the execution status and retrieve results." } } } } } } } } }, "/api/v3/meta/bases/{base_id}/workflows/{workflow_id}/executions": { "get": { "summary": "List Workflow Executions", "description": "Retrieve a list of executions for a specific workflow.\n\n**Note**: Workflow APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "workflow-execution-list", "tags": ["Workflows"], "parameters": [ { "schema": { "type": "string" }, "name": "base_id", "in": "path", "required": true, "description": "Unique identifier for the base." }, { "schema": { "type": "string" }, "name": "workflow_id", "in": "path", "required": true, "description": "Unique identifier for the workflow." }, { "schema": { "type": "integer", "default": 25 }, "name": "limit", "in": "query", "description": "Maximum number of executions to return." }, { "schema": { "type": "integer", "default": 0 }, "name": "offset", "in": "query", "description": "Number of executions to skip." } ], "responses": { "200": { "description": "Execution list retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionList" } } } } } } }, "/api/v3/meta/bases/{base_id}/workflows/{workflow_id}/executions/{execution_id}": { "get": { "summary": "Get Workflow Execution", "description": "Retrieve the details of a specific workflow execution.\n\n**Note**: Workflow APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "operationId": "workflow-execution-read", "tags": ["Workflows"], "parameters": [ { "schema": { "type": "string" }, "name": "base_id", "in": "path", "required": true, "description": "Unique identifier for the base." }, { "schema": { "type": "string" }, "name": "workflow_id", "in": "path", "required": true, "description": "Unique identifier for the workflow." }, { "schema": { "type": "string" }, "name": "execution_id", "in": "path", "required": true, "description": "Unique identifier for the execution." } ], "responses": { "200": { "description": "Execution retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowExecutionGetResponse" } } } } } } }, "/api/v3/data/{baseId}/{tableId}/records": { "parameters": [ { "schema": { "type": "string" }, "name": "baseId", "in": "path", "required": true, "description": "**Base Identifier**." }, { "schema": { "type": "string" }, "name": "tableId", "in": "path", "required": true, "description": "**Table Identifier**." } ], "get": { "summary": "List Table Records", "operationId": "db-data-table-row-list", "description": "This API endpoint allows you to retrieve records from a specified table. You can customize the response by applying various query parameters for filtering, sorting, and formatting.\n\n**Pagination**: The response is paginated by default, with the first page being returned initially. The response includes the following pagination fields as top-level properties alongside `records`:\n\n- **next**: URL to retrieve the next page of records. For example, `\"https://app.nocodb.com/api/v3/tables/medhonywr18cysz/records?page=2\"`. Returns `null` when on the last page.\n- **prev**: URL to retrieve the previous page of records. Returns `null` when on the first page.\n- **nestedNext**: URL to retrieve the current page of records with the next set of nested (linked record) data. Returns `null` when there are no more nested pages.\n- **nestedPrev**: URL to retrieve the current page of records with the previous set of nested data. Returns `null` when on the first nested page.\n\nThese pagination fields are particularly valuable when working with large datasets divided into multiple pages. They provide the necessary URLs to seamlessly navigate forward and backward through the dataset.", "tags": [ "Table Records" ], "parameters": [ { "schema": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "in": "query", "name": "fields", "description": "Allows you to specify the fields that you wish to include from the linked records in your API response. By default, only Primary Key and associated display value field is included.\n\nExample: `fields=[\"field1\",\"field2\"]` or `fields=field1,field2` will include only 'field1' and 'field2' in the API response." }, { "schema": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "field": { "type": "string" } }, "required": [ "field", "direction" ] } }, { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "field": { "type": "string" } }, "required": [ "field", "direction" ] } ] }, "in": "query", "name": "sort", "description": "Allows you to specify the fields by which you want to sort the records in your API response. Accepts either an array of sort objects or a single sort object.\n\nEach sort object must have a 'field' property specifying the field name and a 'direction' property with value 'asc' or 'desc'.\n\nExample: `sort=[{\"direction\":\"asc\",\"field\":\"field_name\"},{\"direction\":\"desc\",\"field\":\"another_field\"}]` or `sort={\"direction\":\"asc\",\"field\":\"field_name\"}`\n\nIf `viewId` query parameter is also included, the sort included here will take precedence over any sorting configuration defined in the view." }, { "schema": { "type": "string" }, "in": "query", "name": "where", "description": "Enables you to define specific conditions for filtering records in your API response. Multiple conditions can be combined using logical operators such as 'and' and 'or'. Each condition consists of three parts: a field name, a comparison operator, and a value.\n\nExample: `where=(field1,eq,value1)~and(field2,eq,value2)` will filter records where 'field1' is equal to 'value1' AND 'field2' is equal to 'value2'. \n\nYou can also use other comparison operators like 'neq' (not equal), 'gt' (greater than), 'lt' (less than), and more, to create complex filtering rules.\n\nIf `viewId` query parameter is also included, then the filters included here will be applied over the filtering configuration defined in the view. \n\nPlease remember to maintain the specified format, for further information on this please see [the documentation](https://nocodb.com/docs/product-docs/developer-resources/rest-apis#v3-where-query-parameter)" }, { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "page", "description": "Enables you to control the pagination of your API response by specifying the page number you want to retrieve. By default, the first page is returned. If you want to retrieve the next page, you can increment the page number by one.\n\nExample: `page=2` will return the second page of records in the dataset." }, { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "nestedPage", "description": "Enables you to control the pagination of your nested data (linked records) in API response by specifying the page number you want to retrieve. By default, the first page is returned. If you want to retrieve the next page, you can increment the page number by one.\n\nExample: `page=2` will return the second page of nested data records in the dataset." }, { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "pageSize", "description": "Enables you to set a limit on the number of records you want to retrieve in your API response. By default, your response includes all the available records, but by using this parameter, you can control the quantity you receive.\n\nExample: `pageSize=100` will constrain your response to the first 100 records in the dataset." }, { "schema": { "type": "string" }, "name": "viewId", "in": "query", "description": "***View Identifier***. Allows you to fetch records that are currently visible within a specific view. API retrieves records in the order they are displayed if the SORT option is enabled within that view.\n\nAdditionally, if you specify a `sort` query parameter, it will take precedence over any sorting configuration defined in the view. If you specify a `where` query parameter, it will be applied over the filtering configuration defined in the view. \n\nBy default, all fields, including those that are disabled within the view, are included in the response. To explicitly specify which fields to include or exclude, you can use the `fields` query parameter to customize the output according to your requirements." }, { "schema": { "type": "string", "enum": [ "true" ] }, "name": "linksAsLtar", "in": "query", "description": "When set to `true`, Links fields will return full linked record data (id and display value) instead of just a count. This makes Links fields behave like LinkToAnotherRecord (LTAR) fields in the response." }, { "required": true, "$ref": "#/components/parameters/xc-token" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataListResponseV3" }, "examples": { "Example 1": { "value": { "records": [ { "id": 1, "fields": { "SingleLineText": "record #1", "MultiLineText": "sample long text", "Email": "user@nocodb.com", "PhoneNumber": "1234567890", "URL": "www.google.com", "Number": 1234, "Decimal": 100.88, "Currency": 100, "Percent": 10, "Duration": 1010, "Rating": 3, "Year": 2020, "Time": "20:20:00", "Checkbox": true, "Date": "2020-01-01", "SingleSelect": "Jan", "MultiSelect": [ "Jan", "Feb", "Mar" ], "DateTime": "2022-02-02 00:00:00+00:00", "LTAR": [ { "id": 1, "fields": { "SingleLineText": "record #1" } }, { "id": 2, "fields": { "SingleLineText": "record #2" } } ] } } ], "next": "https://app.nocodb.com/api/v3/data/baseId/tableId/records?page=2" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Create Table Records", "operationId": "db-data-table-row-create", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataInsertResponseV3" }, "examples": { "Example 1": { "value": { "records": [ { "id": 10, "fields": { "Number": 1, "SingleLineText": "record #1" } }, { "id": 11, "fields": { "Number": 2, "SingleLineText": "record #2" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": [ "Table Records" ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DataInsertRequestV3" }, { "type": "array", "items": { "$ref": "#/components/schemas/DataInsertRequestV3" } } ] }, "examples": { "Example 1": { "value": [ { "fields": { "Number": 1, "Decimal": 100.88, "Currency": 100, "Percent": 100, "Duration": 1010, "Rating": 3, "Year": 2020, "Time": "20:20:00", "SingleLineText": "record #1", "MultiLineText": "sample text", "Email": "user@nocodb.com", "PhoneNumber": "1234567890", "URL": "www.google.com", "SingleSelect": "jan", "Checkbox": true, "Date": "2020-01-01", "JSON": { "x": 1, "y": 2 }, "User": [ { "email": "raju@nocodb.com" } ], "MultiSelect": [ "jan", "feb", "mar" ], "DateTime": "2022-02-02 05:30:00+00:00", "LTAR": [ { "id": 1, "fields": {} }, { "id": 2, "fields": {} } ] } } ] } } } } }, "description": "This API endpoint allows the creation of new records within a specified table. Records to be inserted are input as an array of key-value pair objects, where each key corresponds to a field name. Ensure that all the required fields are included in the payload, with exceptions for fields designated as auto-increment or those having default values. \n\nCertain read-only field types will be disregarded if included in the request. These field types include Look Up, Roll Up, Formula, Created By, Updated By, Created At, Updated At, Button, Barcode and QR Code.\n\nFor **Attachment** field types, this API cannot be used. Instead, utilize the storage APIs for managing attachments. Support for attachment fields in the record update API will be added soon.", "parameters": [ { "required": true, "$ref": "#/components/parameters/xc-token" } ] }, "patch": { "summary": "Update Table Records", "operationId": "db-data-table-row-update", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataUpdateResponseV3" }, "examples": { "Example 1": { "value": { "records": [ { "id": 6 }, { "id": 7 } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": [ "Table Records" ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DataUpdateRequestV3" }, { "type": "array", "items": { "$ref": "#/components/schemas/DataUpdateRequestV3" } } ] }, "examples": { "Example 1": { "value": [ { "id": 6, "fields": { "Number": 101, "SingleLineText": "Updated record #1", "Email": "updated@nocodb.com" } }, { "id": 7, "fields": { "Number": 102, "SingleLineText": "Updated record #2" } } ] } } } } }, "description": "This API endpoint allows you to update records within a specified table by their Record ID. The request payload should contain the Record ID and the fields that need to be updated.\n\nCertain read-only field types will be disregarded if included in the request. These field types include Look Up, Roll Up, Formula, Created By, Updated By, Created At, Updated At, Button, Barcode and QR Code.\n\nFor **Attachment** field types, this API cannot be used. Instead, utilize the storage APIs for managing attachments. Support for attachment fields in the record update API will be added soon.", "parameters": [ { "required": true, "$ref": "#/components/parameters/xc-token" } ] }, "delete": { "summary": "Delete Table Records", "operationId": "db-data-table-row-delete", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataDeleteResponseV3" }, "examples": { "Example 1": { "value": { "records": [ { "id": 1, "deleted": true }, { "id": 2, "deleted": true } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": [ "Table Records" ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DataDeleteRequestV3" }, { "type": "array", "items": { "$ref": "#/components/schemas/DataDeleteRequestV3" } } ] }, "examples": { "Example 1": { "value": [ { "id": 1 }, { "id": 2 } ] } } } } }, "description": "This API endpoint allows the deletion of records within a specified table by Record ID. The request should include the Record ID of the record(s) to be deleted.", "parameters": [ { "required": true, "$ref": "#/components/parameters/xc-token" } ] } }, "/api/v3/data/{baseId}/{tableId}/records/upsert": { "parameters": [ { "schema": { "type": "string" }, "name": "baseId", "in": "path", "required": true, "description": "**Base Identifier**." }, { "schema": { "type": "string" }, "name": "tableId", "in": "path", "required": true, "description": "**Table Identifier**." } ], "post": { "summary": "Upsert Table Records", "operationId": "db-v3-data-table-row-upsert", "description": "Find-or-create records in a single call. If a record matching the merge key exists, update it; otherwise insert a new one.", "tags": ["Table Records"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataUpsertRequest" } } } }, "responses": { "200": { "description": "Upsert results with status per record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataUpsertResponse" } } } }, "400": { "description": "Bad request — invalid merge fields or missing records" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Base or table not found" } } } }, "/api/v3/data/{baseId}/{tableId}/records/{recordId}": { "parameters": [ { "schema": { "type": "string" }, "name": "baseId", "in": "path", "required": true, "description": "**Base Identifier**." }, { "schema": { "type": "string" }, "name": "tableId", "in": "path", "required": true, "description": "**Table Identifier**" }, { "schema": { "type": "string" }, "name": "recordId", "in": "path", "required": true, "description": "Record ID" } ], "get": { "summary": "Read Table Record", "operationId": "db-data-table-row-read", "description": "This API endpoint allows you to retrieve a single record identified by Record-ID, serving as unique identifier for the record from a specified table.", "tags": [ "Table Records" ], "parameters": [ { "schema": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "in": "query", "name": "fields", "description": "Allows you to specify the fields that you wish to include from the linked records in your API response. By default, only Primary Key and associated display value field is included.\n\nExample: `fields=[\"field1\",\"field2\"]` or `fields=field1,field2` will include only 'field1' and 'field2' in the API response." }, { "schema": { "type": "string", "enum": [ "true" ] }, "name": "linksAsLtar", "in": "query", "description": "When set to `true`, Links fields will return full linked record data (id and display value) instead of just a count. This makes Links fields behave like LinkToAnotherRecord (LTAR) fields in the response." }, { "required": true, "$ref": "#/components/parameters/xc-token" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataReadResponseV3" }, "examples": { "Example 1": { "value": { "id": 1, "fields": { "SingleLineText": "record #1", "MultiLineText": "sample long text", "Email": "user@nocodb.com", "PhoneNumber": "1234567890", "URL": "www.google.com", "Number": 1234, "Decimal": 100.88, "Currency": 100, "Percent": 10, "Duration": 1010, "Rating": 3, "Year": 2020, "Time": "20:20:00", "Checkbox": true, "Date": "2020-01-01", "SingleSelect": "Jan", "MultiSelect": [ "Jan", "Feb", "Mar" ], "DateTime": "2022-02-02 00:00:00+00:00", "LTAR": [ { "id": 1, "fields": { "SingleLineText": "record #1" } }, { "id": 2, "fields": { "SingleLineText": "record #2" } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/data/{baseId}/{modelId}/records/{recordId}/fields/{fieldId}/upload": { "post": { "summary": "Upload Attachment to Cell", "operationId": "db-data-table-row-attachment-upload", "description": "This API endpoint allows you to upload an attachment (base64 encoded) to a specific cell in a table. The attachment data includes content type, base64 encoded file, and filename.", "tags": [ "Table Records" ], "parameters": [ { "schema": { "type": "string" }, "name": "baseId", "in": "path", "required": true, "description": "**Base Identifier**." }, { "schema": { "type": "string" }, "name": "modelId", "in": "path", "required": true, "description": "**Model Identifier**." }, { "schema": { "type": "string" }, "name": "recordId", "in": "path", "required": true, "description": "**Record Identifier**." }, { "schema": { "type": "string" }, "name": "fieldId", "in": "path", "required": true, "description": "**Field Identifier**." }, { "required": true, "$ref": "#/components/parameters/xc-token" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contentType": { "type": "string", "description": "Content type of the file (e.g., image/png, application/pdf)." }, "file": { "type": "string", "description": "Base64 encoded file content." }, "filename": { "type": "string", "description": "Original filename of the attachment." } }, "required": [ "contentType", "file", "filename" ] }, "examples": { "Example 1": { "value": { "contentType": "image/png", "file": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==", "filename": "image.png" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataReadResponseV3" }, "examples": { "Example 1": { "value": { "id": 1, "fields": { "SingleLineText": "record #1", "MultiLineText": "sample long text", "Email": "user@nocodb.com", "PhoneNumber": "1234567890", "URL": "www.google.com", "Number": 1234, "Decimal": 100.88, "Currency": 100, "Percent": 10, "Duration": 1010, "Rating": 3, "Year": 2020, "Time": "20:20:00", "Checkbox": true, "Date": "2020-01-01", "SingleSelect": "Jan", "MultiSelect": [ "Jan", "Feb", "Mar" ], "DateTime": "2022-02-02 00:00:00+00:00", "LTAR": [ { "id": 1, "fields": { "SingleLineText": "record #1" } }, { "id": 2, "fields": { "SingleLineText": "record #2" } } ] } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/data/{baseId}/{tableId}/count": { "parameters": [ { "schema": { "type": "string" }, "name": "baseId", "in": "path", "required": true, "description": "**Base Identifier**." }, { "schema": { "type": "string" }, "name": "tableId", "in": "path", "required": true, "description": "**Table Identifier**" }, { "schema": { "type": "string" }, "name": "viewId", "in": "query", "description": "**View Identifier**. Allows you to fetch record count that are currently visible within a specific view." } ], "get": { "summary": "Count Table Records", "operationId": "db-data-table-row-count", "description": "This API endpoint allows you to retrieve the total number of records from a specified table or a view. You can narrow down search results by applying `where` query parameter", "tags": [ "Table Records" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "where", "description": "Enables you to define specific conditions for filtering record count in your API response. Multiple conditions can be combined using logical operators such as 'and' and 'or'. Each condition consists of three parts: a field name, a comparison operator, and a value.\n\nExample: `where=(field1,eq,value1)~and(field2,eq,value2)` will filter records where 'field1' is equal to 'value1' AND 'field2' is equal to 'value2'. \n\nYou can also use other comparison operators like 'neq' (not equal), 'gt' (greater than), 'lt' (less than), and more, to create complex filtering rules.\n\nIf `viewId` query parameter is also included, then the filters included here will be applied over the filtering configuration defined in the view. \n\nPlease remember to maintain the specified format, for further information on this please see [the documentation](https://nocodb.com/docs/product-docs/developer-resources/rest-apis#v3-where-query-parameter)" }, { "$ref": "#/components/parameters/xc-token" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number" } } }, "examples": { "Example 1": { "value": { "count": 3 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/data/{baseId}/{tableId}/links/{linkFieldId}/{recordId}": { "parameters": [ { "schema": { "type": "string" }, "name": "tableId", "in": "path", "required": true, "description": "**Table Identifier**" }, { "schema": { "type": "string" }, "name": "linkFieldId", "in": "path", "required": true, "description": "**Links Field Identifier** corresponding to the relation field `Link to another record` established between tables." } ], "get": { "summary": "List Linked Records", "operationId": "db-data-table-row-nested-list", "description": "This API endpoint allows you to retrieve list of linked records for a specific `Link to another record field` and `Record ID`. The response is an array of objects containing Primary Key and its corresponding display value.", "tags": [ "Linked Records" ], "parameters": [ { "schema": { "type": "string" }, "name": "recordId", "in": "path", "required": true, "description": "**Record Identifier** corresponding to the record in this table for which linked records are being fetched." }, { "schema": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "in": "query", "name": "fields", "description": "Allows you to specify the fields that you wish to include from the linked records in your API response. By default, only Primary Key and associated display value field is included.\n\nExample: `fields=[\"field1\",\"field2\"]` or `fields=field1,field2` will include only 'field1' and 'field2' in the API response." }, { "schema": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "field": { "type": "string" } }, "required": [ "field", "direction" ] } }, { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "asc", "desc" ] }, "field": { "type": "string" } }, "required": [ "field", "direction" ] } ] }, "in": "query", "name": "sort", "description": "Allows you to specify the fields by which you want to sort the records in your API response. Accepts either an array of sort objects or a single sort object.\n\nEach sort object must have a 'field' property specifying the field name and a 'direction' property with value 'asc' or 'desc'.\n\nExample: `sort=[{\"direction\":\"asc\",\"field\":\"field_name\"},{\"direction\":\"desc\",\"field\":\"another_field\"}]` or `sort={\"direction\":\"asc\",\"field\":\"field_name\"}`\n\nIf `viewId` query parameter is also included, the sort included here will take precedence over any sorting configuration defined in the view." }, { "schema": { "type": "string" }, "in": "query", "name": "where", "description": "Enables you to define specific conditions for filtering linked records in your API response. Multiple conditions can be combined using logical operators such as 'and' and 'or'. Each condition consists of three parts: a field name, a comparison operator, and a value.\n\nExample: `where=(field1,eq,value1)~and(field2,eq,value2)` will filter linked records where 'field1' is equal to 'value1' AND 'field2' is equal to 'value2'. \n\nYou can also use other comparison operators like 'neq' (not equal), 'gt' (greater than), 'lt' (less than), and more, to create complex filtering rules.\n\nPlease remember to maintain the specified format, for further information on this please see [the documentation](https://nocodb.com/docs/product-docs/developer-resources/rest-apis#v3-where-query-parameter)" }, { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "page", "description": "Enables you to control the pagination of your API response by specifying the page number you want to retrieve. By default, the first page is returned. If you want to retrieve the next page, you can increment the page number by one.\n\nExample: `page=2` will return the second page of linked records in the dataset." }, { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "pageSize", "description": "Enables you to set a limit on the number of linked records you want to retrieve in your API response. By default, your response includes all the available linked records, but by using this parameter, you can control the quantity you receive.\n\nExample: `pageSize=100` will constrain your response to the first 100 linked records in the dataset." }, { "required": true, "$ref": "#/components/parameters/xc-token" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataListResponseV3" }, "examples": { "Example 1": { "value": { "records": [ { "id": 1, "fields": { "SingleLineText": "record #1", "MultiLineText": "sample long text", "Email": "user@nocodb.com", "PhoneNumber": "1234567890", "URL": "www.google.com", "Number": 1234, "Decimal": 100.88, "Currency": 100, "Percent": 10, "Duration": 1010, "Rating": 3, "Year": 2020, "Time": "20:20:00", "Checkbox": true, "Date": "2020-01-01", "SingleSelect": "Jan", "MultiSelect": [ "Jan", "Feb", "Mar" ], "DateTime": "2022-02-02 00:00:00+00:00", "LTAR": [ { "id": 1, "fields": { "SingleLineText": "record #1" } }, { "id": 2, "fields": { "SingleLineText": "record #2" } } ] } } ], "next": "https://app.nocodb.com/api/v3/data/baseId/tableId/records?page=2" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "post": { "summary": "Link Records", "operationId": "db-data-table-row-nested-link", "responses": { "200": { "description": "Records successfully linked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the linking operation was successful", "example": true } }, "required": [ "success" ], "additionalProperties": false }, "examples": { "Success Response": { "summary": "Successful linking operation", "value": { "success": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": [ "Linked Records" ], "requestBody": { "required": true, "description": "Array of record objects to be linked, each containing an id field", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record", "example": "33" } }, "required": [ "id" ], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record", "example": "22" } }, "required": [ "id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } ] }, "examples": { "Single Record": { "summary": "Link a single record", "value": { "id": "22" } }, "Multiple Records": { "summary": "Link multiple records", "value": [ { "id": "43" }, { "id": "01" } ] } } } } }, "description": "This API endpoint allows you to link records to a specific `Link field` and `Record ID`. The request payload is an array of record-ids from the adjacent table for linking purposes. Note that any existing links, if present, will be unaffected during this operation.", "parameters": [ { "schema": { "type": "string" }, "name": "recordId", "in": "path", "required": true, "description": "**Record Identifier** corresponding to the record in this table for which links are being created." }, { "required": true, "$ref": "#/components/parameters/xc-token" } ] }, "delete": { "summary": "Unlink Records", "operationId": "db-data-table-row-nested-unlink", "responses": { "200": { "description": "Records successfully unlinked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the unlink operation was successful", "example": true } }, "required": [ "success" ], "additionalProperties": false }, "examples": { "Success Response": { "summary": "Successful unlinking operation", "value": { "success": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "tags": [ "Linked Records" ], "requestBody": { "required": true, "description": "Array of record objects to be unlinked, each containing an id field", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record", "example": "33" } }, "required": [ "id" ], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record", "example": "33" } }, "required": [ "id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } ] }, "examples": { "Single Record": { "summary": "UnLink a single record", "value": { "id": "32" } }, "Multiple Records": { "summary": "UnLink multiple records", "value": [ { "id": "1" }, { "id": "22" } ] } } } } }, "description": "This API endpoint allows you to unlink records from a specific `Link field` and `Record ID`. The request payload is an array of record-ids from the adjacent table for unlinking purposes. Note that, \n- duplicated record-ids will be ignored.\n- non-existent record-ids will be ignored.", "parameters": [ { "schema": { "type": "string" }, "name": "recordId", "in": "path", "required": true, "description": "**Record Identifier** corresponding to the record in this table for which links are being removed." }, { "required": true, "$ref": "#/components/parameters/xc-token" } ] } }, "/api/v3/data/{baseId}/{tableId}/actions/{columnId}": { "parameters": [ { "schema": { "type": "string" }, "name": "baseId", "in": "path", "required": true, "description": "**Base Identifier**." }, { "schema": { "type": "string" }, "name": "tableId", "in": "path", "required": true, "description": "**Table Identifier**." }, { "schema": { "type": "string" }, "name": "columnId", "in": "path", "required": true, "description": "**Button Field Identifier** to trigger the action." } ], "post": { "summary": "Trigger Button Action", "operationId": "trigger-action", "description": "Triggers a button action (such as AI generation) for specified rows. This is useful for bulk processing button actions programmatically. Maximum of 25 rows can be processed at a time.", "tags": [ "Table Records" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rowIds" ], "properties": { "rowIds": { "type": "array", "description": "Array of record IDs to process", "items": { "type": "string" }, "minItems": 1, "maxItems": 25, "example": [ "1", "2", "3" ] }, "preview": { "type": "boolean", "description": "Preview mode (optional)", "default": false } } }, "examples": { "Example 1": { "value": { "rowIds": [ "1", "2" ], "preview": false } } } } } }, "responses": { "200": { "description": "Action triggered successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DataRecordV3" } }, "examples": { "Example 1": { "value": [ { "id": "1", "fields": { "Title": "Updated by AI", "Description": "Generated content..." } }, { "id": "2", "fields": { "Title": "Another update", "Description": "More generated content..." } } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "parameters": [ { "required": true, "$ref": "#/components/parameters/xc-token" } ] } }, "/api/v3/meta/workspaces/{workspaceId}/teams": { "get": { "summary": "List Teams", "operationId": "teams-list-v3", "description": "Retrieve a list of teams associated with a Workspace or ORG", "tags": [ "Teams" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" } ], "responses": { "200": { "description": "List of teams", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/TeamV3" } } }, "required": [ "list" ] } } } } } }, "post": { "summary": "Create Team", "operationId": "teams-create-v3", "description": "Create a new team", "tags": [ "Teams" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamCreateV3Req" } } } }, "responses": { "200": { "description": "Created team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamV3" } } } } } } }, "/api/v3/meta/workspaces/{workspaceId}/teams/{teamId}": { "get": { "summary": "Get Team", "operationId": "teams-get-v3", "description": "Fetch details of a specific team", "tags": [ "Teams" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team ID" }, { "name": "include_workspace", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include workspace teams" } ], "responses": { "200": { "description": "Team details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDetailV3" } } } } } }, "patch": { "summary": "Update Team", "operationId": "teams-update-v3", "description": "Update name, icon, or badge color", "tags": [ "Teams" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team ID" }, { "name": "include_workspace", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include workspace teams" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamUpdateV3Req" } } } }, "responses": { "200": { "description": "Updated team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamV3" } } } } } }, "delete": { "summary": "Delete Team", "operationId": "teams-delete-v3", "description": "Delete a team", "tags": [ "Teams" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team ID" }, { "name": "include_workspace", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include workspace teams" } ], "responses": { "200": { "description": "Team deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Team has been deleted successfully" } } } } } } } } }, "/api/v3/meta/workspaces/{workspaceId}/teams/{teamId}/members": { "post": { "summary": "Add Members to Team", "operationId": "teams-members-add-v3", "description": "Add members to a team", "tags": [ "Teams" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team ID" }, { "name": "include_workspace", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include workspace teams" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMembersAddV3Req" } } } } }, "responses": { "200": { "description": "Members added successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamUser" } } } } } } }, "delete": { "summary": "Remove Member from Team", "operationId": "teams-members-remove-v3", "description": "Remove members from a team", "tags": [ "Teams" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team ID" }, { "name": "include_workspace", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include workspace teams" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMembersRemoveV3Req" } } } } }, "responses": { "200": { "description": "Members removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Members have been removed successfully" } } } } } } } }, "patch": { "summary": "Update Member Role", "operationId": "teams-members-update-v3", "description": "Update member roles in a team", "tags": [ "Teams" ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Workspace ID" }, { "name": "teamId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Team ID" }, { "name": "include_workspace", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Include workspace teams" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMembersUpdateV3Req" } } } } }, "responses": { "200": { "description": "Member roles updated successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamUser" } } } } } } } }, "/api/v3/meta/tokens": { "get": { "summary": "List API tokens", "description": "Retrieve a list of all API tokens for the organization.\n\n**Note**: \nAPI Token APIs are available only with self-hosted **Enterprise** plans and cloud-hosted **Enterprise** plans.\n> **Beta**: These APIs are currently in beta and subject to change in future releases.", "tags": [ "API Tokens" ], "security": [ { "xc-token": [] } ], "responses": { "200": { "description": "List of API tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenV3" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } }, "post": { "summary": "Create API token", "description": "Create a new API token for the organization.\n\n**Note**: API Token APIs are available only with self-hosted **Enterprise** plans and cloud-hosted **Enterprise** plans.\n> **Beta**: These APIs are currently in beta and subject to change in future releases.", "tags": [ "API Tokens" ], "security": [ { "xc-token": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Title / description for the API token", "example": "Github Integration" } } } } } }, "responses": { "200": { "description": "Created API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenWithTokenV3" }, "examples": { "created": { "value": { "id": 5, "title": "Github Integration", "token": "wxAFzFO2wwOf9ozVRjragBJ7KPWMaW2OGpklGqHh", "created_at": "2025-12-30 15:17:24+00:00", "updated_at": "2025-12-30 15:17:24+00:00" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestV3" }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } } }, "/api/v3/meta/tokens/{tokenId}": { "delete": { "summary": "Delete API token", "description": "Delete an API token by its ID.\n\n**Note**: API Token APIs are available only with self-hosted **Enterprise** plans and cloud-hosted **Enterprise** plans.\n> **Beta**: These APIs are currently in beta and subject to change in future releases.", "tags": [ "API Tokens" ], "security": [ { "xc-token": [] } ], "parameters": [ { "name": "tokenId", "in": "path", "required": true, "description": "ID of the API token to delete", "schema": { "type": "string", "example": "5" } } ], "responses": { "200": { "description": "Deleted API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTokenV3" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } } }, "/api/v3/docs/{baseId}": { "get": { "summary": "List documents", "operationId": "document-list", "description": "Retrieve a list of documents in a base. Documents are returned without content for lightweight listing.\n\nUse the `parent_id` query parameter to navigate the document hierarchy:\n- `parent_id=null` or omitted — returns root-level documents\n- `parent_id={docId}` — returns children of the specified document\n\nDocuments API is available on **Business** plan and above (Cloud) or with an **Enterprise** license (self-hosted).", "tags": [ "Documents" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base.", "example": "p_abc123def456" }, { "name": "parent_id", "in": "query", "required": false, "schema": { "type": "string", "nullable": true }, "description": "Parent document ID. Use `null` (or omit) for root-level documents, or a document ID to list its children.", "example": "null" } ], "responses": { "200": { "description": "Documents retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListResponse" }, "examples": { "Root Documents": { "value": { "list": [ { "id": "dc_r1a2b3c4d5e6f", "base_id": "p_abc123def456", "title": "Project Overview", "meta": { "icon": "📋" }, "order": 1, "parent_id": null, "has_children": true, "version": 3, "comment_count": 2, "created_by": "us_abc123", "updated_by": "us_abc123", "created_at": "2026-03-01T10:00:00.000Z", "updated_at": "2026-03-08T14:30:00.000Z" }, { "id": "dc_r7h8i9j0k1l2m", "base_id": "p_abc123def456", "title": "Meeting Notes", "meta": { "icon": "📝" }, "order": 2, "parent_id": null, "has_children": false, "version": 1, "comment_count": 0, "created_by": "us_abc123", "updated_by": "us_abc123", "created_at": "2026-03-05T09:00:00.000Z", "updated_at": "2026-03-05T09:00:00.000Z" } ] } }, "Child Documents": { "value": { "list": [ { "id": "dc_c1n2o3p4q5r6s", "base_id": "p_abc123def456", "title": "Q1 Goals", "meta": {}, "order": 1, "parent_id": "dc_r1a2b3c4d5e6f", "has_children": false, "version": 2, "comment_count": 0, "created_by": "us_abc123", "updated_by": "us_def456", "created_at": "2026-03-01T11:00:00.000Z", "updated_at": "2026-03-06T16:00:00.000Z" } ] } }, "Empty List": { "value": { "list": [] } } } } } }, "400": { "$ref": "#/components/responses/BadRequestV3" }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } }, "post": { "summary": "Create document", "operationId": "document-create", "description": "Create a new document in a base. If no `title` is provided, defaults to \"Untitled\". If no `content` is provided, defaults to an empty document.\n\nTo create a child document, pass the `parent_id` of the parent document.\n\nDocuments API is available on **Business** plan and above (Cloud) or with an **Enterprise** license (self-hosted).", "tags": [ "Documents" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base.", "example": "p_abc123def456" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreate" }, "examples": { "Minimal (empty document)": { "value": {} }, "With Title": { "value": { "title": "Weekly Standup Notes" } }, "With Rich Content": { "value": { "title": "Architecture Decision Record", "content": { "type": "doc", "content": [ { "type": "heading", "attrs": { "level": 1 }, "content": [ { "type": "text", "text": "ADR-001: Document Storage Format" } ] }, { "type": "paragraph", "content": [ { "type": "text", "text": "We decided to use rich-text JSON as the canonical storage format for document content." } ] }, { "type": "heading", "attrs": { "level": 2 }, "content": [ { "type": "text", "text": "Context" } ] }, { "type": "paragraph", "content": [ { "type": "text", "text": "Content is stored as rich-text JSON, a structured document format that preserves rich-text formatting without lossy conversions." } ] } ] }, "meta": { "icon": "📐" } } }, "Child Document": { "value": { "title": "Q1 Goals", "parent_id": "dc_r1a2b3c4d5e6f" } } } } } }, "responses": { "200": { "description": "Document created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "examples": { "Created Document": { "value": { "id": "dc_n3w1d2o3c4u5m", "base_id": "p_abc123def456", "title": "Weekly Standup Notes", "content": { "type": "doc", "content": [ { "type": "paragraph" } ] }, "meta": {}, "order": 3, "parent_id": null, "has_children": false, "version": 1, "comment_count": 0, "created_by": "us_abc123", "updated_by": "us_abc123", "created_at": "2026-03-09T12:00:00.000Z", "updated_at": "2026-03-09T12:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestV3" }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } } }, "/api/v3/docs/{baseId}/{docId}": { "get": { "summary": "Get document", "operationId": "document-read", "description": "Retrieve a single document with its full content (rich-text JSON).\n\nDocuments API is available on **Business** plan and above (Cloud) or with an **Enterprise** license (self-hosted).", "tags": [ "Documents" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base.", "example": "p_abc123def456" }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the document.", "example": "dc_r1a2b3c4d5e6f" } ], "responses": { "200": { "description": "Document retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "examples": { "Document with Content": { "value": { "id": "dc_r1a2b3c4d5e6f", "base_id": "p_abc123def456", "title": "Project Overview", "content": { "type": "doc", "content": [ { "type": "heading", "attrs": { "level": 1 }, "content": [ { "type": "text", "text": "Project Overview" } ] }, { "type": "paragraph", "content": [ { "type": "text", "text": "This document describes the " }, { "type": "text", "marks": [ { "type": "bold" } ], "text": "project goals" }, { "type": "text", "text": " and timeline." } ] }, { "type": "bulletList", "content": [ { "type": "listItem", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Phase 1: Research" } ] } ] }, { "type": "listItem", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Phase 2: Implementation" } ] } ] } ] } ] }, "meta": { "icon": "📋", "cover_image": "/api/v1/attachments/cover_abc.jpg" }, "order": 1, "parent_id": null, "has_children": true, "version": 3, "comment_count": 2, "created_by": "us_abc123", "updated_by": "us_abc123", "created_at": "2026-03-01T10:00:00.000Z", "updated_at": "2026-03-08T14:30:00.000Z" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } }, "patch": { "summary": "Update document", "operationId": "document-update", "description": "Update a document's title, content, or metadata.\n\n**Optimistic concurrency control**: You must include the current `version` of the document. If the version does not match the server's version (i.e., someone else edited it), the request will be rejected with a 422 error. This prevents silent overwrites.\n\nAfter a successful update, the returned document will have `version` incremented by 1.\n\nDocuments API is available on **Business** plan and above (Cloud) or with an **Enterprise** license (self-hosted).", "tags": [ "Documents" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base.", "example": "p_abc123def456" }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the document.", "example": "dc_r1a2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUpdate" }, "examples": { "Update Title Only": { "value": { "title": "Updated Project Overview", "version": 3 } }, "Update Content": { "value": { "content": { "type": "doc", "content": [ { "type": "heading", "attrs": { "level": 1 }, "content": [ { "type": "text", "text": "Updated Heading" } ] }, { "type": "paragraph", "content": [ { "type": "text", "text": "New paragraph content added via API." } ] } ] }, "version": 3 } }, "Update Metadata (icon and cover)": { "value": { "meta": { "icon": "🚀", "cover_image": "/api/v1/attachments/new_cover.jpg" }, "version": 3 } } } } } }, "responses": { "200": { "description": "Document updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "examples": { "Updated Document": { "value": { "id": "dc_r1a2b3c4d5e6f", "base_id": "p_abc123def456", "title": "Updated Project Overview", "content": { "type": "doc", "content": [ { "type": "paragraph" } ] }, "meta": { "icon": "📋" }, "order": 1, "parent_id": null, "has_children": true, "version": 4, "comment_count": 2, "created_by": "us_abc123", "updated_by": "us_def456", "created_at": "2026-03-01T10:00:00.000Z", "updated_at": "2026-03-09T15:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestV3" }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "422": { "description": "Version conflict — the document has been modified since it was last fetched. Fetch the latest version and retry." }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } }, "delete": { "summary": "Delete document", "operationId": "document-delete", "description": "Soft-delete a document. All child documents are also deleted (cascade).\n\nAttachments (images, files) referenced by the document are also cleaned up.\n\nDocuments API is available on **Business** plan and above (Cloud) or with an **Enterprise** license (self-hosted).", "tags": [ "Documents" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base.", "example": "p_abc123def456" }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the document to delete.", "example": "dc_r1a2b3c4d5e6f" } ], "responses": { "200": { "description": "Document deleted successfully.", "content": { "application/json": { "schema": { "type": "boolean" }, "examples": { "Deleted": { "value": true } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } } }, "/api/v3/docs/{baseId}/{docId}/reorder": { "patch": { "summary": "Reorder or move document", "operationId": "document-reorder", "description": "Update a document's sort order among its siblings, and optionally move it to a different parent.\n\n**Order**: Pass a float value. To insert between two siblings with orders 2.0 and 3.0, use 2.5 (midpoint).\n\n**Move**: Include `parent_id` to re-parent the document. Pass `null` to move to root level. Circular moves (moving a document under itself or its descendants) are rejected.\n\nDocuments API is available on **Business** plan and above (Cloud) or with an **Enterprise** license (self-hosted).", "tags": [ "Documents" ], "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base.", "example": "p_abc123def456" }, { "name": "docId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the document to reorder.", "example": "dc_r1a2b3c4d5e6f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentReorder" }, "examples": { "Change Sort Order": { "description": "Move the document to position 2.5 (between siblings at 2.0 and 3.0).", "value": { "order": 2.5 } }, "Move to Different Parent": { "description": "Move the document under a different parent and set its order.", "value": { "order": 1, "parent_id": "dc_n3w1p2a3r4e5n" } }, "Move to Different Parent Only": { "description": "Move a document under a different parent (server assigns order).", "value": { "parent_id": "dc_n3w1p2a3r4e5n" } }, "Move to Root": { "description": "Move a child document to the root level.", "value": { "order": 4, "parent_id": null } } } } } }, "responses": { "200": { "description": "Document reordered/moved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "examples": { "Reordered Document": { "value": { "id": "dc_r1a2b3c4d5e6f", "base_id": "p_abc123def456", "title": "Project Overview", "content": { "type": "doc", "content": [ { "type": "paragraph" } ] }, "meta": { "icon": "📋" }, "order": 2.5, "parent_id": null, "has_children": true, "version": 3, "comment_count": 2, "created_by": "us_abc123", "updated_by": "us_abc123", "created_at": "2026-03-01T10:00:00.000Z", "updated_at": "2026-03-09T15:30:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestV3" }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "422": { "description": "Invalid move — cannot move document under itself or its own descendant." }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } } }, "/api/v3/meta/bases/{baseId}/tables/{tableId}/records/{recordId}/comments": { "get": { "summary": "List comments", "operationId": "comments-list", "tags": [ "Comments" ], "description": "Retrieve all comments for a specific record.\n\n**Note**: Comment APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." }, { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the record." } ], "responses": { "200": { "description": "Comments retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentListResponse" } } } }, "400": { "description": "Bad request." }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } }, "post": { "summary": "Create comment", "operationId": "comments-create", "tags": [ "Comments" ], "description": "Create a new comment on a record.\n\n**Note**: Comment APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "tableId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the table." }, { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the record." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreateRequest" } } } }, "responses": { "200": { "description": "Comment created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Bad request." }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } } }, "/api/v3/meta/bases/{baseId}/comments/{commentId}": { "patch": { "summary": "Update comment", "operationId": "comments-update", "tags": [ "Comments" ], "description": "Update the text of an existing comment. Only the comment creator can update.\n\n**Note**: Comment APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the comment." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentUpdateRequest" } } } }, "responses": { "200": { "description": "Comment updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Bad request." }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } }, "delete": { "summary": "Delete comment", "operationId": "comments-delete", "tags": [ "Comments" ], "description": "Soft-delete a comment. Only the comment creator can delete.\n\n**Note**: Comment APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the comment." } ], "responses": { "200": { "description": "Comment deleted successfully.", "content": { "application/json": { "schema": { "type": "boolean", "example": true } } } }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } } }, "/api/v3/meta/bases/{baseId}/comments/{commentId}/resolve": { "post": { "summary": "Resolve comment", "operationId": "comments-resolve", "tags": [ "Comments" ], "description": "Toggle the resolved state of a comment. If already resolved, unresolves it.\n\n**Note**: Comment APIs are available only on self-hosted and cloud-hosted **Enterprise** plans.", "parameters": [ { "name": "baseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the base." }, { "name": "commentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the comment." } ], "responses": { "200": { "description": "Comment resolved/unresolved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedV3" }, "403": { "$ref": "#/components/responses/ForbiddenV3" }, "404": { "$ref": "#/components/responses/NotFoundV3" }, "500": { "$ref": "#/components/responses/InternalServerErrorV3" } } } } }, "components": { "schemas": { "DataUpsertRecordRequest": { "type": "object", "required": ["fields"], "properties": { "fields": { "type": "object", "description": "Field title → value map" } } }, "DataUpsertRequest": { "type": "object", "required": ["fieldsToMergeOn", "records"], "properties": { "fieldsToMergeOn": { "type": "array", "items": { "type": "string" }, "description": "Field titles or IDs to match on (max 3). If a matching record exists it is updated; otherwise a new record is created. When multiple records match the same combination, the request is rejected.", "minItems": 1, "maxItems": 3 }, "records": { "oneOf": [ { "$ref": "#/components/schemas/DataUpsertRecordRequest" }, { "type": "array", "items": { "$ref": "#/components/schemas/DataUpsertRecordRequest" }, "maxItems": 10 } ], "description": "Records to upsert — single object or array" } } }, "DataUpsertRecordResponse": { "type": "object", "properties": { "id": { "oneOf": [{ "type": "string" }, { "type": "number" }], "description": "Primary key value" }, "id_fields": { "type": "object", "description": "Composite PK values (when table has multi-column PK)" }, "fields": { "type": "object", "description": "Full record fields after upsert" }, "status": { "type": "string", "enum": ["inserted", "updated"], "description": "Whether this record was inserted or updated" } } }, "DataUpsertResponse": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/DataUpsertRecordResponse" } } } }, "Base": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the base." }, "title": { "type": "string", "description": "Title of the base." }, "meta": { "$ref": "#/components/schemas/BaseMetaRes" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the base was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the base was last updated." }, "workspace_id": { "type": "string", "description": "Unique identifier for the workspace to which this base belongs to." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the data source." }, "title": { "type": "string", "description": "Title of the data source." }, "type": { "type": "string", "description": "Type of the data source (e.g., pg, mysql)." }, "is_schema_readonly": { "type": "boolean", "description": "Indicates if the schema in this data source is read-only." }, "is_data_readonly": { "type": "boolean", "description": "Indicates if the data (records) in this data source is read-only." }, "integration_id": { "type": "string", "description": "Integration ID for the data source." } }, "required": [ "id", "title", "type", "is_schema_readonly", "is_data_readonly", "integration_id" ] }, "description": "List of data sources associated with this base. This information will be included only if one or more external data sources are associated with the base." } }, "required": [ "id", "title", "meta", "created_at", "updated_at", "workspace_id" ] }, "BaseWithMembers": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the base." }, "title": { "type": "string", "description": "Title of the base." }, "meta": { "$ref": "#/components/schemas/BaseMetaRes" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the base was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of when the base was last updated." }, "workspace_id": { "type": "string", "description": "Unique identifier for the workspace to which this base belongs to." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the data source." }, "title": { "type": "string", "description": "Title of the data source." }, "type": { "type": "string", "description": "Type of the data source (e.g., pg, mysql)." }, "is_schema_readonly": { "type": "boolean", "description": "Indicates if the schema in this data source is read-only." }, "is_data_readonly": { "type": "boolean", "description": "Indicates if the data (records) in this data source is read-only." }, "integration_id": { "type": "string", "description": "Integration ID for the data source." } }, "required": [ "id", "title", "type", "is_schema_readonly", "is_data_readonly", "integration_id" ] }, "description": "List of data sources associated with this base. This information will be included only if one or more external data sources are associated with the base." }, "individual_members": { "type": "object", "properties": { "base_members": { "type": "array", "items": { "$ref": "#/components/schemas/BaseMemberWithWorkspaceRole" } }, "workspace_members": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceMember" } } } } }, "required": [ "id", "title", "meta", "created_at", "updated_at", "workspace_id" ] }, "BaseMetaRes": { "type": "object", "properties": { "icon_color": { "type": "string", "description": "Specifies the color of the base icon using a hexadecimal color code (e.g., `#36BFFF`)", "pattern": "^#[0-9A-Fa-f]{6}$" } } }, "BaseMetaReq": { "type": "object", "properties": { "icon_color": { "type": "string", "description": "Specifies the color of the base icon using a hexadecimal color code (e.g., `#36BFFF`).\n\n**Constraints**:\n- Must be a valid 6-character hexadecimal color code preceded by a `#`.\n- Optional field; defaults to a standard color if not provided.", "pattern": "^#[0-9A-Fa-f]{6}$" } } }, "BaseCreate": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the base." }, "meta": { "$ref": "#/components/schemas/BaseMetaReq" } }, "required": [ "title" ] }, "BaseUpdate": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the base." }, "meta": { "$ref": "#/components/schemas/BaseMetaReq" } } }, "TableList": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the table." }, "title": { "type": "string", "description": "Title of the table." }, "description": { "type": [ "string", "null" ], "description": "Description of the table." }, "meta": { "$ref": "#/components/schemas/TableMeta" }, "base_id": { "type": "string", "description": "Unique identifier for the base to which this table belongs to." }, "source_id": { "type": "string", "description": "Unique identifier for the data source. This information will be included only if the table is associated with an external data source." }, "workspace_id": { "type": "string", "description": "Unique identifier for the workspace to which this base belongs to." } }, "required": [ "id", "title", "base_id", "workspace_id" ] } } }, "required": [ "list" ] }, "TableMeta": { "type": "object", "properties": { "icon": { "type": "string", "description": "Icon prefix to the table name that needs to be displayed in-lieu of the default table icon." } } }, "TableCreate": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the table." }, "description": { "type": [ "string", "null" ], "description": "Description of the table." }, "meta": { "$ref": "#/components/schemas/TableMeta" }, "source_id": { "type": "string", "description": "Unique identifier for the data source. Include this information only if the table being created is part of a data source." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TableCreateField" } } }, "required": [ "title" ] }, "FieldOptions": { "SingleLineText": { "title": "SingleLineText", "properties": { "type": { "enum": [ "SingleLineText" ] } } }, "LongText": { "title": "LongText", "properties": { "type": { "enum": [ "LongText" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_LongText" } } }, "PhoneNumber": { "title": "PhoneNumber", "properties": { "type": { "enum": [ "PhoneNumber" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_PhoneNumber" } } }, "URL": { "title": "URL", "properties": { "type": { "enum": [ "URL" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_URL" } } }, "Email": { "title": "Email", "properties": { "type": { "enum": [ "Email" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Email" } } }, "Number": { "title": "Number", "properties": { "type": { "enum": [ "Number" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Number" } } }, "Decimal": { "title": "Decimal", "properties": { "type": { "enum": [ "Decimal" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Decimal" } } }, "Currency": { "title": "Currency", "properties": { "type": { "enum": [ "Currency" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Currency" } } }, "Percent": { "title": "Percent", "properties": { "type": { "enum": [ "Percent" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Percent" } } }, "Duration": { "title": "Duration", "properties": { "type": { "enum": [ "Duration" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Duration" } } }, "Date": { "title": "Date", "properties": { "type": { "enum": [ "Date" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Date" } } }, "DateTime": { "title": "DateTime", "properties": { "type": { "enum": [ "DateTime" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_DateTime" } } }, "Time": { "title": "Time", "properties": { "type": { "enum": [ "Time" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Time" } } }, "SingleSelect": { "title": "SingleSelect", "properties": { "type": { "enum": [ "SingleSelect" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Select" } } }, "MultiSelect": { "title": "MultiSelect", "properties": { "type": { "enum": [ "MultiSelect" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Select" } } }, "Rating": { "title": "Rating", "properties": { "type": { "enum": [ "Rating" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Rating" } } }, "Checkbox": { "title": "Checkbox", "properties": { "type": { "enum": [ "Checkbox" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Checkbox" } } }, "Attachment": { "title": "Attachment", "properties": { "type": { "enum": [ "Attachment" ] } } }, "Geometry": { "title": "Geometry", "properties": { "type": { "enum": [ "Geometry" ] } } }, "Links": { "title": "Links", "properties": { "type": { "enum": [ "Links" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Links" } } }, "Lookup": { "title": "Lookup", "properties": { "type": { "enum": [ "Lookup" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Lookup" } } }, "Rollup": { "title": "Rollup", "properties": { "type": { "enum": [ "Rollup" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Rollup" } } }, "Button": { "title": "Button", "properties": { "type": { "enum": [ "Button" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Button" } } }, "Formula": { "title": "Formula", "properties": { "type": { "enum": [ "Formula" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Formula" } } }, "Barcode": { "title": "Barcode", "properties": { "type": { "enum": [ "Barcode" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Barcode" } } }, "Year": { "title": "Year", "properties": { "type": { "enum": [ "Year" ] } } }, "AutoNumber": { "title": "AutoNumber", "properties": { "type": { "enum": [ "AutoNumber" ] } } }, "QrCode": { "title": "QrCode", "properties": { "type": { "enum": [ "QrCode" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_QrCode" } } }, "CreatedTime": { "title": "CreatedTime", "properties": { "type": { "enum": [ "CreatedTime" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_DateTime" } } }, "LastModifiedTime": { "title": "LastModifiedTime", "properties": { "type": { "enum": [ "LastModifiedTime" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_DateTime" } } }, "CreatedBy": { "title": "CreatedBy", "properties": { "type": { "enum": [ "CreatedBy" ] } } }, "LastModifiedBy": { "title": "LastModifiedBy", "properties": { "type": { "enum": [ "LastModifiedBy" ] } } }, "LinkToAnotherRecord": { "title": "LinkToAnotherRecord", "properties": { "type": { "enum": [ "LinkToAnotherRecord" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_LinkToAnotherRecord" } } }, "User": { "title": "User", "properties": { "type": { "enum": [ "User" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_User" } } }, "JSON": { "title": "JSON", "properties": { "type": { "enum": [ "JSON" ] } } } }, "CreateField": { "allOf": [ { "oneOf": [ { "$ref": "#/components/schemas/FieldOptions/SingleLineText" }, { "$ref": "#/components/schemas/FieldOptions/LongText" }, { "$ref": "#/components/schemas/FieldOptions/PhoneNumber" }, { "$ref": "#/components/schemas/FieldOptions/URL" }, { "$ref": "#/components/schemas/FieldOptions/Email" }, { "$ref": "#/components/schemas/FieldOptions/Number" }, { "$ref": "#/components/schemas/FieldOptions/Decimal" }, { "$ref": "#/components/schemas/FieldOptions/Currency" }, { "$ref": "#/components/schemas/FieldOptions/Percent" }, { "$ref": "#/components/schemas/FieldOptions/Duration" }, { "$ref": "#/components/schemas/FieldOptions/Date" }, { "$ref": "#/components/schemas/FieldOptions/DateTime" }, { "$ref": "#/components/schemas/FieldOptions/Time" }, { "$ref": "#/components/schemas/FieldOptions/Year" }, { "$ref": "#/components/schemas/FieldOptions/SingleSelect" }, { "$ref": "#/components/schemas/FieldOptions/MultiSelect" }, { "$ref": "#/components/schemas/FieldOptions/Rating" }, { "$ref": "#/components/schemas/FieldOptions/Checkbox" }, { "$ref": "#/components/schemas/FieldOptions/Attachment" }, { "$ref": "#/components/schemas/FieldOptions/JSON" }, { "$ref": "#/components/schemas/FieldOptions/Geometry" }, { "$ref": "#/components/schemas/FieldOptions/Links" }, { "$ref": "#/components/schemas/FieldOptions/Lookup" }, { "$ref": "#/components/schemas/FieldOptions/Rollup" }, { "$ref": "#/components/schemas/FieldOptions/Button" }, { "$ref": "#/components/schemas/FieldOptions/Formula" }, { "$ref": "#/components/schemas/FieldOptions/Barcode" }, { "$ref": "#/components/schemas/FieldOptions/QrCode" }, { "$ref": "#/components/schemas/FieldOptions/CreatedTime" }, { "$ref": "#/components/schemas/FieldOptions/LastModifiedTime" }, { "$ref": "#/components/schemas/FieldOptions/CreatedBy" }, { "$ref": "#/components/schemas/FieldOptions/LastModifiedBy" }, { "$ref": "#/components/schemas/FieldOptions/LinkToAnotherRecord" }, { "$ref": "#/components/schemas/FieldOptions/User" } ], "errorMessage": { "oneOf": "Invalid field type or options. Ensure 'type' is a valid field type and 'options' matches the schema for that type." } }, { "$ref": "#/components/schemas/FieldBaseCreate" } ] }, "TableCreateField": { "allOf": [ { "oneOf": [ { "$ref": "#/components/schemas/FieldOptions/SingleLineText" }, { "$ref": "#/components/schemas/FieldOptions/LongText" }, { "$ref": "#/components/schemas/FieldOptions/PhoneNumber" }, { "$ref": "#/components/schemas/FieldOptions/URL" }, { "$ref": "#/components/schemas/FieldOptions/Email" }, { "$ref": "#/components/schemas/FieldOptions/Number" }, { "$ref": "#/components/schemas/FieldOptions/Decimal" }, { "$ref": "#/components/schemas/FieldOptions/Currency" }, { "$ref": "#/components/schemas/FieldOptions/Percent" }, { "$ref": "#/components/schemas/FieldOptions/Duration" }, { "$ref": "#/components/schemas/FieldOptions/Date" }, { "$ref": "#/components/schemas/FieldOptions/DateTime" }, { "$ref": "#/components/schemas/FieldOptions/Time" }, { "$ref": "#/components/schemas/FieldOptions/Year" }, { "$ref": "#/components/schemas/FieldOptions/SingleSelect" }, { "$ref": "#/components/schemas/FieldOptions/MultiSelect" }, { "$ref": "#/components/schemas/FieldOptions/Rating" }, { "$ref": "#/components/schemas/FieldOptions/Checkbox" }, { "$ref": "#/components/schemas/FieldOptions/Attachment" }, { "$ref": "#/components/schemas/FieldOptions/JSON" }, { "$ref": "#/components/schemas/FieldOptions/Geometry" }, { "$ref": "#/components/schemas/FieldOptions/Links" }, { "$ref": "#/components/schemas/FieldOptions/Button" }, { "$ref": "#/components/schemas/FieldOptions/Formula" }, { "$ref": "#/components/schemas/FieldOptions/CreatedTime" }, { "$ref": "#/components/schemas/FieldOptions/LastModifiedTime" }, { "$ref": "#/components/schemas/FieldOptions/CreatedBy" }, { "$ref": "#/components/schemas/FieldOptions/LastModifiedBy" }, { "$ref": "#/components/schemas/FieldOptions/LinkToAnotherRecord" }, { "$ref": "#/components/schemas/FieldOptions/User" } ], "errorMessage": { "oneOf": "Invalid field type or options. Ensure 'type' is a valid field type and 'options' matches the schema for that type." } }, { "$ref": "#/components/schemas/TableFieldBaseCreate" } ] }, "Table": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the table." }, "source_id": { "type": "string", "description": "Unique identifier for the data source. This information will be included only if the table is associated with an external data source." }, "base_id": { "type": "string", "description": "Unique identifier for the base to which this table belongs to." }, "title": { "type": "string", "description": "Title of the table." }, "description": { "type": "string", "description": "Description of the table." }, "display_field_id": { "type": "string", "description": "Unique identifier for the display field of the table. First non system field is set as display field by default." }, "workspace_id": { "type": "string", "description": "Unique identifier for the workspace to which this base belongs to." }, "fields": { "type": "array", "description": "List of fields associated with this table.", "items": { "$ref": "#/components/schemas/CreateField" } }, "views": { "type": "array", "description": "List of views associated with this table.", "items": { "$ref": "#/components/schemas/ViewSummary" } } }, "required": [ "id", "title", "base_id", "workspace_id", "display_field_id", "fields", "views" ] }, "BaseMember": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Unique identifier for the user." }, "email": { "type": "string", "format": "email", "description": "Email address of the user." }, "user_name": { "type": "string", "description": "Display name of the user." }, "base_role": { "$ref": "#/components/schemas/BaseRoles" } }, "required": [ "user_id", "email", "created_at", "updated_at", "base_role" ] }, "BaseMemberWithWorkspaceRole": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Unique identifier for the user." }, "email": { "type": "string", "format": "email", "description": "Email address of the user." }, "user_name": { "type": "string", "description": "Display name of the user." }, "base_role": { "$ref": "#/components/schemas/BaseRoles" }, "workspace_role": { "$ref": "#/components/schemas/WorkspaceRoles", "description": "Role assigned to the user in the workspace" } }, "required": [ "user_id", "email", "created_at", "updated_at", "base_role" ] }, "BaseUserDeleteRequest": {}, "BaseMemberList": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/BaseMember" } } }, "required": [ "users" ] }, "BaseMemberCreate": { "type": "array", "items": { "type": "object", "properties": { "base_role": { "$ref": "#/components/schemas/BaseRoles" } }, "required": [ "base_role" ], "oneOf": [ { "title": "Invite User with ID", "required": [ "base_role", "user_id" ], "properties": { "user_id": { "type": "string", "description": "Unique identifier for the user (skip if email is provided)" }, "user_name": { "type": "string", "description": "Full name of the user." } } }, { "title": "Invite User with Email", "required": [ "base_role", "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the user (skip if user_id is provided)" }, "user_name": { "type": "string", "description": "Full name of the user." } } } ], "errorMessage": { "oneOf": "Each member must have either a valid 'user_id' or a valid 'email', but not both." }, "description": "An object representing a new member to be created." }, "description": "Array of members to be created." }, "BaseMemberUpdate": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Unique user identifier for the member." }, "base_role": { "$ref": "#/components/schemas/BaseRoles" } }, "required": [ "user_id", "base_role" ], "description": "An object representing updates for an existing member." }, "description": "Array of member updates." }, "BaseMemberDelete": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "User unique identifier for the member." } }, "required": [ "user_id" ] } }, "TableMetaReq": { "type": "object", "properties": { "icon": { "type": "string", "description": "Icon prefix to the table name that needs to be displayed in-lieu of the default table icon." } } }, "TableUpdate": { "type": "object", "properties": { "title": { "type": "string", "description": "New title of the table." }, "description": { "type": "string", "description": "Description of the table." }, "display_field_id": { "type": "string", "description": "Unique identifier for the display field of the table. The type of the field should be one of the allowed types for display field." }, "meta": { "$ref": "#/components/schemas/TableMetaReq", "description": "Icon prefix to the table name that needs to be displayed in-lieu of the default table icon." } }, "anyOf": [ { "title": "Rename Table", "required": [ "title" ] }, { "title": "Update Table Description", "required": [ "description" ] }, { "title": "Update Display Field", "required": [ "display_field_id" ] }, { "title": "Update Table Icon", "required": [ "meta" ] } ], "errorMessage": { "anyOf": "At least one of 'title', 'description', 'display_field_id', or 'meta' must be provided." } }, "Sort": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the sort.", "readOnly": true }, "field_id": { "type": "string", "format": "uuid", "description": "Identifier for the field being sorted." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sorting direction, either 'asc' (ascending) or 'desc' (descending)." } }, "required": [ "id", "field_id", "direction" ] }, "SortCreate": { "type": "object", "properties": { "field_id": { "type": "string", "description": "Identifier for the field being sorted." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sorting direction, either 'asc' (ascending) or 'desc' (descending)." } }, "required": [ "field_id" ] }, "SortUpdate": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the sort." }, "field_id": { "type": "string", "format": "uuid", "description": "Identifier for the field being sorted." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sorting direction, either 'asc' (ascending) or 'desc' (descending)." }, "enabled": { "type": "boolean", "nullable": true, "description": "Whether this sort is enabled. Disabled sorts are skipped during evaluation." } }, "required": [ "id" ] }, "HookV3": { "type": "object", "description": "Hook configuration for table-level event triggers.", "properties": { "id": { "type": "string", "description": "Unique identifier for the hook." }, "table_id": { "type": "string", "description": "Unique identifier of the associated table." }, "title": { "type": "string", "description": "Title of the hook." }, "description": { "type": ["string", "null"], "description": "Description of the hook." }, "event": { "type": "string", "enum": ["record", "manual"], "description": "Event trigger type. 'record' triggers after the operation completes." }, "operation": { "type": "array", "items": { "type": "string", "enum": ["insert", "update", "delete"] }, "description": "Operations that trigger the hook." }, "notification": { "$ref": "#/components/schemas/HookNotificationV3" }, "active": { "type": "boolean", "description": "Indicates if the hook is active." }, "trigger_fields": { "type": "array", "items": { "type": "string" }, "description": "Field IDs that trigger the hook when modified." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the hook was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the hook was last updated." } }, "required": ["id", "table_id", "title", "event", "operation"] }, "HookV3List": { "type": "object", "description": "List response containing hooks.", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/HookV3" }, "description": "Array of hooks." } }, "required": ["list"] }, "HookV3Create": { "type": "object", "description": "Request body for creating a new hook.", "properties": { "title": { "type": "string", "description": "Title of the hook." }, "description": { "type": "string", "description": "Description of the hook." }, "event": { "type": "string", "enum": ["record", "manual"], "default": "record", "description": "Event trigger type. Defaults to 'record' (triggers after the operation completes)." }, "operation": { "type": "array", "items": { "type": "string", "enum": ["insert", "update", "delete"] }, "description": "Operations that trigger the hook." }, "notification": { "$ref": "#/components/schemas/HookNotificationV3" }, "active": { "type": "boolean", "default": true, "description": "Indicates if the hook is active." }, "trigger_fields": { "type": "array", "items": { "type": "string" }, "description": "Field IDs that trigger the hook when modified." } }, "required": ["title", "operation", "notification"] }, "HookV3Update": { "type": "object", "description": "Request body for updating an existing hook.", "properties": { "title": { "type": "string", "description": "Title of the hook." }, "description": { "type": "string", "description": "Description of the hook." }, "event": { "type": "string", "enum": ["record", "manual"], "description": "Event trigger type. 'record' triggers after the operation completes." }, "operation": { "type": "array", "items": { "type": "string", "enum": ["insert", "update", "delete"] }, "description": "Operations that trigger the hook." }, "notification": { "$ref": "#/components/schemas/HookNotificationV3" }, "active": { "type": "boolean", "description": "Indicates if the hook is active." }, "trigger_fields": { "type": "array", "items": { "type": "string" }, "description": "Field IDs that trigger the hook when modified." } } }, "HookNotificationV3Url": { "title": "URL", "type": "object", "description": "URL webhook notification. Sends an HTTP request when triggered.", "properties": { "type": { "type": "string", "enum": ["URL"], "description": "Notification channel type." }, "payload": { "type": "object", "description": "HTTP request configuration.", "properties": { "method": { "type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"], "description": "HTTP method for the webhook request." }, "path": { "type": "string", "description": "URL to send the webhook to. Supports Handlebars templates." }, "body": { "type": "string", "description": "Request body. Supports Handlebars templates." }, "headers": { "type": "array", "description": "Custom HTTP headers to include in the request.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Header name." }, "value": { "type": "string", "description": "Header value. Supports Handlebars templates." }, "enabled": { "type": "boolean", "description": "Whether this header is active." } } } }, "parameters": { "type": "array", "description": "Query parameters to append to the URL.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Query parameter name." }, "value": { "type": "string", "description": "Query parameter value. Supports Handlebars templates." }, "enabled": { "type": "boolean", "description": "Whether this parameter is active." } } } }, "auth": { "type": "string", "description": "Authentication configuration. Supports Handlebars templates." } }, "required": ["method", "path"] }, "trigger_form": { "type": "boolean", "description": "If true, the hook only fires when submitted via a specific form." }, "trigger_form_id": { "type": "string", "description": "Form view ID that triggers this hook. Only applicable when trigger_form is true." }, "include_user": { "type": "boolean", "description": "If true, includes the triggering user's info in the webhook payload." } }, "required": ["type", "payload"] }, "HookNotificationV3Email": { "title": "Email", "type": "object", "description": "Email notification via configured email adapter.", "properties": { "type": { "type": "string", "enum": ["Email"], "description": "Notification channel type." }, "payload": { "type": "object", "description": "Email configuration.", "properties": { "to": { "type": "string", "description": "Recipient email address. Supports Handlebars templates." }, "subject": { "type": "string", "description": "Email subject line. Supports Handlebars templates." }, "body": { "type": "string", "description": "Email body (HTML). Supports Handlebars templates." } }, "required": ["to", "subject", "body"] }, "trigger_form": { "type": "boolean", "description": "If true, the hook only fires when submitted via a specific form." }, "trigger_form_id": { "type": "string", "description": "Form view ID that triggers this hook. Only applicable when trigger_form is true." }, "include_user": { "type": "boolean", "description": "If true, includes the triggering user's info in the webhook payload." } }, "required": ["type", "payload"] }, "HookNotificationV3Script": { "title": "Script", "type": "object", "description": "Script notification. Executes a saved script when triggered.", "properties": { "type": { "type": "string", "enum": ["Script"], "description": "Notification channel type." }, "payload": { "type": "object", "description": "Script execution configuration.", "properties": { "scriptId": { "type": "string", "description": "Identifier of the script to execute." }, "method": { "type": "string", "description": "HTTP method used to invoke the script endpoint.", "default": "POST" }, "path": { "type": "string", "description": "Script execution endpoint path." } }, "required": ["scriptId"] }, "trigger_form": { "type": "boolean", "description": "If true, the hook only fires when submitted via a specific form." }, "trigger_form_id": { "type": "string", "description": "Form view ID that triggers this hook. Only applicable when trigger_form is true." }, "include_user": { "type": "boolean", "description": "If true, includes the triggering user's info in the webhook payload." } }, "required": ["type", "payload"] }, "HookNotificationV3Messaging": { "title": "Messaging", "type": "object", "description": "Messaging notification via plugin adapter (Slack, Discord, Telegram, etc.).", "properties": { "type": { "type": "string", "enum": ["Slack", "Discord", "Telegram", "Whatsapp", "Twilio"], "description": "Messaging platform type." }, "payload": { "type": "object", "description": "Messaging configuration.", "properties": { "body": { "type": "string", "description": "Message body. Supports Handlebars templates." } }, "required": ["body"] }, "trigger_form": { "type": "boolean", "description": "If true, the hook only fires when submitted via a specific form." }, "trigger_form_id": { "type": "string", "description": "Form view ID that triggers this hook. Only applicable when trigger_form is true." }, "include_user": { "type": "boolean", "description": "If true, includes the triggering user's info in the webhook payload." } }, "required": ["type", "payload"] }, "HookNotificationV3": { "oneOf": [ { "$ref": "#/components/schemas/HookNotificationV3Url" }, { "$ref": "#/components/schemas/HookNotificationV3Email" }, { "$ref": "#/components/schemas/HookNotificationV3Script" }, { "$ref": "#/components/schemas/HookNotificationV3Messaging" } ], "discriminator": { "propertyName": "type", "mapping": { "URL": "#/components/schemas/HookNotificationV3Url", "Email": "#/components/schemas/HookNotificationV3Email", "Script": "#/components/schemas/HookNotificationV3Script", "Slack": "#/components/schemas/HookNotificationV3Messaging", "Discord": "#/components/schemas/HookNotificationV3Messaging", "Telegram": "#/components/schemas/HookNotificationV3Messaging", "Whatsapp": "#/components/schemas/HookNotificationV3Messaging", "Twilio": "#/components/schemas/HookNotificationV3Messaging" } } }, "ViewSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the view." }, "title": { "type": "string", "description": "Name of the view." }, "view_type": { "type": "string", "enum": [ "grid", "gallery", "kanban", "calendar", "form", "map", "timeline", "gantt" ], "description": "Type of the view." } } }, "ViewAggregationEnum": { "type": "string", "enum": [ "sum", "min", "max", "avg", "median", "std_dev", "range", "count", "count_empty", "count_filled", "count_unique", "percent_empty", "percent_filled", "percent_unique", "none", "attachment_size", "checked", "unchecked", "percent_checked", "percent_unchecked", "earliest_date", "latest_date", "date_range", "month_range" ] }, "ViewList": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the view." }, "table_id": { "type": "string", "description": "Id of table associated with the view." }, "title": { "type": "string", "description": "Title of the view." }, "description": { "type": [ "string", "null" ], "description": "Description of the view." }, "type": { "type": "string", "enum": [ "grid", "gallery", "kanban", "calendar", "form", "map", "timeline", "gantt" ], "description": "Type of the view." }, "lock_type": { "type": "string", "enum": [ "collaborative", "locked", "personal" ], "description": "View configuration edit state." }, "created_by": { "type": "string", "description": "User ID of the creator." }, "owned_by": { "type": "string", "description": "User ID of the owner. Applicable only for personal views." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of creation." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of last update." } }, "required": [ "id", "title", "type", "lock_type", "created_at", "updated_at", "created_by" ] } } }, "required": [ "list" ] }, "ViewBase": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the view." }, "type": { "type": "string", "enum": [ "grid", "gallery", "kanban", "calendar", "map", "form", "timeline", "gantt", "list" ], "description": "Type of the view." }, "lock_type": { "type": "string", "enum": [ "collaborative", "locked", "personal" ], "description": "Lock type of the view.\n\n Note: Assigning view as personal using API is not supported currently", "default": "collaborative" }, "description": { "type": "string", "description": "Description of the view." } }, "required": [ "title", "type" ] }, "ViewBaseInUpdate": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the view." }, "lock_type": { "type": "string", "enum": [ "collaborative", "locked", "personal" ], "description": "Lock type of the view.\n\n Note: Assigning view as personal using API is not supported currently", "default": "collaborative" }, "description": { "type": "string", "description": "Description of the view." } } }, "ViewFields": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string", "description": "Unique identifier for the field." }, "show": { "type": "boolean", "description": "Indicates whether the field should be displayed in the view." }, "width": { "type": "integer", "description": "Width of the field in pixels.\n\n **Applicable only for grid view.**" }, "aggregation": { "$ref": "#/components/schemas/ViewAggregationEnum", "description": "Aggregation function to be applied to the field.\n\n **Applicable only for grid view.**" } }, "required": [ "field_id", "show" ] }, "description": "List of fields to be displayed in the view. \n\n- If not specified, all fields are displayed by default.\n- If an empty array is provided, only the display value field will be shown.\n- In case of partial list, fields not included in the list will be excluded from the view." }, "ViewRowColour": { "type": "object", "oneOf": [ { "type": "object", "title": "conditions", "properties": { "mode": { "type": "string", "enum": [ "filter" ], "description": "Mode of row coloring. In this mode, the color is selected based on conditions applied to the fields." }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "apply_as_row_background": { "type": "boolean" }, "color": { "type": "string" }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" } } } } }, "required": [ "mode", "conditions" ] }, { "type": "object", "title": "select", "properties": { "mode": { "type": "string", "enum": [ "select" ], "description": "Mode of row coloring. In this mode, the color is selected based on a single select field." }, "field_id": { "type": "string", "description": "Single select field ID to be used for colouring rows in the view." }, "apply_as_row_background": { "type": "boolean", "description": "Whether to additionally apply the color as row background." } }, "required": [ "mode", "field_id" ] } ], "errorMessage": { "oneOf": "Invalid row colour configuration. Must match one of the supported colour rule formats." }, "discriminator": { "propertyName": "mode" } }, "ViewOptionsGrid": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string", "description": "Identifier for the field being sorted." }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "Direction of the group, either 'asc' (ascending) or 'desc' (descending).", "default": "asc" } }, "required": [ "field_id" ] }, "description": "List of groups to be applied on the grid view." }, "row_height": { "type": "string", "enum": [ "short", "medium", "tall", "extra" ], "description": "Height of the rows in the grid view.", "default": "short" } } }, "ViewOptionsKanban": { "type": "object", "properties": { "stack_by": { "type": "object", "properties": { "field_id": { "type": "string", "description": "Single select field ID to be used for stacking cards in kanban view." }, "stack_order": { "type": "array", "description": "Order of the stacks in kanban view. If not provided, the order will be determined by options listed in associated field.\n\nExample: ```stack_order: ['option1', 'option2', 'option3']```", "items": { "type": "string" } } }, "required": [ "field_id" ] }, "cover_field_id": { "type": "string", "description": "Attachment field ID to be used as cover image in kanban view. If not provided, cover field configuration is skipped." } }, "required": [ "stack_by" ] }, "ViewOptionsCalendar": { "type": "object", "properties": { "date_ranges": { "type": "array", "items": { "type": "object", "properties": { "start_date_field_id": { "type": "string", "description": "Date field ID to be used as start date in calendar view." }, "end_date_field_id": { "type": "string", "description": "Date field ID to be used as end date in calendar view." } }, "required": [ "start_date_field_id" ] } } }, "required": [ "date_ranges" ] }, "ViewOptionsTimeline": { "type": "object", "description": "Timeline view configuration. A timeline may have multiple date ranges (e.g. \"planned\" vs \"actual\"); each range has a required start field and an optional end field.", "additionalProperties": false, "properties": { "date_ranges": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": false, "properties": { "start_date_field_id": { "type": "string", "description": "Field ID of the start date column." }, "end_date_field_id": { "type": "string", "nullable": true, "description": "Field ID of the end date column. Null means the range is a single point in time." } }, "required": [ "start_date_field_id" ] } } } }, "ViewOptionsTimelineCreate": { "description": "Timeline view configuration on create — same shape as ViewOptionsTimeline but requires date_ranges. Update (PATCH) uses the base schema so partial updates are allowed.", "allOf": [ { "$ref": "#/components/schemas/ViewOptionsTimeline" }, { "required": ["date_ranges"] } ] }, "ViewOptionsGantt": { "type": "object", "description": "Gantt view configuration. Bundles the per-view DateDependency rule with presentation settings stored on the view's meta JSON.", "additionalProperties": false, "properties": { "date_dependency": { "oneOf": [ { "$ref": "#/components/schemas/DateDependency" }, { "type": "null" } ], "description": "The view-owned date dependency rule. When null, the gantt falls back to the table-level default rule (if any). PATCH replaces the entire object — no partial updates." } } }, "ViewOptionsGanttCreate": { "description": "Gantt view configuration on create — same shape as ViewOptionsGantt but requires date_dependency. Update (PATCH) uses the base schema so partial updates are allowed.", "allOf": [ { "$ref": "#/components/schemas/ViewOptionsGantt" }, { "required": ["date_dependency"] } ] }, "DateDependency": { "type": "object", "description": "Date dependency rule for a gantt view. Top-level properties are all optional; supplying a child object (`dates`, `dependency`) commits to providing every property inside it.", "additionalProperties": false, "properties": { "dates": { "type": "object", "description": "Date column pair. Atomic — supply both or omit the block entirely.", "additionalProperties": false, "properties": { "start_field_id": { "type": "string", "description": "Field ID of the start date column." }, "end_field_id": { "type": "string", "description": "Field ID of the end date column." } }, "required": [ "start_field_id", "end_field_id" ] }, "duration_field_id": { "type": "string", "nullable": true, "description": "Optional standalone duration field; independent of the `dates` block." }, "dependency": { "type": "object", "description": "Predecessor/successor link configuration. Atomic — supply all five properties or omit the block entirely.", "additionalProperties": false, "properties": { "linkrow_field_id": { "type": "string", "description": "Link-to-another-record field that connects predecessor/successor records." }, "linkrow_role": { "type": "string", "enum": ["predecessors", "successors"] }, "connection_type": { "type": "string", "enum": ["end-to-start", "end-to-end", "start-to-end", "start-to-start"] }, "buffer_type": { "type": "string", "enum": ["flexible", "fixed", "none"] }, "buffer_days": { "type": "integer", "minimum": 0, "description": "Buffer in days. Meaningful when `buffer_type` is `fixed`; pass 0 when buffer_type is `flexible` or `none`." } }, "required": [ "linkrow_field_id", "linkrow_role", "connection_type", "buffer_type", "buffer_days" ] }, "include_weekends": { "type": "boolean", "default": true }, "is_active": { "type": "boolean", "default": true, "description": "Soft-disable the rule without deleting it." } } }, "ViewOptionsGallery": { "type": "object", "properties": { "cover_field_id": { "type": "string", "description": "Attachment field ID to be used as cover image in gallery view. Is optional, if not provided, the first attachment field will be used." } } }, "ViewOptionsMap": { "type": "object", "additionalProperties": false, "properties": { "geo_data_field_id": { "type": "string", "description": "Field ID of the GeoData column plotted on the map." } } }, "ViewOptionsList": { "type": "object", "additionalProperties": false, "description": "List view configuration. Records are organised into a hierarchy of levels; each level is a table linked to its parent through a link field.", "properties": { "levels": { "type": "array", "description": "Ordered levels of the list. Level 1 is the root table; deeper levels connect to their parent via link_field_id.", "items": { "type": "object", "additionalProperties": false, "properties": { "level": { "type": "number", "description": "1-based depth of this level (1 = root)." }, "table_id": { "type": "string", "description": "Table shown at this level." }, "link_field_id": { "type": "string", "nullable": true, "description": "Link field connecting this level to its parent. Omitted/null for the root level." }, "filters": { "$ref": "#/components/schemas/FilterCreate", "description": "Filters applied at this level." }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "Sorts applied at this level." }, "fields": { "$ref": "#/components/schemas/ViewFields", "description": "Field visibility/order at this level. Listed fields are shown in order; unlisted fields are hidden (same semantics as top-level fields)." } }, "required": [ "level", "table_id" ] } }, "show_empty_parents": { "type": "boolean", "description": "Show parent rows that have no child records." }, "row_height": { "type": "string", "enum": [ "short", "medium", "tall", "extra" ], "description": "Height of the rows in the list view.", "default": "short" } } }, "ViewOptionsForm": { "type": "object", "properties": { "form_title": { "type": "string", "description": "Heading for the form." }, "form_description": { "type": "string", "description": "Subheading for the form." }, "thank_you_message": { "type": "string", "description": "Success message shown after form submission." }, "form_redirect_after_secs": { "type": "integer", "description": "Seconds to wait before redirecting." }, "show_submit_another_button": { "type": "boolean", "description": "Whether to show another form after submission." }, "reset_form_after_submit": { "type": "boolean", "description": "Whether to show a blank form after submission." }, "form_hide_banner": { "type": "boolean", "description": "Whether to hide the banner on the form." }, "form_hide_branding": { "type": "boolean", "description": "Whether to hide branding on the form." }, "banner": { "type": "string", "format": "uri", "description": "URL of the banner image for the form." }, "logo": { "type": "string", "format": "uri", "description": "URL of the logo for the form." }, "form_background_color": { "type": "string", "description": "Background color for the form.", "pattern": "^#[0-9A-Fa-f]{6}$" }, "redirect_url": { "type": "string", "format": "uri", "description": "URL to redirect to after form submission." }, "submit_button_label": { "type": "string", "description": "Custom label for the submit button." }, "send_response_email_to": { "type": "string", "description": "Email address to send form responses to." }, "fields_by_id": { "type": "object", "description": "Per-field form configuration keyed by field_id.", "additionalProperties": { "$ref": "#/components/schemas/FormFieldConfig" } } } }, "ViewCreate": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ViewBase" }, { "oneOf": [ { "type": "object", "title": "grid", "properties": { "type": { "type": "string", "enum": [ "grid" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsGrid" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "gallery", "properties": { "type": { "type": "string", "enum": [ "gallery" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsGallery" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "kanban", "properties": { "type": { "type": "string", "enum": [ "kanban" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsKanban" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } }, "required": [ "options" ] }, { "type": "object", "title": "calendar", "properties": { "type": { "type": "string", "enum": [ "calendar" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsCalendar" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } }, "required": [ "options" ] }, { "type": "object", "title": "timeline", "properties": { "type": { "type": "string", "enum": [ "timeline" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsTimelineCreate" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } }, "required": [ "options" ] }, { "type": "object", "title": "gantt", "properties": { "type": { "type": "string", "enum": [ "gantt" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsGanttCreate" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } }, "required": [ "options" ] }, { "type": "object", "title": "map", "properties": { "type": { "type": "string", "enum": [ "map" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsMap" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "form", "properties": { "type": { "type": "string", "enum": [ "form" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsForm" }, "fields": { "$ref": "#/components/schemas/ViewFields" } } }, { "type": "object", "title": "list", "properties": { "type": { "type": "string", "enum": [ "list" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsList" } } } ], "discriminator": { "propertyName": "type" } } ], "errorMessage": { "oneOf": "Invalid view type or options. Ensure the view type is valid and its properties match the expected schema." }, "discriminator": { "propertyName": "type" } }, "ViewUpdate": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ViewBaseInUpdate" }, { "oneOf": [ { "type": "object", "title": "grid", "properties": { "options": { "$ref": "#/components/schemas/ViewOptionsGrid" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "gallery", "properties": { "options": { "$ref": "#/components/schemas/ViewOptionsGallery" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "kanban", "properties": { "options": { "$ref": "#/components/schemas/ViewOptionsKanban" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "calendar", "properties": { "options": { "$ref": "#/components/schemas/ViewOptionsCalendar" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "timeline", "properties": { "options": { "$ref": "#/components/schemas/ViewOptionsTimeline" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "gantt", "properties": { "options": { "$ref": "#/components/schemas/ViewOptionsGantt" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "map", "properties": { "options": { "$ref": "#/components/schemas/ViewOptionsMap" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "form", "properties": { "options": { "$ref": "#/components/schemas/ViewOptionsForm" }, "fields": { "$ref": "#/components/schemas/ViewFields" } } }, { "type": "object", "title": "list", "properties": { "options": { "$ref": "#/components/schemas/ViewOptionsList" } } } ], "discriminator": { "propertyName": "type" } } ], "errorMessage": { "oneOf": "Invalid view type or options. Ensure the view type is valid and its properties match the expected schema." }, "discriminator": { "propertyName": "type" } }, "View": { "type": "object", "allOf": [ { "properties": { "id": { "type": "string", "description": "Unique identifier for the view." }, "table_id": { "type": "string", "description": "Id of table associated with the view." } }, "required": [ "id" ] }, { "$ref": "#/components/schemas/ViewBase" }, { "properties": { "created_by": { "type": "string", "description": "User ID of the creator." }, "owned_by": { "type": "string", "description": "User ID of the owner." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of creation." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp of last update." } } }, { "oneOf": [ { "type": "object", "title": "grid", "properties": { "type": { "type": "string", "enum": [ "grid" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsGrid" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "gallery", "properties": { "type": { "type": "string", "enum": [ "gallery" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsGallery" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "kanban", "properties": { "type": { "type": "string", "enum": [ "kanban" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsKanban" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } }, "required": [ "options" ] }, { "type": "object", "title": "calendar", "properties": { "type": { "type": "string", "enum": [ "calendar" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsCalendar" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } }, "required": [ "options" ] }, { "type": "object", "title": "timeline", "properties": { "type": { "type": "string", "enum": [ "timeline" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsTimeline" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } }, "required": [ "options" ] }, { "type": "object", "title": "gantt", "properties": { "type": { "type": "string", "enum": [ "gantt" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsGantt" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "map", "properties": { "type": { "type": "string", "enum": [ "map" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsMap" }, "sorts": { "type": "array", "items": { "$ref": "#/components/schemas/SortCreate" }, "description": "List of sorts to be applied to the view." }, "filters": { "$ref": "#/components/schemas/FilterCreateUpdate" }, "fields": { "$ref": "#/components/schemas/ViewFields" }, "row_coloring": { "$ref": "#/components/schemas/ViewRowColour", "description": "Row colour configuration for the the view." } } }, { "type": "object", "title": "list", "properties": { "type": { "type": "string", "enum": [ "list" ] }, "options": { "$ref": "#/components/schemas/ViewOptionsList" } } } ], "errorMessage": { "oneOf": "Invalid view type or options. Ensure the view type is valid and its properties match the expected schema." }, "discriminator": { "propertyName": "type" } } ] }, "FieldBase": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the field.", "readOnly": true, "writeOnly": false }, "title": { "type": "string", "description": "Title of the field." }, "type": { "type": "string", "enum": [ "SingleLineText", "LongText", "PhoneNumber", "URL", "Email", "Number", "Decimal", "Currency", "Percent", "Duration", "Date", "DateTime", "Time", "SingleSelect", "MultiSelect", "Rating", "Checkbox", "Attachment", "Geometry", "Links", "Lookup", "Rollup", "Button", "Formula", "Barcode", "Year", "QrCode", "CreatedTime", "LastModifiedTime", "CreatedBy", "LastModifiedBy", "LinkToAnotherRecord", "User", "JSON", "AutoNumber" ], "description": "Field data type." }, "description": { "type": [ "string", "null" ], "description": "Description of the field." }, "default_value": { "type": [ "string", "boolean", "number" ], "description": "Default value for the field. Applicable for SingleLineText, LongText, PhoneNumber, URL, Email, Number, Decimal, Currency, Percent, Duration, Date, DateTime, Time, SingleSelect, MultiSelect, Rating, Checkbox, User and JSON fields." }, "unique": { "type": "boolean", "description": "Enable unique constraint for the field. When enabled, the field will only accept unique values (no duplicates allowed). Note: Unique constraint is only supported for NC-DB (not external databases) and is mutually exclusive with default values. Supported field types: SingleLineText, PhoneNumber, URL, Email, Number, Decimal, Currency, Percent, Date, DateTime and Time" } } }, "FieldBaseCreate": { "allOf": [ { "$ref": "#/components/schemas/FieldBase" }, { "required": [ "title", "type" ] } ] }, "TableFieldBaseCreate": { "allOf": [ { "$ref": "#/components/schemas/FieldBase" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SingleLineText", "LongText", "PhoneNumber", "URL", "Email", "Number", "Decimal", "Currency", "Percent", "Duration", "Date", "DateTime", "Time", "SingleSelect", "MultiSelect", "Rating", "Checkbox", "Attachment", "Geometry", "Links", "LinkToAnotherRecord", "Button", "Formula", "Year", "CreatedTime", "LastModifiedTime", "CreatedBy", "LastModifiedBy", "User", "JSON", "AutoNumber" ], "description": "Field data type." } } }, { "required": [ "title", "type" ] } ] }, "FieldOptions_LongText": { "type": "object", "title": "LongText", "properties": { "rich_text": { "type": "boolean", "description": "Enable rich text formatting." }, "generate_text_using_ai": { "type": "boolean", "description": "Enable text generation for this field using NocoAI." } }, "additionalProperties": false }, "FieldOptions_PhoneNumber": { "type": "object", "title": "PhoneNumber", "properties": { "validation": { "type": "boolean", "description": "Enable validation for phone numbers." } }, "additionalProperties": false }, "FieldOptions_URL": { "type": "object", "title": "URL", "properties": { "validation": { "type": "boolean", "description": "Enable validation for URL." } }, "additionalProperties": false }, "FieldOptions_Email": { "type": "object", "title": "Email", "properties": { "validation": { "type": "boolean", "description": "Enable validation for Email." } }, "additionalProperties": false }, "FieldOptions_Number": { "type": "object", "title": "Number", "properties": { "separator": { "type": "string", "description": "Thousand/decimal separator style. `locale` uses the runtime locale, `none_period` / `none_comma` disable thousand grouping.", "enum": [ "locale", "none_period", "none_comma", "comma_period", "period_comma", "space_period", "space_comma" ] } }, "additionalProperties": false }, "FieldOptions_Decimal": { "type": "object", "title": "Decimal", "properties": { "precision": { "type": "number", "description": "Decimal field precision. Defaults to 0", "minimum": 0, "maximum": 5 }, "separator": { "type": "string", "description": "Thousand/decimal separator style. `locale` uses the runtime locale, `none_period` / `none_comma` disable thousand grouping.", "enum": [ "locale", "none_period", "none_comma", "comma_period", "period_comma", "space_period", "space_comma" ] } }, "additionalProperties": false }, "FieldOptions_Currency": { "type": "object", "title": "Currency", "description": "Currency settings for this column. Locale defaults to `en-US` and currency code defaults to `USD`", "properties": { "locale": { "type": "string", "description": "Locale for currency formatting. Refer https://simplelocalize.io/data/locales/" }, "code": { "type": "string", "description": "Currency code. Refer https://simplelocalize.io/data/locales/", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BOV", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHE", "CHF", "CHW", "CLF", "CLP", "CNY", "COP", "COU", "CRC", "CUP", "CVE", "CYP", "CZK", "DJF", "DKK", "DOP", "DZD", "EEK", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHC", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LVL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MTL", "MUR", "MVR", "MWK", "MXN", "MXV", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "ROL", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDD", "SEK", "SGD", "SHP", "SIT", "SKK", "SLL", "SOS", "SRD", "STD", "SYP", "SZL", "THB", "TJS", "TMM", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "USN", "USS", "UYU", "UZS", "VEB", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XBA", "XBB", "XBC", "XBD", "XCD", "XDR", "XFO", "XFU", "XOF", "XPD", "XPF", "XPT", "XTS", "XXX", "YER", "ZAR", "ZMK", "ZWD" ] } }, "additionalProperties": false }, "FieldOptions_Percent": { "type": "object", "title": "Percent", "properties": { "show_as_progress": { "type": "boolean", "description": "Display as a progress bar." }, "shape": { "type": "string", "enum": ["bar", "circle"], "description": "Progress bar shape. Only applies when `show_as_progress` is enabled.\n- `bar` (default)\n- `circle`" } }, "additionalProperties": false }, "FieldOptions_Duration": { "type": "object", "title": "Duration", "properties": { "duration_format": { "type": "string", "description": "Duration format. Supported options are listed below\n- `h:mm`\n- `h:mm:ss`\n- `h:mm:ss.S`\n- `h:mm:ss.SS`\n- `h:mm:ss.SSS`" } }, "additionalProperties": false }, "FieldOptions_DateTime": { "type": "object", "title": "DateTime", "properties": { "date_format": { "type": "string", "description": "Date format. Supported options are listed below\n- `YYYY/MM/DD`\n- `YYYY-MM-DD`\n- `YYYY MM DD`\n- `DD/MM/YYYY`\n- `DD-MM-YYYY`\n- `DD MM YYYY`\n- `MM/DD/YYYY`\n- `MM-DD-YYYY`\n- `MM DD YYYY`\n- `YYYY-MM`\n- `YYYY MM`\n- `dddd YYYY-MM-DD`\n- `ddd YYYY-MM-DD`\n- `dddd DD/MM/YYYY`\n- `ddd DD/MM/YYYY`\n- `dddd MM/DD/YYYY`\n- `ddd MM/DD/YYYY`" }, "time_format": { "type": "string", "description": "Time format. Supported options are listed below\n- `HH:mm`\n- `HH:mm:ss`\n- `HH:mm:ss.SSS`" }, "12hr_format": { "type": "boolean", "description": "Use 12-hour time format." }, "display_timezone": { "type": "boolean", "description": "Display timezone." }, "timezone": { "type": "string", "description": "Timezone. Refer to https://en.wikipedia.org/wiki/List_of_tz_database_time_zones" }, "use_same_timezone_for_all": { "type": "boolean", "description": "Use same timezone for all records." } }, "additionalProperties": false }, "FieldOptions_Date": { "type": "object", "title": "Date", "properties": { "date_format": { "type": "string", "description": "Date format. Supported options are listed below\n- `YYYY/MM/DD`\n- `YYYY-MM-DD`\n- `YYYY MM DD`\n- `DD/MM/YYYY`\n- `DD-MM-YYYY`\n- `DD MM YYYY`\n- `MM/DD/YYYY`\n- `MM-DD-YYYY`\n- `MM DD YYYY`\n- `YYYY-MM`\n- `YYYY MM`\n- `dddd YYYY-MM-DD`\n- `ddd YYYY-MM-DD`\n- `dddd DD/MM/YYYY`\n- `ddd DD/MM/YYYY`\n- `dddd MM/DD/YYYY`\n- `ddd MM/DD/YYYY`" } }, "additionalProperties": false }, "FieldOptions_Time": { "type": "object", "title": "Time", "properties": { "12hr_format": { "type": "boolean", "description": "Use 12-hour time format." } }, "additionalProperties": false }, "FieldOptions_Select": { "type": "object", "title": "Single & MultiSelect", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Choice title." }, "color": { "type": "string", "description": "Specifies the tile color for the choice using a hexadecimal color code (e.g., `#36BFFF`).", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "required": [ "title" ] }, "uniqueItems": true } }, "additionalProperties": false }, "FieldOptions_Rating": { "type": "object", "title": "Rating", "properties": { "icon": { "type": "string", "enum": [ "star", "heart", "circle-filled", "thumbs-up", "flag" ], "description": "Icon to display rating on the UI. Supported options are listed below\n- `star`\n- `heart`\n- `circle-filled`\n- `thumbs-up`\n- `flag`" }, "max_value": { "type": "integer", "description": "Maximum value for the rating. Allowed range: 1-10.", "minimum": 1, "maximum": 10 }, "color": { "type": "string", "description": "Specifies icon color using a hexadecimal color code (e.g., `#36BFFF`).", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "additionalProperties": false }, "FieldOptions_Checkbox": { "type": "object", "title": "Checkbox", "properties": { "icon": { "type": "string", "enum": [ "square", "circle-check", "circle-filled", "star", "heart", "thumbs-up", "flag" ], "description": "Icon to display checkbox on the UI. Supported options are listed below\n- `square`\n- `circle-check`\n- `circle-filled`\n- `star`\n- `heart`\n- `thumbs-up`\n- `flag`" }, "color": { "type": "string", "description": "Specifies icon color using a hexadecimal color code (e.g., `#36BFFF`).", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "additionalProperties": false }, "FieldOptions_Barcode": { "type": "object", "title": "Barcode", "properties": { "format": { "type": "string", "description": "Barcode format (e.g., CODE128)." }, "barcode_value_field_id": { "type": "string", "description": "Field ID that contains the value." } }, "additionalProperties": false }, "FieldOptions_QrCode": { "type": "object", "title": "QrCode", "properties": { "qrcode_value_field_id": { "type": "string", "description": "Field ID that contains the value." } }, "additionalProperties": false }, "FieldOptions_Formula": { "type": "object", "title": "Formula", "properties": { "formula": { "type": "string", "description": "Formula expression." } }, "additionalProperties": false }, "FieldOptions_User": { "type": "object", "title": "User", "properties": { "allow_multiple_users": { "type": "boolean", "description": "Allow selecting multiple users." } }, "additionalProperties": false }, "FieldOptions_Lookup": { "type": "object", "title": "Lookup", "properties": { "related_field_id": { "type": "string", "description": "Linked field ID. Can be of type Links or LinkToAnotherRecord" }, "related_table_lookup_field_id": { "type": "string", "description": "Lookup field ID in the linked table." }, "error": { "type": "string", "description": "Error message when dependent field is deleted" } }, "required": [ "related_field_id", "related_table_lookup_field_id" ], "additionalProperties": false }, "FieldOptions_Rollup": { "type": "object", "title": "Rollup", "properties": { "related_field_id": { "type": "string", "description": "Linked field ID." }, "related_table_rollup_field_id": { "type": "string", "description": "Rollup field ID in the linked table." }, "rollup_function": { "type": "string", "description": "Rollup function.", "enum": [ "count", "min", "max", "avg", "sum", "countDistinct", "sumDistinct", "avgDistinct" ] }, "error": { "type": "string", "description": "Error message when dependent field is deleted" }, "separator": { "type": "string", "description": "Thousand/decimal separator style for numeric rollups. `locale` uses the runtime locale, `none_period` / `none_comma` disable thousand grouping.", "enum": [ "locale", "none_period", "none_comma", "comma_period", "period_comma", "space_period", "space_comma" ] } }, "required": [ "related_field_id", "related_table_rollup_field_id", "rollup_function" ], "additionalProperties": false }, "FieldOptions_Button": { "type": "object", "title": "Button", "oneOf": [ { "title": "Formula Button", "type": "object", "properties": { "type": { "type": "string", "enum": [ "formula" ], "description": "Button type: formula" }, "formula": { "type": "string", "description": "Formula to execute" }, "label": { "type": "string", "description": "Label of the button" }, "icon": { "type": "string", "description": "Icon of the button" }, "color": { "type": "string", "enum": [ "brand", "red", "green", "maroon", "blue", "orange", "pink", "purple", "yellow", "gray" ], "description": "Color of the button" }, "theme": { "type": "string", "enum": [ "solid", "light", "text" ], "description": "Theme of the button" } }, "required": [ "type", "formula" ], "additionalProperties": false }, { "title": "Webhook Button", "type": "object", "properties": { "type": { "type": "string", "enum": [ "webhook" ], "description": "Button type: webhook" }, "button_hook_id": { "type": "string", "description": "ID of the webhook to trigger" }, "label": { "type": "string", "description": "Label of the button" }, "icon": { "type": "string", "description": "Icon of the button" }, "color": { "type": "string", "enum": [ "brand", "red", "green", "maroon", "blue", "orange", "pink", "purple", "yellow", "gray" ], "description": "Color of the button" }, "theme": { "type": "string", "enum": [ "solid", "light", "text" ], "description": "Theme of the button" } }, "required": [ "type", "button_hook_id" ], "additionalProperties": false }, { "title": "AI Button", "type": "object", "properties": { "type": { "type": "string", "enum": [ "ai" ], "description": "Button type: AI" }, "prompt": { "type": "string", "description": "AI prompt to execute" }, "integration_id": { "type": "string", "description": "Integration ID for AI service" }, "theme": { "type": "string", "enum": [ "solid", "light", "text" ], "description": "Theme of the button" }, "output_column_ids": { "type": "string", "description": "IDs of columns where AI output should be stored" }, "label": { "type": "string", "description": "Label of the button" }, "icon": { "type": "string", "description": "Icon of the button" }, "color": { "type": "string", "enum": [ "brand", "red", "green", "maroon", "blue", "orange", "pink", "purple", "yellow", "gray" ], "description": "Color of the button" } }, "required": [ "type", "prompt", "integration_id" ], "additionalProperties": false }, { "title": "Script Button", "type": "object", "properties": { "type": { "type": "string", "enum": [ "script" ], "description": "Button type: script" }, "script_id": { "type": "string", "description": "ID of the script to trigger" }, "label": { "type": "string", "description": "Label of the button" }, "icon": { "type": "string", "description": "Icon of the button" }, "color": { "type": "string", "enum": [ "brand", "red", "green", "maroon", "blue", "orange", "pink", "purple", "yellow", "gray" ], "description": "Color of the button" }, "theme": { "type": "string", "enum": [ "solid", "light", "text" ], "description": "Theme of the button" } }, "required": [ "type", "script_id" ], "additionalProperties": false } ], "errorMessage": { "oneOf": "Invalid button field options. Must match one of the supported button action types (webhook, url, ai, script)." }, "discriminator": { "propertyName": "type", "mapping": { "formula": "#/components/schemas/FieldOptions_Button/oneOf/0", "webhook": "#/components/schemas/FieldOptions_Button/oneOf/1", "ai": "#/components/schemas/FieldOptions_Button/oneOf/2", "script": "#/components/schemas/FieldOptions_Button/oneOf/3" } } }, "FieldOptions_Links": { "type": "object", "title": "Links", "properties": { "relation_type": { "type": "string", "description": "Type of relationship.\n\nSupported options are listed below\n- `om` one-to-many\n- `mo` many-to-one\n- `mm` many-to-many\n- `oo` one-to-one" }, "related_table_id": { "type": "string", "description": "Identifier of the linked table." } }, "required": [ "relation_type", "related_table_id" ], "additionalProperties": false }, "FieldOptions_LinkToAnotherRecord": { "type": "object", "title": "LinkToAnotherRecord", "properties": { "relation_type": { "type": "string", "description": "Type of relationship.\n\nSupported options are listed below\n- `om` one-to-many\n- `mo` many-to-one\n- `mm` many-to-many\n- `oo` one-to-one" }, "related_table_id": { "type": "string", "description": "Identifier of the linked table." } }, "required": [ "relation_type", "related_table_id" ], "additionalProperties": false }, "Field": { "allOf": [ { "$ref": "#/components/schemas/FieldBase" }, { "oneOf": [ { "properties": { "type": { "enum": [ "SingleLineText" ] } } }, { "properties": { "type": { "enum": [ "LongText" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_LongText" } } }, { "properties": { "type": { "enum": [ "PhoneNumber", "URL", "Email" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_PhoneNumber" } } }, { "properties": { "type": { "enum": [ "Number", "Decimal" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Number" } } }, { "properties": { "type": { "enum": [ "JSON" ] } } }, { "properties": { "type": { "enum": [ "Currency" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Currency" } } }, { "properties": { "type": { "enum": [ "Percent" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Percent" } } }, { "properties": { "type": { "enum": [ "Duration" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Duration" } } }, { "properties": { "type": { "enum": [ "Date", "DateTime", "Time" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_DateTime" } } }, { "properties": { "type": { "enum": [ "SingleSelect", "MultiSelect" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Select" } } }, { "properties": { "type": { "enum": [ "Rating", "Checkbox" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Rating" } } }, { "properties": { "type": { "enum": [ "Barcode" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Barcode" } } }, { "properties": { "type": { "enum": [ "Formula" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Formula" } } }, { "properties": { "type": { "enum": [ "User" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_User" } } }, { "properties": { "type": { "enum": [ "Lookup" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Lookup" } } }, { "properties": { "type": { "enum": [ "Links" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Links" } } }, { "properties": { "type": { "enum": [ "LinkToAnotherRecord" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_LinkToAnotherRecord" } } } ], "errorMessage": { "oneOf": "Invalid field options. Ensure 'uidt' is a valid field type and the options match the schema for that type." } } ] }, "FilterCreateUpdate": { "oneOf": [ { "$ref": "#/components/schemas/Filter" }, { "$ref": "#/components/schemas/FilterGroup" } ], "errorMessage": { "oneOf": "Must match either a Filter or a FilterGroup schema." } }, "FieldOptionAddItem": { "type": "object", "properties": { "title": { "type": "string", "description": "Choice title." }, "color": { "type": "string", "description": "Tile color for the choice as a hex code (e.g. `#36BFFF`). Defaults to a palette color when omitted.", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "required": [ "title" ], "additionalProperties": false }, "FieldOptionDeleteItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the choice to remove." } }, "required": [ "id" ], "additionalProperties": false }, "FieldOptionsAddReq": { "type": "object", "description": "Add choices (options) to a SingleSelect/MultiSelect field. Titles that already exist on the field are skipped (idempotent).", "properties": { "choices": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/FieldOptionAddItem" } } }, "required": [ "choices" ], "additionalProperties": false }, "FieldOptionsDeleteReq": { "type": "object", "description": "Remove choices (options) from a SingleSelect/MultiSelect field by id. Ids not present on the field are ignored (idempotent).", "properties": { "choices": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/FieldOptionDeleteItem" } } }, "required": [ "choices" ], "additionalProperties": false }, "FieldUpdate": { "allOf": [ { "$ref": "#/components/schemas/FieldBase" }, { "oneOf": [ { "$ref": "#/components/schemas/FieldOptions/SingleLineText" }, { "title": "LongText", "properties": { "type": { "enum": [ "LongText" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_LongText" } } }, { "title": "PhoneNumber", "properties": { "type": { "enum": [ "PhoneNumber", "URL", "Email" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_PhoneNumber" } } }, { "title": "Number / Decimal", "properties": { "type": { "enum": [ "Number", "Decimal" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Number" } } }, { "title": "JSON", "properties": { "type": { "enum": [ "JSON" ] } } }, { "title": "Currency", "properties": { "type": { "enum": [ "Currency" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Currency" } } }, { "title": "Percent", "properties": { "type": { "enum": [ "Percent" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Percent" } } }, { "title": "Duration", "properties": { "type": { "enum": [ "Duration" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Duration" } } }, { "title": "Date / DateTime", "properties": { "type": { "enum": [ "Date", "DateTime", "Time" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_DateTime" } } }, { "title": "Single / MultiSelect", "properties": { "type": { "enum": [ "SingleSelect", "MultiSelect" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Select" } } }, { "title": "Checkbox", "properties": { "type": { "enum": [ "Checkbox" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Checkbox" } } }, { "title": "Rating", "properties": { "type": { "enum": [ "Rating" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Rating" } } }, { "title": "Barcode", "properties": { "type": { "enum": [ "Barcode" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Barcode" } } }, { "title": "Formula", "properties": { "type": { "enum": [ "Formula" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Formula" } } }, { "title": "User", "properties": { "type": { "enum": [ "User" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_User" } } }, { "title": "Lookup", "properties": { "type": { "enum": [ "Lookup" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Lookup" } } }, { "title": "Links", "properties": { "type": { "enum": [ "Links" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_Links" } } }, { "title": "LinkToAnotherRecord", "properties": { "type": { "enum": [ "LinkToAnotherRecord" ] }, "options": { "$ref": "#/components/schemas/FieldOptions_LinkToAnotherRecord" } } } ], "errorMessage": { "oneOf": "Invalid field type or options. Ensure 'type' is a valid field type and 'options' matches the schema for that type." } } ], "minProperties": 1 }, "Filter": { "type": "object", "title": "Filter", "properties": { "id": { "type": "string", "description": "Unique identifier for the filter.", "readOnly": true }, "parent_id": { "type": "string", "description": "Parent ID of the filter, specifying this filters group association. Defaults to **root**." }, "field_id": { "type": "string", "description": "Field ID to which this filter applies." }, "operator": { "type": "string", "description": "Primary comparison operator (e.g., eq, gt, lt)." }, "sub_operator": { "type": [ "string", "null" ], "description": "Secondary comparison operator (if applicable)." }, "value": { "type": [ "string", "number", "boolean", "null" ], "description": "Value for comparison." } }, "required": [ "field_id", "operator" ] }, "FilterListResponse": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/FilterGroup" }, "description": "List of filter groups. Initial set of filters are mapped to a default group with group-id set to **root**." } }, "required": [ "list" ] }, "FilterGroupLevel3": { "type": "object", "properties": { "group_operator": { "type": "string", "enum": [ "AND", "OR" ], "description": "Logical operator for the group." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" }, "description": "List of filters in this group." } }, "required": [ "group_operator", "filters" ] }, "FilterGroupLevel2": { "type": "object", "properties": { "group_operator": { "type": "string", "enum": [ "AND", "OR" ], "description": "Logical operator for the group." }, "filters": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Filter" }, { "$ref": "#/components/schemas/FilterGroupLevel3" } ], "errorMessage": { "oneOf": "Must match either a Filter or a FilterGroup schema." } }, "description": "List of filters or nested filter groups at level 3." } }, "required": [ "group_operator", "filters" ] }, "FilterGroupLevel1": { "type": "object", "properties": { "group_operator": { "type": "string", "enum": [ "AND", "OR" ], "description": "Logical operator for the group." }, "filters": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Filter" }, { "$ref": "#/components/schemas/FilterGroupLevel2" } ], "errorMessage": { "oneOf": "Must match either a Filter or a FilterGroup schema." } }, "description": "List of filters or nested filter groups at level 2." } }, "required": [ "group_operator", "filters" ] }, "FilterGroup": { "type": "object", "title": "FilterGroup", "properties": { "id": { "type": "string", "description": "Unique identifier for the group.", "readOnly": true }, "parent_id": { "type": "string", "description": "Parent ID of this filter-group." }, "group_operator": { "type": "string", "enum": [ "AND", "OR" ], "description": "Logical operator for combining filters in the group." }, "filters": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/Filter" }, { "$ref": "#/components/schemas/FilterGroup" } ] }, "description": "Nested filters or filter groups." } }, "required": [ "id", "group_operator", "filters" ] }, "FilterCreate": { "oneOf": [ { "$ref": "#/components/schemas/Filter" }, { "$ref": "#/components/schemas/FilterGroupLevel1" } ], "errorMessage": { "oneOf": "Must match either a Filter or a FilterGroup schema." } }, "FilterUpdate": { "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the filter." } }, "required": [ "id" ] }, { "oneOf": [ { "$ref": "#/components/schemas/Filter" }, { "$ref": "#/components/schemas/FilterGroup" } ], "errorMessage": { "oneOf": "Must match either a Filter or a FilterGroup schema." } } ] }, "SortListResponse": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Sort" } } }, "required": [ "list" ] }, "DataRecordV3": { "type": "object", "description": "V3 Data Record format with id and fields separation", "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "errorMessage": { "oneOf": "Field 'id' must be either a string or a number." }, "description": "Record identifier (primary key value)" }, "id_fields": { "type": "object", "description": "Individual primary key field values as object", "additionalProperties": true }, "fields": { "type": "object", "description": "Record fields data (excluding primary key). Undefined when empty.", "additionalProperties": true } }, "required": [ "id" ] }, "DataRecordWithDeletedV3": { "allOf": [ { "$ref": "#/components/schemas/DataRecordV3" }, { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Indicates if the record was deleted" } }, "required": [ "deleted" ] } ] }, "DataListResponseV3": { "type": "object", "description": "V3 Data List Response format", "properties": { "records": { "type": "array", "description": "Array of records for has-many and many-to-many relationships", "items": { "$ref": "#/components/schemas/DataRecordV3" } }, "next": { "type": [ "string", "null" ], "description": "Pagination token for next page" }, "prev": { "type": [ "string", "null" ], "description": "Pagination token for previous page" }, "nestedNext": { "type": [ "string", "null" ], "description": "Nested pagination token for next page" }, "nestedPrev": { "type": [ "string", "null" ], "description": "Nested pagination token for previous page" } } }, "DataInsertRequestV3": { "type": "object", "description": "V3 Data Insert Request format", "properties": { "fields": { "type": "object", "description": "Record fields data", "additionalProperties": true } }, "required": [ "fields" ] }, "DataUpdateRequestV3": { "type": "object", "description": "V3 Data Update Request format", "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "errorMessage": { "oneOf": "Field 'id' must be either a string or a number." }, "description": "Record identifier" }, "fields": { "type": "object", "description": "Record fields data to update", "additionalProperties": true } }, "required": [ "id", "fields" ] }, "DataDeleteRequestV3": { "type": "object", "description": "Single record delete request", "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "errorMessage": { "oneOf": "Field 'id' must be either a string or a number." }, "description": "Record identifier" } }, "required": [ "id" ] }, "DataInsertResponseV3": { "type": "object", "description": "V3 Data Insert Response format", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/DataRecordV3" }, "description": "Array of created records" } }, "required": [ "records" ] }, "DataUpdateResponseV3": { "type": "object", "description": "V3 Data Update Response format", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "errorMessage": { "oneOf": "Field 'id' must be either a string or a number." }, "description": "Updated record identifier" }, "fields": { "type": "object", "description": "Record fields data (excluding primary key). Undefined when empty.", "additionalProperties": true } }, "required": [ "id" ] }, "description": "Array of updated record identifiers" } }, "required": [ "records" ] }, "DataDeleteResponseV3": { "type": "object", "description": "V3 Data Delete Response format", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/DataRecordWithDeletedV3" }, "description": "Array of deleted records" } }, "required": [ "records" ] }, "DataReadResponseV3": { "$ref": "#/components/schemas/DataRecordV3", "description": "V3 Data Read Response format" }, "DataNestedListResponseV3": { "type": "object", "description": "V3 Nested Data List Response format - supports both single record and array responses", "properties": { "records": { "type": "array", "description": "Array of records for has-many and many-to-many relationships", "items": { "$ref": "#/components/schemas/DataRecordV3" } }, "record": { "description": "Single record for belongs-to and one-to-one relationships", "oneOf": [ { "$ref": "#/components/schemas/DataRecordV3" }, { "type": "null" } ], "errorMessage": { "oneOf": "Field 'record' must be either a valid record object or null." } }, "next": { "type": [ "string", "null" ], "description": "Pagination token for next page" }, "prev": { "type": [ "string", "null" ], "description": "Pagination token for previous page" } } }, "BaseRoles": { "type": "string", "description": "Base roles for the user.", "enum": [ "owner", "creator", "editor", "viewer", "commenter", "no-access" ] }, "Workspace": { "type": "object", "description": "Basic workspace information", "properties": { "id": { "type": "string", "description": "Unique identifier for the workspace" }, "title": { "type": "string", "description": "Title of the workspace" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workspace was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workspace was last updated" } }, "required": [ "id", "title", "created_at", "updated_at" ] }, "WorkspaceV3": { "type": "object", "description": "Workspace V3 information with meta data", "properties": { "id": { "type": "string", "description": "Unique identifier for the workspace" }, "title": { "type": "string", "description": "Title of the workspace" }, "org_id": { "type": "string", "description": "Organization identifier (required for cloud, absent for on-prem EE)" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workspace was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workspace was last updated" } }, "required": [ "id", "title", "created_at", "updated_at" ] }, "WorkspaceV3Create": { "type": "object", "description": "Workspace creation request", "properties": { "title": { "type": "string", "description": "Title of the workspace" }, "org_id": { "type": "string", "description": "Organization identifier (required for cloud, absent for on-prem EE)" } }, "required": [ "title" ] }, "WorkspaceV3Update": { "type": "object", "description": "Workspace update request", "properties": { "title": { "type": "string", "description": "Title of the workspace" } }, "required": [ "title" ] }, "WorkspaceV3ListResponse": { "type": "object", "description": "Workspace list response", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceV3" }, "description": "List of workspaces" } }, "required": [ "list" ] }, "WorkspaceWithMembers": { "type": "object", "description": "Workspace information including member details", "allOf": [ { "$ref": "#/components/schemas/Workspace" }, { "type": "object", "properties": { "individual_members": { "type": "object", "properties": { "workspace_members": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceMember" }, "description": "List of workspace members" } }, "required": [ "workspace_members" ] } }, "required": [ "individual_members" ] } ] }, "WorkspaceMember": { "type": "object", "description": "Individual workspace member information", "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the member" }, "user_id": { "type": "string", "description": "Unique identifier for the user" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the user was added to the workspace" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the user was last updated in the workspace" }, "workspace_role": { "$ref": "#/components/schemas/WorkspaceRoles", "description": "Role assigned to the user in the workspace" } }, "required": [ "email", "user_id", "created_at", "updated_at", "workspace_role" ] }, "WorkspaceUser": { "type": "object", "description": "Workspace user information", "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the user" }, "user_id": { "type": "string", "description": "Unique identifier for the user" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the user was added to the workspace" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the user was last updated in the workspace" }, "workspace_role": { "$ref": "#/components/schemas/WorkspaceRoles", "description": "Role assigned to the user in the workspace" } }, "required": [ "email", "user_id", "created_at", "updated_at", "workspace_role" ] }, "WorkspaceUserCreate": { "type": "array", "items": { "type": "object", "oneOf": [ { "title": "Invite User with ID", "required": [ "user_id", "workspace_role" ], "properties": { "user_id": { "type": "string", "description": "Unique identifier for the user (skip if email is provided)" }, "workspace_role": { "$ref": "#/components/schemas/WorkspaceRoles", "description": "Workspace role to assign to the user" } } }, { "title": "Invite User with Email", "required": [ "email", "workspace_role" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the user (skip if user_id is provided)" }, "workspace_role": { "$ref": "#/components/schemas/WorkspaceRoles", "description": "Workspace role to assign to the user" } } } ], "errorMessage": { "oneOf": "Each member must have either a valid 'user_id' or a valid 'email', but not both." }, "description": "An object representing a new workspace user to be created." }, "description": "Array of workspace users to be created." }, "WorkspaceUserUpdate": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Unique identifier for the user" }, "workspace_role": { "$ref": "#/components/schemas/WorkspaceRoles", "description": "New workspace role to assign to the user" } }, "required": [ "user_id", "workspace_role" ], "description": "An object representing updates for an existing workspace user." }, "description": "Array of workspace user updates." }, "WorkspaceUserDelete": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "description": "Unique identifier for the user" } }, "required": [ "user_id" ], "description": "An object representing a workspace user to be deleted." }, "description": "Array of workspace users to be deleted." }, "TeamV3": { "type": "object", "description": "Team information for v3 API", "properties": { "id": { "type": "string", "description": "Unique team identifier", "example": "t12345" }, "title": { "type": "string", "description": "Team name", "example": "Design Team", "maxLength": 150 }, "icon": { "type": [ "string", "null" ], "description": "Team icon (emoji or icon identifier)", "example": "🎨" }, "icon_type": { "oneOf": [ { "type": "string", "enum": [ "EMOJI", "ICON" ] }, { "type": "null" } ], "errorMessage": { "oneOf": "Field 'icon_type' must be either a string or null." }, "description": "Team icon type", "example": "EMOJI" }, "badge_color": { "type": "string", "description": "Team badge color (hex code)", "example": "#FF5733", "pattern": "^#[0-9A-Fa-f]{6}$" }, "members_count": { "type": "integer", "description": "Number of team members", "example": 10 }, "managers_count": { "type": "integer", "description": "Number of team managers", "example": 2 }, "fk_org_id": { "type": "string", "description": "Organization ID (for Cloud Enterprise)" }, "fk_workspace_id": { "type": "string", "description": "Workspace ID (for other plans)" }, "created_at": { "type": "string", "format": "date-time", "description": "Team creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Team last update timestamp" }, "fk_parent_team_id": { "type": [ "string", "null" ], "description": "Parent team ID. Null = root team." }, "depth": { "type": "integer", "description": "Depth in the team tree. Root teams have depth 0.", "example": 1 }, "path": { "type": "string", "description": "Materialized path for efficient ancestor/descendant queries.", "example": "/eng/fe/web" }, "is_member": { "type": "boolean", "description": "Whether the requesting user is a member of this team." }, "managers": { "type": "array", "description": "List of user IDs who are owners/managers of this team.", "items": { "type": "string" } } }, "required": [ "id", "title", "members_count" ] }, "TeamCreateV3Req": { "type": "object", "description": "Team creation request for v3 API", "properties": { "title": { "type": "string", "description": "Team name", "example": "Design Team", "maxLength": 150, "minLength": 1 }, "icon": { "type": [ "string", "null" ], "description": "Team icon (emoji or icon identifier)", "example": "🎨" }, "icon_type": { "oneOf": [ { "type": "string", "enum": [ "EMOJI", "ICON" ] }, { "type": "null" } ], "errorMessage": { "oneOf": "Field 'icon_type' must be either a string or null." }, "description": "Team icon type", "example": "EMOJI" }, "badge_color": { "type": "string", "description": "Team badge color (hex code)", "example": "#FF5733", "pattern": "^#[0-9A-Fa-f]{6}$" }, "members": { "type": "array", "description": "Initial team members", "items": { "$ref": "#/components/schemas/TeamMemberV3" } }, "parent_team_id": { "type": [ "string", "null" ], "description": "Parent team ID. Null or omitted = root team.", "example": "tmd_abc123" } }, "required": [ "title" ] }, "TeamUpdateV3Req": { "type": "object", "description": "Team update request for v3 API", "properties": { "title": { "type": "string", "description": "Updated team name", "example": "Updated Team Name", "maxLength": 150, "minLength": 1 }, "icon": { "type": [ "string", "null" ], "description": "Updated team icon (emoji or icon identifier)", "example": "🛠️" }, "icon_type": { "oneOf": [ { "type": "string", "enum": [ "EMOJI", "ICON" ] }, { "type": "null" } ], "errorMessage": { "oneOf": "Field 'icon_type' must be either a string or null." }, "description": "Team icon type", "example": "EMOJI" }, "badge_color": { "type": "string", "description": "Updated team badge color (hex code)", "example": "#00AEEF", "pattern": "^#[0-9A-Fa-f]{6}$" } } }, "TeamDetailV3": { "type": "object", "description": "Detailed team information for v3 API", "properties": { "title": { "type": "string", "description": "Team name", "example": "Design Team" }, "icon": { "type": [ "string", "null" ], "description": "Team icon (emoji or icon identifier)", "example": "🎨" }, "icon_type": { "oneOf": [ { "type": "string", "enum": [ "EMOJI", "ICON" ] }, { "type": "null" } ], "errorMessage": { "oneOf": "Field 'icon_type' must be either a string or null." }, "description": "Team icon type", "example": "EMOJI" }, "badge_color": { "type": "string", "description": "Team badge color (hex code)", "example": "#FF5733" }, "members": { "type": "array", "description": "Team members", "items": { "$ref": "#/components/schemas/TeamMemberV3Response" } }, "inherited_members": { "type": "array", "description": "Members inherited from ancestor teams", "items": { "$ref": "#/components/schemas/InheritedTeamMemberV3" } } }, "required": [ "title", "members" ] }, "InheritedTeamMemberV3": { "type": "object", "description": "A team member inherited from an ancestor team", "properties": { "user_email": { "type": "string", "description": "Member email address", "example": "user@example.com" }, "user_id": { "type": "string", "description": "Member user ID", "example": "usr_xxxx" }, "team_role": { "type": "string", "enum": ["owner", "member"], "description": "Member role in the ancestor team", "example": "member" }, "inherited_from_team_id": { "type": "string", "description": "ID of the ancestor team this member is inherited from", "example": "tm_xxxx" }, "inherited_from_team_title": { "type": "string", "description": "Title of the ancestor team this member is inherited from", "example": "Engineering" } }, "required": [ "user_email", "user_id", "team_role", "inherited_from_team_id", "inherited_from_team_title" ] }, "TeamMemberV3": { "type": "object", "description": "Team member information for v3 API", "properties": { "user_id": { "type": "string", "description": "User ID", "example": "xxxx" }, "team_role": { "type": "string", "description": "Team role", "enum": [ "member", "owner" ], "example": "member" } }, "required": [ "user_id", "team_role" ] }, "TeamMemberV3Response": { "type": "object", "description": "Team member response for v3 API", "properties": { "user_email": { "type": "string", "format": "email", "description": "User email address", "example": "user@nocodb.com" }, "user_id": { "type": "string", "description": "User ID", "example": "id" }, "team_role": { "type": "string", "description": "Team role", "enum": [ "member", "owner" ], "example": "member" } }, "required": [ "user_email", "user_id", "team_role" ] }, "TeamMembersAddV3Req": { "type": "object", "description": "Add team members request for v3 API", "properties": { "user_id": { "type": "string", "description": "User ID to add", "example": "xxxx" }, "team_role": { "type": "string", "description": "Team role to assign", "enum": [ "member", "owner" ], "example": "member" } }, "required": [ "user_id", "team_role" ] }, "TeamMembersRemoveV3Req": { "type": "object", "description": "Remove team members request for v3 API", "properties": { "user_id": { "type": "string", "description": "User ID to remove", "example": "user123" } }, "required": [ "user_id" ] }, "TeamMembersUpdateV3Req": { "type": "object", "description": "Update team members request for v3 API", "properties": { "user_id": { "type": "string", "description": "User ID to update", "example": "user123" }, "team_role": { "type": "string", "description": "New team role", "enum": [ "member", "owner" ], "example": "member" } }, "required": [ "user_id", "team_role" ] }, "TeamUser": { "type": "object", "description": "Team user relationship", "properties": { "fk_team_id": { "type": "string", "description": "Team ID" }, "fk_user_id": { "type": "string", "description": "User ID" }, "is_owner": { "type": "boolean", "description": "Whether user is team owner" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "fk_team_id", "fk_user_id", "is_owner" ] }, "WorkspaceRoles": { "type": "string", "description": "Workspace roles for the user.", "enum": [ "workspace-level-owner", "workspace-level-creator", "workspace-level-editor", "workspace-level-viewer", "workspace-level-commenter", "workspace-level-no-access" ] }, "WorkspaceTeamCreate": { "type": "object", "description": "Create workspace team request for v3 API", "properties": { "team_id": { "type": "string", "description": "Team ID to add to workspace", "example": "team123" }, "workspace_role": { "type": "string", "description": "Workspace role to assign to the team (creator or lower only)", "enum": [ "workspace-level-creator", "workspace-level-editor", "workspace-level-viewer", "workspace-level-commenter", "workspace-level-no-access" ], "example": "workspace-level-editor" } }, "required": [ "team_id", "workspace_role" ] }, "WorkspaceTeamCreateBulk": { "type": "object", "description": "Bulk create workspace team requests for v3 API", "properties": { "teams": { "type": "array", "description": "Array of teams to add to workspace", "items": { "$ref": "#/components/schemas/WorkspaceTeamCreate" }, "minItems": 1, "example": [ { "team_id": "team123", "workspace_role": "workspace-level-editor" }, { "team_id": "team456", "workspace_role": "workspace-level-viewer" } ] } }, "required": [ "teams" ] }, "WorkspaceTeamUpdate": { "type": "object", "description": "Update workspace team request for v3 API", "properties": { "team_id": { "type": "string", "description": "Team ID to update in workspace", "example": "team123" }, "workspace_role": { "type": "string", "description": "New workspace role for the team (creator or lower only)", "enum": [ "workspace-level-creator", "workspace-level-editor", "workspace-level-viewer", "workspace-level-commenter", "workspace-level-no-access" ], "example": "workspace-level-viewer" } }, "required": [ "team_id", "workspace_role" ] }, "WorkspaceTeamDelete": { "type": "object", "description": "Delete workspace team request for v3 API", "properties": { "team_id": { "type": "string", "description": "Team ID to remove from workspace", "example": "team123" } }, "required": [ "team_id" ] }, "WorkspaceTeamDeleteBulk": { "type": "object", "description": "Bulk delete workspace team requests for v3 API", "properties": { "teams": { "type": "array", "description": "Array of teams to remove from workspace", "items": { "$ref": "#/components/schemas/WorkspaceTeamDelete" }, "minItems": 1, "example": [ { "team_id": "team123" }, { "team_id": "team456" } ] } }, "required": [ "teams" ] }, "BaseTeamCreate": { "type": "object", "description": "Create base team request for v3 API", "properties": { "team_id": { "type": "string", "description": "Team ID to add to base", "example": "team123" }, "base_role": { "type": "string", "description": "Base role to assign to the team (creator or lower only)", "enum": [ "creator", "editor", "viewer", "commenter", "no-access" ], "example": "editor" } }, "required": [ "team_id", "base_role" ] }, "BaseTeamCreateBulk": { "type": "object", "description": "Bulk create base team requests for v3 API", "properties": { "teams": { "type": "array", "description": "Array of teams to add to base", "items": { "$ref": "#/components/schemas/BaseTeamCreate" }, "minItems": 1, "example": [ { "team_id": "team123", "base_role": "editor" }, { "team_id": "team456", "base_role": "viewer" } ] } }, "required": [ "teams" ] }, "BaseTeamUpdate": { "type": "object", "description": "Update base team request for v3 API", "properties": { "team_id": { "type": "string", "description": "Team ID to update in base", "example": "team123" }, "base_role": { "type": "string", "description": "New base role for the team (creator or lower only)", "enum": [ "creator", "editor", "viewer", "commenter", "no-access" ], "example": "viewer" } }, "required": [ "team_id", "base_role" ] }, "BaseTeamDelete": { "type": "object", "description": "Delete base team request for v3 API", "properties": { "team_id": { "type": "string", "description": "Team ID to remove from base", "example": "team123" } }, "required": [ "team_id" ] }, "BaseTeamDeleteBulk": { "type": "object", "description": "Bulk delete base team requests for v3 API", "properties": { "teams": { "type": "array", "description": "Array of teams to remove from base", "items": { "$ref": "#/components/schemas/BaseTeamDelete" }, "minItems": 1, "example": [ { "team_id": "team123" }, { "team_id": "team456" } ] } }, "required": [ "teams" ] }, "ScriptList": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the script." }, "title": { "type": "string", "description": "Title of the script." }, "description": { "type": [ "string", "null" ], "description": "Description of the script." }, "base_id": { "type": "string", "description": "Unique identifier for the base to which this script belongs to." }, "workspace_id": { "type": "string", "description": "Unique identifier for the workspace to which this base belongs to." } }, "required": [ "id", "title", "base_id", "workspace_id" ] } } }, "required": [ "list" ] }, "ScriptCreateReq": { "description": "Script create request body", "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "Title of the script." }, "description": { "type": [ "string", "null" ], "description": "Description of the script." }, "script": { "type": "string", "description": "Script content." }, "config": { "type": "object", "description": "Configuration for the script." }, "meta": { "type": "object", "description": "Metadata for the script." } } }, "ScriptUpdateReq": { "description": "Script update request body", "type": "object", "properties": { "title": { "type": "string", "description": "Title of the script." }, "description": { "type": [ "string", "null" ], "description": "Description of the script." }, "script": { "type": "string", "description": "Script content." }, "config": { "type": "object", "description": "Configuration for the script." }, "meta": { "type": "object", "description": "Metadata for the script." } } }, "ScriptGetResponse": { "description": "Script with additional info", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the script" }, "title": { "type": "string", "description": "Title of the script." }, "description": { "type": [ "string", "null" ], "description": "Description of the script." }, "script": { "type": "string", "description": "Script content." }, "config": { "type": "object", "description": "Configuration for the script." }, "meta": { "type": "object", "description": "Metadata of the script." }, "base_id": { "type": "string", "description": "Unique identifier for the base" }, "workspace_id": { "type": "string", "description": "Unique identifier for the workspace" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the script was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the script was last updated" } }, "required": [ "id", "title", "script", "base_id", "workspace_id", "created_at", "updated_at" ] }, "DashboardListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the dashboard." }, "title": { "type": "string", "description": "Title of the dashboard." }, "description": { "type": ["string", "null"], "description": "Description of the dashboard." }, "base_id": { "type": "string", "description": "Unique identifier for the base." }, "workspace_id": { "type": "string", "description": "Unique identifier for the workspace." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the dashboard was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the dashboard was last updated." }, "created_by": { "type": "string", "description": "User ID of the dashboard creator." } }, "required": ["id", "title", "base_id", "workspace_id", "created_at", "updated_at"] }, "DashboardList": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardListItem" } } }, "required": ["list"] }, "DashboardGetResponse": { "allOf": [ { "$ref": "#/components/schemas/DashboardListItem" }, { "type": "object", "properties": { "widgets": { "type": "array", "items": { "$ref": "#/components/schemas/WidgetRead" }, "description": "List of widgets. Only included when `includeWidgets=true`." } } } ] }, "DashboardDataResponse": { "type": "object", "properties": { "widgets": { "type": "object", "additionalProperties": true, "description": "Map of widget IDs to their data." } }, "required": ["widgets"] }, "WidgetOptionsMetric": { "type": "object", "description": "Options for a metric widget (type=metric).", "properties": { "data_source": { "type": "string", "enum": ["table", "view", "filter"], "description": "Data source type." }, "metric": { "type": "object", "description": "Metric aggregation configuration.", "properties": { "type": { "type": "string", "enum": ["count", "summary"], "description": "'count' counts all rows, 'summary' aggregates a column." }, "field_id": { "type": "string", "description": "Column to aggregate. Required when type is 'summary'." }, "aggregation": { "type": "string", "enum": ["sum", "avg", "count", "min", "max"], "description": "Aggregation function." } }, "required": ["type", "aggregation"] }, "appearance": { "type": "object", "properties": { "type": { "type": "string", "enum": ["default", "filled", "coloured"], "description": "Visual style variant." }, "theme": { "type": "string", "enum": ["gray", "red", "green", "yellow", "pink", "blue", "orange", "maroon", "purple"], "description": "Color theme." } } } } }, "WidgetOptionsPieChart": { "type": "object", "description": "Options for a pie chart widget (type=chart, chart_type=pie).", "properties": { "chart_type": { "type": "string", "enum": ["pie"] }, "data_source": { "type": "string", "enum": ["table", "view", "filter"] }, "data": { "type": "object", "properties": { "category": { "type": "object", "properties": { "field_id": { "type": "string", "description": "Column to group by." }, "order_by": { "type": "string", "enum": ["default", "asc", "desc"] }, "category_limit": { "type": "number", "description": "Max categories (10-50)." }, "include_empty_records": { "type": "boolean" }, "include_others": { "type": "boolean", "description": "Aggregate remaining into 'Others'." } }, "required": ["field_id"] }, "value": { "type": "object", "properties": { "type": { "type": "string", "enum": ["count", "summary"] }, "field_id": { "type": "string", "description": "Column to aggregate. Required when type is 'summary'." }, "aggregation": { "type": "string", "description": "Aggregation function. Required when type is 'summary'." } }, "required": ["type"] } } }, "appearance": { "type": "object", "properties": { "size": { "type": "string", "enum": ["small", "medium", "large"] }, "show_count_in_legend": { "type": "boolean" }, "show_percentage_on_chart": { "type": "boolean" }, "legend_position": { "type": "string", "enum": ["top", "right", "bottom", "left", "none"] }, "color_schema": { "type": "string", "enum": ["default", "classic", "vibrant", "pastel", "earth", "monoBlue", "custom"] }, "custom_color_schema": { "type": "array", "items": { "type": "object", "properties": { "color": { "type": "string" }, "label": { "type": "string" } } } } } } }, "required": ["chart_type"] }, "WidgetOptionsDonutChart": { "type": "object", "description": "Options for a donut chart widget (type=chart, chart_type=donut). Same structure as pie chart.", "properties": { "chart_type": { "type": "string", "enum": ["donut"] }, "data_source": { "type": "string", "enum": ["table", "view", "filter"] }, "data": { "type": "object", "properties": { "category": { "type": "object", "properties": { "field_id": { "type": "string" }, "order_by": { "type": "string", "enum": ["default", "asc", "desc"] }, "category_limit": { "type": "number" }, "include_empty_records": { "type": "boolean" }, "include_others": { "type": "boolean" } }, "required": ["field_id"] }, "value": { "type": "object", "properties": { "type": { "type": "string", "enum": ["count", "summary"] }, "field_id": { "type": "string" }, "aggregation": { "type": "string" } }, "required": ["type"] } } }, "appearance": { "type": "object", "properties": { "size": { "type": "string", "enum": ["small", "medium", "large"] }, "show_count_in_legend": { "type": "boolean" }, "show_percentage_on_chart": { "type": "boolean" }, "legend_position": { "type": "string", "enum": ["top", "right", "bottom", "left", "none"] }, "color_schema": { "type": "string", "enum": ["default", "classic", "vibrant", "pastel", "earth", "monoBlue", "custom"] }, "custom_color_schema": { "type": "array", "items": { "type": "object", "properties": { "color": { "type": "string" }, "label": { "type": "string" } } } } } } }, "required": ["chart_type"] }, "WidgetOptionsBarChart": { "type": "object", "description": "Options for a bar chart widget (type=chart, chart_type=bar).", "properties": { "chart_type": { "type": "string", "enum": ["bar"] }, "data_source": { "type": "string", "enum": ["table", "view", "filter"] }, "data": { "type": "object", "properties": { "x_axis": { "type": "object", "description": "X-axis (category) configuration.", "properties": { "field_id": { "type": "string", "description": "X-axis grouping field." }, "sort_by": { "type": "string", "enum": ["x_axis", "y_axis"], "description": "Sort by x-axis labels or y-axis values." }, "order_by": { "type": "string", "enum": ["default", "asc", "desc"] }, "include_empty_records": { "type": "boolean" }, "include_others": { "type": "boolean" }, "category_limit": { "type": "number", "description": "Max categories (10-50)." } }, "required": ["field_id"] }, "y_axis": { "type": "object", "description": "Y-axis (value) configuration.", "properties": { "start_at_zero": { "type": "boolean" }, "fields": { "type": "array", "description": "Fields to aggregate on the y-axis.", "items": { "type": "object", "properties": { "field_id": { "type": "string" }, "aggregation": { "type": "string" } }, "required": ["field_id", "aggregation"] } }, "group_by": { "type": ["string", "null"], "description": "Optional secondary grouping field ID." } } } } }, "appearance": { "type": "object", "properties": { "size": { "type": "string", "enum": ["small", "medium", "large"] }, "show_count_in_legend": { "type": "boolean" }, "show_value_in_chart": { "type": "boolean" }, "legend_position": { "type": "string", "enum": ["top", "right", "bottom", "left", "none"] }, "color_schema": { "type": "string", "enum": ["default", "classic", "vibrant", "pastel", "earth", "monoBlue", "custom"] } } } }, "required": ["chart_type"] }, "WidgetOptionsLineChart": { "type": "object", "description": "Options for a line chart widget (type=chart, chart_type=line). Same data structure as bar chart with additional line-specific appearance options.", "properties": { "chart_type": { "type": "string", "enum": ["line"] }, "data_source": { "type": "string", "enum": ["table", "view", "filter"] }, "data": { "type": "object", "properties": { "x_axis": { "type": "object", "properties": { "field_id": { "type": "string" }, "sort_by": { "type": "string", "enum": ["x_axis", "y_axis"] }, "order_by": { "type": "string", "enum": ["default", "asc", "desc"] }, "include_empty_records": { "type": "boolean" }, "include_others": { "type": "boolean" }, "category_limit": { "type": "number" } }, "required": ["field_id"] }, "y_axis": { "type": "object", "properties": { "start_at_zero": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string" }, "aggregation": { "type": "string" } }, "required": ["field_id", "aggregation"] } }, "group_by": { "type": ["string", "null"] } } } } }, "appearance": { "type": "object", "properties": { "size": { "type": "string", "enum": ["small", "medium", "large"] }, "smooth_lines": { "type": "boolean", "description": "Smooth curve vs straight line segments." }, "plot_data_points": { "type": "boolean", "description": "Show dots at data points." }, "show_count_in_legend": { "type": "boolean" }, "show_value_in_chart": { "type": "boolean" }, "legend_position": { "type": "string", "enum": ["top", "right", "bottom", "left", "none"] }, "color_schema": { "type": "string", "enum": ["default", "classic", "vibrant", "pastel", "earth", "monoBlue", "custom"] } } } }, "required": ["chart_type"] }, "WidgetOptionsScatter": { "type": "object", "description": "Options for a scatter plot widget (type=chart, chart_type=scatter). Same data structure as bar chart.", "properties": { "chart_type": { "type": "string", "enum": ["scatter"] }, "data_source": { "type": "string", "enum": ["table", "view", "filter"] }, "data": { "type": "object", "properties": { "x_axis": { "type": "object", "properties": { "field_id": { "type": "string" }, "sort_by": { "type": "string", "enum": ["x_axis", "y_axis"] }, "order_by": { "type": "string", "enum": ["default", "asc", "desc"] }, "include_empty_records": { "type": "boolean" }, "include_others": { "type": "boolean" }, "category_limit": { "type": "number" } }, "required": ["field_id"] }, "y_axis": { "type": "object", "properties": { "start_at_zero": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "field_id": { "type": "string" }, "aggregation": { "type": "string" } }, "required": ["field_id", "aggregation"] } }, "group_by": { "type": ["string", "null"] } } } } }, "appearance": { "type": "object", "properties": { "size": { "type": "string", "enum": ["small", "medium", "large"] }, "show_count_in_legend": { "type": "boolean" }, "show_value_in_chart": { "type": "boolean" }, "legend_position": { "type": "string", "enum": ["top", "right", "bottom", "left", "none"] }, "color_schema": { "type": "string", "enum": ["default", "classic", "vibrant", "pastel", "earth", "monoBlue", "custom"] } } } }, "required": ["chart_type"] }, "WidgetOptionsText": { "type": "object", "description": "Options for a text widget (type=text). Formatting is nested inside appearance.", "properties": { "content": { "type": "string", "description": "Text content (plain text or markdown)." }, "type": { "type": "string", "enum": ["markdown", "text"], "description": "Text rendering mode." }, "appearance": { "type": "object", "properties": { "formatting": { "type": "object", "description": "Text formatting options.", "properties": { "horizontal_align": { "type": "string", "enum": ["flex-start", "center", "flex-end"] }, "vertical_align": { "type": "string", "enum": ["flex-start", "center", "flex-end"] }, "bold": { "type": "boolean" }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strikethrough": { "type": "boolean" } } }, "font": { "type": "object", "description": "Font settings (only for type=text).", "properties": { "family": { "type": "string" }, "weight": { "type": "number", "enum": [100, 200, 300, 400, 500, 600, 700, 800, 900] }, "size": { "type": "number", "description": "Font size in pixels." }, "line_height": { "type": "number", "description": "Line height multiplier." } } }, "color": { "type": "string", "description": "Hex color (only for type=text)." } } } } }, "WidgetOptionsIframe": { "type": "object", "description": "Options for an iframe widget (type=iframe).", "properties": { "url": { "type": "string", "description": "URL to embed." }, "allow_fullscreen": { "type": "boolean", "description": "Whether to allow fullscreen." } } }, "WidgetRead": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the widget." }, "title": { "type": "string", "description": "Title of the widget." }, "description": { "type": ["string", "null"], "description": "Description of the widget." }, "dashboard_id": { "type": "string", "description": "Unique identifier for the parent dashboard." }, "type": { "type": "string", "enum": ["chart", "metric", "text", "iframe"], "description": "Type of the widget." }, "options": { "description": "Widget configuration. Structure depends on widget type. See WidgetOptions* schemas.", "oneOf": [ { "$ref": "#/components/schemas/WidgetOptionsMetric" }, { "$ref": "#/components/schemas/WidgetOptionsPieChart" }, { "$ref": "#/components/schemas/WidgetOptionsDonutChart" }, { "$ref": "#/components/schemas/WidgetOptionsBarChart" }, { "$ref": "#/components/schemas/WidgetOptionsLineChart" }, { "$ref": "#/components/schemas/WidgetOptionsScatter" }, { "$ref": "#/components/schemas/WidgetOptionsText" }, { "$ref": "#/components/schemas/WidgetOptionsIframe" } ] }, "order": { "type": ["number", "null"], "description": "Display order of the widget." }, "position": { "type": ["object", "null"], "properties": { "x": { "type": "number", "description": "Column position of the widget on the dashboard grid (0-indexed, left to right). e.g. 0 means the first column, 6 means starting at the 7th column." }, "y": { "type": "number", "description": "Row position of the widget on the dashboard grid (0-indexed, top to bottom). e.g. 0 means the first row, 4 means starting at the 5th row." }, "w": { "type": "number", "description": "Width of the widget in grid columns. e.g. 6 means the widget spans 6 columns (half of a 12-column grid)." }, "h": { "type": "number", "description": "Height of the widget in grid rows. e.g. 4 means the widget spans 4 rows tall." } }, "description": "Position and size of the widget on the dashboard grid." }, "table_id": { "type": ["string", "null"], "description": "Unique identifier for the associated table." }, "view_id": { "type": ["string", "null"], "description": "Unique identifier for the associated view." }, "error": { "type": "boolean", "description": "Whether the widget has a configuration error." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the widget was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the widget was last updated." } }, "required": ["id", "title", "dashboard_id", "type", "created_at", "updated_at"] }, "WidgetList": { "type": "object", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/WidgetRead" } } }, "required": ["list"] }, "DashboardCreateReq": { "description": "Dashboard create request body", "type": "object", "required": ["title"], "properties": { "title": { "type": "string", "description": "Title of the dashboard." }, "description": { "type": ["string", "null"], "description": "Description of the dashboard." } } }, "DashboardUpdateReq": { "description": "Dashboard update request body", "type": "object", "properties": { "title": { "type": "string", "description": "Title of the dashboard." }, "description": { "type": ["string", "null"], "description": "Description of the dashboard." } } }, "WidgetCreateReq": { "description": "Widget create request body", "type": "object", "required": ["title", "type"], "properties": { "title": { "type": "string", "description": "Title of the widget." }, "description": { "type": ["string", "null"], "description": "Description of the widget." }, "type": { "type": "string", "enum": ["chart", "metric", "text", "iframe"], "description": "Type of the widget." }, "options": { "description": "Widget configuration. Structure depends on widget type.", "oneOf": [ { "$ref": "#/components/schemas/WidgetOptionsMetric" }, { "$ref": "#/components/schemas/WidgetOptionsPieChart" }, { "$ref": "#/components/schemas/WidgetOptionsDonutChart" }, { "$ref": "#/components/schemas/WidgetOptionsBarChart" }, { "$ref": "#/components/schemas/WidgetOptionsLineChart" }, { "$ref": "#/components/schemas/WidgetOptionsScatter" }, { "$ref": "#/components/schemas/WidgetOptionsText" }, { "$ref": "#/components/schemas/WidgetOptionsIframe" } ] }, "position": { "type": "object", "description": "Position and size of the widget on the dashboard grid.", "properties": { "x": { "type": "number", "description": "Column position of the widget on the dashboard grid (0-indexed, left to right). e.g. 0 means the first column, 6 means starting at the 7th column." }, "y": { "type": "number", "description": "Row position of the widget on the dashboard grid (0-indexed, top to bottom). e.g. 0 means the first row, 4 means starting at the 5th row." }, "w": { "type": "number", "description": "Width of the widget in grid columns. e.g. 6 means the widget spans 6 columns (half of a 12-column grid)." }, "h": { "type": "number", "description": "Height of the widget in grid rows. e.g. 4 means the widget spans 4 rows tall." } } }, "table_id": { "type": ["string", "null"], "description": "Unique identifier for the associated table." }, "view_id": { "type": ["string", "null"], "description": "Unique identifier for the associated view." } } }, "WidgetUpdateReq": { "description": "Widget update request body", "type": "object", "properties": { "title": { "type": "string", "description": "Title of the widget." }, "description": { "type": ["string", "null"], "description": "Description of the widget." }, "options": { "description": "Widget configuration. Structure depends on widget type.", "oneOf": [ { "$ref": "#/components/schemas/WidgetOptionsMetric" }, { "$ref": "#/components/schemas/WidgetOptionsPieChart" }, { "$ref": "#/components/schemas/WidgetOptionsDonutChart" }, { "$ref": "#/components/schemas/WidgetOptionsBarChart" }, { "$ref": "#/components/schemas/WidgetOptionsLineChart" }, { "$ref": "#/components/schemas/WidgetOptionsScatter" }, { "$ref": "#/components/schemas/WidgetOptionsText" }, { "$ref": "#/components/schemas/WidgetOptionsIframe" } ] }, "order": { "type": "number", "description": "Display order of the widget." }, "position": { "type": "object", "description": "Position and size of the widget on the dashboard grid.", "properties": { "x": { "type": "number", "description": "Column position of the widget on the dashboard grid (0-indexed, left to right). e.g. 0 means the first column, 6 means starting at the 7th column." }, "y": { "type": "number", "description": "Row position of the widget on the dashboard grid (0-indexed, top to bottom). e.g. 0 means the first row, 4 means starting at the 5th row." }, "w": { "type": "number", "description": "Width of the widget in grid columns. e.g. 6 means the widget spans 6 columns (half of a 12-column grid)." }, "h": { "type": "number", "description": "Height of the widget in grid rows. e.g. 4 means the widget spans 4 rows tall." } } }, "table_id": { "type": ["string", "null"], "description": "Unique identifier for the associated table." }, "view_id": { "type": ["string", "null"], "description": "Unique identifier for the associated view." } } }, "ApiTokenV3": { "type": "object", "properties": { "id": { "type": "integer", "description": "Token ID", "example": 5 }, "title": { "type": "string", "description": "Token title / description", "example": "Github Integration" }, "created_at": { "type": "string", "format": "date-time", "description": "Token creation timestamp", "example": "2025-12-30 15:17:24+00:00" }, "updated_at": { "type": "string", "format": "date-time", "description": "Token last update timestamp", "example": "2025-12-30 15:17:24+00:00" } }, "required": [ "id", "title", "created_at", "updated_at" ] }, "ApiTokenWithTokenV3": { "allOf": [ { "$ref": "#/components/schemas/ApiTokenV3" }, { "type": "object", "properties": { "token": { "type": "string", "description": "The actual API token value (only returned on creation)", "example": "wxAFzFO2wwOf9ozVRjragBJ7KPWMaW2OGpklGqHh" } }, "required": [ "token" ] } ] }, "DocumentCreate": { "type": "object", "description": "Request body for creating a document.", "properties": { "title": { "type": "string", "description": "Title of the document. Defaults to 'Untitled' if omitted." }, "content": { "type": "object", "description": "rich-text JSON document content." }, "meta": { "type": "object", "description": "Arbitrary metadata (icon, cover image, settings, etc.)." }, "parent_id": { "type": "string", "nullable": true, "description": "Parent document ID. null or omitted for root-level documents." } } }, "DocumentUpdate": { "type": "object", "description": "Request body for updating a document.", "required": [ "version" ], "properties": { "title": { "type": "string", "description": "Updated title." }, "content": { "type": "object", "description": "Updated rich-text JSON document content." }, "meta": { "type": "object", "description": "Updated metadata." }, "version": { "type": "integer", "description": "Current document version for optimistic concurrency control. Must match the server's version." } } }, "DocumentReorder": { "type": "object", "description": "Request body for reordering or moving a document. At least one of order or parent_id must be provided.", "properties": { "order": { "type": "number", "description": "New sort order value (float). Compute midpoint between neighbors for fractional ordering." }, "parent_id": { "type": "string", "nullable": true, "description": "New parent document ID. null to move to root. Omit to keep current parent." } } }, "Document": { "type": "object", "description": "Full document response (includes content).", "required": [ "id", "base_id", "title", "content", "order", "parent_id", "has_children", "version", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Unique document identifier." }, "base_id": { "type": "string", "description": "Base this document belongs to." }, "title": { "type": "string", "description": "Document title." }, "content": { "type": "object", "description": "rich-text JSON document content." }, "meta": { "type": "object", "description": "Document metadata (icon, cover, lock, settings)." }, "order": { "type": "number", "description": "Sort order among siblings." }, "parent_id": { "type": "string", "nullable": true, "description": "Parent document ID. null for root documents." }, "has_children": { "type": "boolean", "description": "Whether this document has child documents." }, "version": { "type": "integer", "description": "Optimistic concurrency version counter." }, "comment_count": { "type": "integer", "description": "Number of comments on this document." }, "created_by": { "type": "string", "description": "User ID of the document creator." }, "updated_by": { "type": "string", "description": "User ID of the last editor." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp." } } }, "DocumentListItem": { "type": "object", "description": "Document summary returned in list responses. Excludes the `content` field.", "required": [ "id", "base_id", "title", "order", "parent_id", "has_children", "version", "created_at", "updated_at" ], "properties": { "id": { "type": "string" }, "base_id": { "type": "string" }, "title": { "type": "string" }, "meta": { "type": "object" }, "order": { "type": "number" }, "parent_id": { "type": "string", "nullable": true }, "has_children": { "type": "boolean" }, "version": { "type": "integer" }, "comment_count": { "type": "integer" }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DocumentListResponse": { "type": "object", "description": "List of documents.", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentListItem" } } }, "required": [ "list" ] }, "Comment": { "type": "object", "description": "A comment on a record.", "properties": { "id": { "type": "string", "description": "Unique comment ID.", "example": "cmt_abc123" }, "record_id": { "type": "string", "description": "Record ID this comment belongs to.", "example": "1" }, "table_id": { "type": "string", "description": "Table ID this comment belongs to.", "example": "mrc5unwjdov67vr" }, "comment": { "type": "string", "description": "Comment text (supports markdown).", "example": "This is a comment", "maxLength": 10000 }, "created_by": { "type": "string", "description": "User ID of the comment creator.", "example": "usr_abc123" }, "resolved_by": { "type": [ "string", "null" ], "description": "User ID who resolved this comment (null if not resolved).", "example": null }, "parent_comment_id": { "type": [ "string", "null" ], "description": "Parent comment ID for threaded comments.", "example": null }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "example": "2024-01-15T10:30:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp.", "example": "2024-01-15T10:30:00.000Z" } } }, "CommentCreateRequest": { "type": "object", "description": "Request body for creating a comment.", "properties": { "comment": { "type": "string", "description": "Comment text (supports markdown).", "example": "This is a comment", "maxLength": 10000 } }, "required": [ "comment" ] }, "CommentUpdateRequest": { "type": "object", "description": "Request body for updating a comment.", "properties": { "comment": { "type": "string", "description": "Updated comment text.", "example": "Updated comment", "maxLength": 10000 } }, "required": [ "comment" ] }, "CommentListResponse": { "type": "object", "description": "List of comments for a record.", "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } }, "required": [ "list" ] }, "FormFieldConfig": { "type": "object", "description": "Form-specific configuration for a field.", "properties": { "alias": { "type": "string", "description": "Display label override for the field." }, "description": { "type": "string", "description": "Help text shown below the field." }, "required": { "type": "boolean", "description": "Whether the field is required." }, "allow_scanner_input": { "type": "boolean", "description": "Whether to show QR/barcode scanner input." }, "is_list": { "type": "boolean", "description": "Whether to display as list layout." }, "is_limit_option": { "type": "boolean", "description": "Whether to limit selectable options." }, "validators": { "type": "array", "description": "List of validators for the field.", "items": { "$ref": "#/components/schemas/FormFieldValidator" } } } }, "FormFieldValidator": { "type": "object", "description": "Validator configuration for a form field.", "properties": { "type": { "type": "string", "enum": [ "required", "regex", "minValue", "maxValue", "minLength", "maxLength", "email", "url", "custom" ], "description": "Type of validation to apply." }, "value": { "type": [ "string", "integer", "null" ], "description": "Validator parameter value (e.g., min/max number, pattern string)." }, "message": { "type": "string", "description": "Custom error message for validation failure." }, "regex": { "type": "string", "description": "Regular expression pattern (for regex validator type)." } } }, "WorkflowList": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the workflow" }, "title": { "type": "string", "description": "Title of the workflow" }, "description": { "type": ["string", "null"], "description": "Description of the workflow" }, "base_id": { "type": "string", "description": "Unique identifier for the base" }, "workspace_id": { "type": "string", "description": "Unique identifier for the workspace" }, "enabled": { "type": "boolean", "description": "Whether the workflow is enabled" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workflow was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workflow was last updated" }, "created_by": { "type": "string", "description": "User ID of the creator" }, "updated_by": { "type": "string", "description": "User ID of the last updater" } }, "required": ["id", "title", "base_id", "workspace_id"] } } }, "required": ["list"] }, "WorkflowNodePort": { "description": "Port definition for a workflow node (input/output connection point)", "type": "object", "properties": { "id": { "type": "string", "description": "Unique port identifier within the node (e.g. 'true', 'false', 'body', 'output')" }, "label": { "type": "string", "description": "Display label for the port (e.g. 'True', 'False', 'For Each Item')" }, "direction": { "type": "string", "enum": ["input", "output"], "description": "Whether this port accepts incoming or outgoing connections" }, "order": { "type": "number", "description": "Display order of the port" } }, "required": ["id", "direction"] }, "WorkflowVariableDefinition": { "description": "Variable definition describing an input or output of a workflow node", "type": "object", "properties": { "key": { "type": "string", "description": "Expression reference key (e.g. 'fields.Title', 'meta.id')" }, "name": { "type": "string", "description": "Human-readable display name" }, "type": { "type": "string", "enum": ["string", "number", "integer", "boolean", "object", "array", "date", "datetime"], "description": "Data type of the variable" }, "groupKey": { "type": "string", "enum": ["meta", "fields", "iteration"], "description": "Grouping category — 'meta' for system fields, 'fields' for user data, 'iteration' for loop variables" }, "isArray": { "type": "boolean", "description": "Whether this variable represents an array of values" }, "extra": { "type": "object", "description": "Additional metadata (entity references, icons, UI type hints)", "properties": { "entity_id": { "type": "string", "description": "ID of the referenced entity (column, table, or view)" }, "entity": { "type": "string", "enum": ["column", "table", "view"], "description": "Type of the referenced entity" }, "icon": { "type": "string", "description": "Icon identifier for display" }, "uiType": { "type": "string", "description": "UI data type hint" }, "description": { "type": "string", "description": "Description of the variable" }, "port": { "type": "string", "description": "Port ID this variable belongs to (for multi-port nodes like If/Iterate)" } } }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVariableDefinition" }, "description": "Nested variable definitions for object/array types" } }, "required": ["key", "name", "type"] }, "WorkflowNodeData": { "description": "Data payload of a workflow node containing its configuration and metadata", "type": "object", "properties": { "title": { "type": "string", "description": "Display title of the node" }, "description": { "type": "string", "description": "Description of the node" }, "config": { "type": "object", "description": "Node-specific configuration. Structure varies by node type — e.g. table ID for record triggers, conditions array for If nodes, duration/unit for Delay nodes, array expression for Iterate nodes" }, "testResult": { "$ref": "#/components/schemas/WorkflowNodeExecutionResult", "description": "Result from the most recent test execution of this node (only present on draft nodes)" }, "inputVariables": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVariableDefinition" }, "description": "Input variable definitions for this node" }, "outputVariables": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVariableDefinition" }, "description": "Output variable definitions produced by this node" } }, "required": ["title", "config"] }, "WorkflowNode": { "description": "A node in the workflow graph representing a trigger, action, or flow control operation. Node type IDs follow the pattern '{provider}.{category}.{name}' (e.g. 'nocodb.trigger.after_insert', 'core.flow.if', 'slack.send_message').", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this node within the workflow" }, "type": { "type": "string", "description": "Node type identifier determining behavior and available configuration. Categories: trigger (start events), action (operations), flow (control flow). Examples: 'nocodb.trigger.after_insert', 'core.action.http', 'core.flow.if', 'core.flow.iterate', 'core.flow.delay', 'slack.send_message', 'ai.action.generate-text'", "examples": [ "nocodb.trigger.after_insert", "nocodb.trigger.after_update", "nocodb.trigger.after_delete", "nocodb.trigger.form_submitted", "nocodb.trigger.record_enters_view", "nocodb.trigger.record_matches_condition", "core.trigger.webhook", "core.trigger.manual", "core.trigger.cron", "core.flow.if", "core.flow.iterate", "core.flow.delay", "core.flow.wait-until", "core.action.http", "core.action.send-email", "nocodb.create_record", "nocodb.update_record", "nocodb.find_record", "nocodb.list_records", "nocodb.delete_record", "nocodb.run_script", "ai.action.generate-text", "ai.action.generate-structured", "slack.send_message", "google.send_email", "twilio.action.send_sms", "twilio.action.call_phone", "twilio.action.send_whatsapp", "github.trigger", "outlook.send_email", "google_calendar.trigger.new_event", "hubspot_crm.action.contact_create", "hubspot_crm.action.deal_create" ] }, "position": { "type": "object", "description": "Position of the node on the workflow canvas", "properties": { "x": { "type": "number", "description": "X coordinate" }, "y": { "type": "number", "description": "Y coordinate" } }, "required": ["x", "y"] }, "data": { "$ref": "#/components/schemas/WorkflowNodeData" }, "targetPosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the incoming connection handle" }, "sourcePosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the outgoing connection handle" } }, "required": ["id", "type", "position", "data"] }, "WorkflowEdge": { "description": "A directed connection between two workflow nodes defining execution flow. For conditional/loop nodes, sourcePortId determines which branch is followed.", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this edge" }, "source": { "type": "string", "description": "ID of the source node" }, "target": { "type": "string", "description": "ID of the target node" }, "animated": { "type": "boolean", "description": "Whether the edge should be animated in the UI" }, "label": { "type": "string", "description": "Display label on the edge (e.g. 'True', 'False', 'For Each Item')" }, "sourcePortId": { "type": "string", "description": "Output port ID on the source node. Used for branching — e.g. 'true'/'false' for If nodes, 'body'/'output' for Iterate nodes" }, "targetPortId": { "type": "string", "description": "Input port ID on the target node" } }, "required": ["id", "source", "target"] }, "WorkflowNodeExecutionResult": { "description": "Result of executing a single workflow node", "type": "object", "properties": { "nodeId": { "type": "string", "description": "ID of the node that was executed" }, "nodeTitle": { "type": "string", "description": "Title of the node at execution time" }, "status": { "type": "string", "enum": ["pending", "running", "success", "error", "skipped"], "description": "Execution status of the node" }, "input": { "type": "object", "description": "Interpolated input data passed to the node" }, "output": { "type": "object", "description": "Output data produced by the node" }, "error": { "type": "string", "description": "Error message if the node failed" }, "startTime": { "type": "number", "description": "Execution start time (Unix timestamp in milliseconds)" }, "endTime": { "type": "number", "description": "Execution end time (Unix timestamp in milliseconds)" }, "nextNode": { "type": "string", "description": "Explicit next node title for routing (used by conditional nodes)" }, "logs": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "string", "enum": ["info", "warn", "error"], "description": "Log level" }, "message": { "type": "string", "description": "Log message" }, "ts": { "type": "number", "description": "Timestamp of the log entry" }, "data": { "type": "object", "description": "Additional structured log data" } }, "required": ["level", "message"] }, "description": "Execution log entries from the node" }, "metrics": { "type": "object", "description": "Execution metrics (e.g. execution time, condition count)" }, "inputVariables": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVariableDefinition" }, "description": "Input variable definitions at execution time" }, "outputVariables": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVariableDefinition" }, "description": "Output variable definitions at execution time" }, "loopContext": { "type": "object", "description": "Loop context for iterate nodes — contains loop state, body port, and exit port", "properties": { "state": { "type": "object", "description": "Serializable loop state", "properties": { "items": { "type": "array", "items": {}, "description": "Array of items being iterated" }, "currentIndex": { "type": "number", "description": "Current iteration index (0-based)" }, "totalItems": { "type": "number", "description": "Total number of items to iterate" } } }, "bodyPort": { "type": "string", "description": "Port ID for the loop body (e.g. 'body')" }, "exitPort": { "type": "string", "description": "Port ID for the loop exit (e.g. 'output')" } } }, "isStale": { "type": "boolean", "description": "Whether this test result is stale (node config changed since last test)" } }, "required": ["nodeId", "nodeTitle", "status", "startTime"] }, "WorkflowLoopData": { "description": "Execution data for a single iterate/loop node across all its iterations", "type": "object", "properties": { "nodeId": { "type": "string", "description": "ID of the iterate node" }, "nodeTitle": { "type": "string", "description": "Title of the iterate node" }, "totalIterations": { "type": "number", "description": "Total number of iterations executed" }, "iterations": { "type": "object", "description": "Map of iteration index to iteration data. Each iteration contains its own nodeResults and optional nested childLoops.", "additionalProperties": { "type": "object", "properties": { "iterationIndex": { "type": "number", "description": "0-based iteration index" }, "nodeResults": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNodeExecutionResult" }, "description": "Node execution results within this iteration" }, "childLoops": { "type": "object", "description": "Nested loop data for loops-within-loops", "additionalProperties": { "$ref": "#/components/schemas/WorkflowLoopData" } } } } } }, "required": ["nodeId", "nodeTitle", "totalIterations"] }, "WorkflowExecutionData": { "description": "Full execution state of a workflow run, including all node results, loop data, and pause/resume information", "type": "object", "properties": { "id": { "type": "string", "description": "Execution state ID" }, "workflowId": { "type": "string", "description": "ID of the workflow being executed" }, "status": { "type": "string", "enum": ["running", "waiting", "completed", "error", "cancelled", "skipped"], "description": "Overall execution status" }, "startTime": { "type": "number", "description": "Execution start time (Unix timestamp in milliseconds)" }, "endTime": { "type": "number", "description": "Execution end time (Unix timestamp in milliseconds)" }, "nodeResults": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNodeExecutionResult" }, "description": "Ordered list of node execution results" }, "currentNodeId": { "type": "string", "description": "ID of the currently executing node (when status is 'running')" }, "triggerData": { "type": "object", "description": "Data that triggered the workflow execution" }, "triggerNodeTitle": { "type": "string", "description": "Title of the trigger node" }, "loops": { "type": "object", "description": "Loop execution data keyed by iterate node ID", "additionalProperties": { "$ref": "#/components/schemas/WorkflowLoopData" } }, "pausedAt": { "type": "number", "description": "Timestamp when execution was paused (for delay/wait-until nodes)" }, "resumeAt": { "type": "number", "description": "Timestamp when execution should resume" }, "nextNodeId": { "type": "string", "description": "ID of the node to resume execution from" } }, "required": ["id", "workflowId", "status", "startTime", "nodeResults"] }, "WorkflowDraft": { "description": "Draft version of workflow nodes and edges with unpublished changes. Must be published via the publish endpoint for changes to take effect.", "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNode" }, "description": "Draft workflow node definitions" }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEdge" }, "description": "Draft connections between nodes" } } }, "WorkflowNodeDataRequest": { "description": "Data payload for a workflow node in create/update requests. Does not accept testResult — that field is server-managed.", "type": "object", "properties": { "title": { "type": "string", "description": "Display title of the node" }, "description": { "type": "string", "description": "Description of the node" }, "config": { "type": "object", "description": "Node-specific configuration. Structure varies by node type — e.g. table ID for record triggers, conditions array for If nodes, duration/unit for Delay nodes, array expression for Iterate nodes" }, "inputVariables": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVariableDefinition" }, "description": "Input variable definitions for this node" }, "outputVariables": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowVariableDefinition" }, "description": "Output variable definitions produced by this node" } }, "required": ["title", "config"] }, "WorkflowNodeRequest": { "description": "A workflow node in create/update requests. Same as WorkflowNode but node data does not accept testResult.", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for this node within the workflow" }, "type": { "type": "string", "description": "Node type identifier determining behavior and available configuration." }, "position": { "type": "object", "description": "Position of the node on the workflow canvas", "properties": { "x": { "type": "number", "description": "X coordinate" }, "y": { "type": "number", "description": "Y coordinate" } }, "required": ["x", "y"] }, "data": { "$ref": "#/components/schemas/WorkflowNodeDataRequest" }, "targetPosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the incoming connection handle" }, "sourcePosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the outgoing connection handle" } }, "required": ["id", "type", "position", "data"] }, "WorkflowDraftRequest": { "description": "Draft version of workflow nodes and edges for create/update requests. Node data does not accept testResult.", "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNodeRequest" }, "description": "Draft workflow node definitions" }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEdge" }, "description": "Draft connections between nodes" } } }, "WorkflowOptions": { "description": "Workflow options including execution configuration and display settings", "type": "object", "properties": { "run_as": { "type": "object", "description": "Execution identity — determines the permissions context under which the workflow runs", "properties": { "type": { "type": "string", "enum": ["service_account", "role", "user"], "description": "Identity type. 'service_account' runs as a system user with creator role, 'role' runs with a specified role, 'user' runs as a specific user" }, "value": { "type": "string", "description": "Role name (when type='role') or user ID (when type='user'). Not required for 'service_account'" } }, "required": ["type"] }, "icon": { "type": "string", "description": "Custom emoji icon for the workflow" } } }, "WorkflowGetResponse": { "description": "Workflow with full details including nodes and edges", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the workflow" }, "title": { "type": "string", "description": "Title of the workflow" }, "description": { "type": ["string", "null"], "description": "Description of the workflow" }, "base_id": { "type": "string", "description": "Unique identifier for the base" }, "workspace_id": { "type": "string", "description": "Unique identifier for the workspace" }, "enabled": { "type": "boolean", "description": "Whether the workflow is enabled" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNode" }, "description": "Published workflow node definitions" }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEdge" }, "description": "Published connections between workflow nodes" }, "draft": { "$ref": "#/components/schemas/WorkflowDraft", "description": "Draft configuration with unpublished changes. Null when no draft exists." }, "options": { "$ref": "#/components/schemas/WorkflowOptions", "description": "Workflow options including execution configuration and display settings" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workflow was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the workflow was last updated" }, "created_by": { "type": "string", "description": "User ID of the creator" }, "updated_by": { "type": "string", "description": "User ID of the last updater" } }, "required": ["id", "title", "base_id", "workspace_id", "created_at", "updated_at"] }, "WorkflowExecuteReq": { "description": "Workflow execute request body", "type": "object", "properties": { "trigger_data": { "type": "object", "description": "Data to pass to the workflow trigger." } } }, "WorkflowTestNodeReq": { "description": "Workflow test node request body", "type": "object", "required": ["node_id"], "properties": { "node_id": { "type": "string", "description": "Unique identifier of the node to test." }, "test_trigger_data": { "type": "object", "description": "Optional test data to pass to the node." }, "test_mode": { "type": "string", "enum": ["sample_data", "listen_webhook", "trigger_event"], "description": "Test mode. Defaults to sample_data if not specified." } } }, "WorkflowNodeGetResponse": { "description": "A single workflow node", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the node." }, "type": { "type": "string", "description": "Node type identifier." }, "position": { "type": "object", "properties": { "x": { "type": "number", "description": "X coordinate." }, "y": { "type": "number", "description": "Y coordinate." } }, "required": ["x", "y"], "description": "Position of the node on the canvas." }, "data": { "$ref": "#/components/schemas/WorkflowNodeData", "description": "Node configuration and metadata." }, "targetPosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the incoming connection handle." }, "sourcePosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the outgoing connection handle." } }, "required": ["id", "type", "position", "data"] }, "WorkflowNodeListResponse": { "description": "List of workflow nodes and edges", "type": "object", "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowNodeGetResponse" }, "description": "Workflow nodes." }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEdge" }, "description": "Connections between nodes." } } }, "WorkflowNodeCreateReq": { "description": "Create a new workflow node", "type": "object", "required": ["type", "position", "data"], "properties": { "type": { "type": "string", "description": "Node type identifier." }, "position": { "type": "object", "properties": { "x": { "type": "number", "description": "X coordinate." }, "y": { "type": "number", "description": "Y coordinate." } }, "required": ["x", "y"], "description": "Position of the node on the canvas." }, "data": { "type": "object", "description": "Node configuration and metadata.", "properties": { "config": { "type": "object", "description": "Node-specific configuration." }, "title": { "type": "string", "description": "Display title for the node." }, "description": { "type": ["string", "null"], "description": "Optional description." } } }, "targetPosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the incoming connection handle. Defaults to 'top'." }, "sourcePosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the outgoing connection handle. Defaults to 'bottom'." }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowEdge" }, "description": "Optional edges to add along with the node." } } }, "WorkflowNodeUpdateReq": { "description": "Update an existing workflow node", "type": "object", "properties": { "type": { "type": "string", "description": "Node type identifier." }, "position": { "type": "object", "properties": { "x": { "type": "number", "description": "X coordinate." }, "y": { "type": "number", "description": "Y coordinate." } }, "description": "Position of the node on the canvas." }, "data": { "type": "object", "description": "Node configuration and metadata.", "properties": { "config": { "type": "object", "description": "Node-specific configuration." }, "title": { "type": "string", "description": "Display title for the node." }, "description": { "type": ["string", "null"], "description": "Optional description." } } }, "targetPosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the incoming connection handle." }, "sourcePosition": { "type": "string", "enum": ["top", "bottom", "left", "right"], "description": "Position of the outgoing connection handle." } } }, "WorkflowExecutionList": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the execution" }, "workflow_id": { "type": "string", "description": "Unique identifier for the workflow" }, "status": { "type": "string", "description": "Execution status", "enum": ["running", "waiting", "completed", "error", "cancelled", "skipped"] }, "started_at": { "type": ["string", "null"], "format": "date-time", "description": "Timestamp when the execution started" }, "finished_at": { "type": ["string", "null"], "format": "date-time", "description": "Timestamp when the execution finished" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution record was created" } }, "required": ["id", "workflow_id", "status"] } } }, "required": ["list"] }, "WorkflowExecutionGetResponse": { "description": "Workflow execution with full details", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the execution" }, "workflow_id": { "type": "string", "description": "Unique identifier for the workflow" }, "status": { "type": "string", "description": "Execution status", "enum": ["running", "waiting", "completed", "error", "cancelled", "skipped"] }, "execution_data": { "$ref": "#/components/schemas/WorkflowExecutionData", "description": "Full execution state including node results, loops, and pause/resume data" }, "started_at": { "type": ["string", "null"], "format": "date-time", "description": "Timestamp when the execution started" }, "finished_at": { "type": ["string", "null"], "format": "date-time", "description": "Timestamp when the execution finished" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the execution record was created" } }, "required": ["id", "workflow_id", "status"] } }, "responses": { "BadRequest": { "description": "BadRequest", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "x-stoplight": { "id": "p9mk4oi0hbihm" }, "example": "BadRequest [Error]: " } }, "required": [ "msg" ] }, "examples": { "Example 1": { "value": { "msg": "BadRequest [Error]: " } } } } }, "headers": {} } }, "BadRequestV3": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "UnauthorizedV3": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "ForbiddenV3": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string", "example": "Accessing api token api require enterprise plan" } } }, "NotFoundV3": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "InternalServerErrorV3": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "securitySchemes": { "xc-token": { "name": "Auth Token ", "type": "apiKey", "in": "header", "description": "Auth Token is a JWT Token generated based on the logged-in user. By default, the token is only valid for 10 hours. However, you can change the value by defining it using environment variable `NC_JWT_EXPIRES_IN`." }, "bearerAuth": { "name": "Authorization", "type": "http", "scheme": "bearer", "description": "Bearer token authentication. Use 'Authorization: Bearer ' header format. This is an alternative to the xc-token header." }, "xc-shared-base-id": { "name": "Shared Base ID", "type": "apiKey", "in": "header", "description": "Shared base uuid" }, "xc-shared-erd-id": { "name": "Shared ERD ID", "type": "apiKey", "in": "header", "description": "Shared ERD uuid" } }, "parameters": { "xc-token": { "name": "xc-token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API Token. Refer [here](https://docs.nocodb.com/account-settings/api-tokens/) to know more" } } } }