# Create Custom Agent Source: https://api-docs.datagol.ai/agents-api/create-agent POST /customAgents/api/v1 Creates a Custom AI Agent with the specified data sources, MCP tool servers, skills, and UI configuration. Returns the new agent record including its UUID. # Generate Conversation Name Source: https://api-docs.datagol.ai/agents-api/generate-name POST /ai/api/v1/builder/chat/complete # Get Agent by ID Source: https://api-docs.datagol.ai/agents-api/get-agent GET /customAgents/api/v1/{agentId} Returns the full configuration of a specific Custom Agent. # Get Conversation Message Source: https://api-docs.datagol.ai/agents-api/get-conversation-messages GET ai/api/v2/conversations/{conversationId}/messages # Get Agent Permissions Source: https://api-docs.datagol.ai/agents-api/get-permissions GET /noCo/api/v2/elementPermissions/{elementType}/{agentId} Returns all users who have access to the specified agent and their permission levels. # Get Workspace by ID Source: https://api-docs.datagol.ai/agents-api/get-workspace GET /noCo/api/v2/workspaces/{workspaceId} Fetches workspace details scoped to a Custom Agent. Called when a user opens the agent from the side panel to load context-specific workspace data. # Create Thread Source: https://api-docs.datagol.ai/agents-api/initiate-conversation POST /ai/api/v2/conversations Opens a new conversation session backed by a Custom Agent. Returns the conversationId required for the streaming endpoint. # List Custom Agents Source: https://api-docs.datagol.ai/agents-api/list-agents GET /customAgents/api/v1 Returns all Custom Agents accessible to the authenticated user within their company tenant. # List AI Connectors Source: https://api-docs.datagol.ai/agents-api/list-connectors GET /connector/api/v1/instance Returns all AI connector instances available to the tenant. Use the id values (as strings) in configs.connectors for CONNECTOR type entries. # List Conversations Source: https://api-docs.datagol.ai/agents-api/list-conversations GET /ai/api/v2/conversations Returns the list of all conversations for the authenticated user. # List Team Members Source: https://api-docs.datagol.ai/agents-api/list-team GET /idp/api/v1/team Returns all users in the company. Use userId values when sharing an agent via the bulk permissions endpoint. # List Workspaces Source: https://api-docs.datagol.ai/agents-api/list-workspaces GET /noCo/api/v2/workspaces # Search Workspaces and Workbooks Source: https://api-docs.datagol.ai/agents-api/search-workspaces GET /noCo/api/v2/workspaces/search Returns a flat list of workbook entries (`type=TABLE`) across all workspaces accessible to the authenticated user. Each item includes a `workspaceId`, `workspaceName`, and a workbook `id` (UUID). Group results by `workspaceId` / `workspaceName` to reconstruct the workspace → workbook hierarchy. Use the workbook `id` as the reference in `WORKBOOK_RAG` connector objects. # Share Agent (Bulk Permissions) Source: https://api-docs.datagol.ai/agents-api/share-agent POST /noCo/api/v2/elementPermissions/bulk Grants one or more users access to a Custom Agent in a single atomic operation. Supports VIEWER, EDITOR, and CREATOR permission levels. # Stream Message Source: https://api-docs.datagol.ai/agents-api/stream-message POST /ai/api/v2/messages/streaming Sends a user message and streams the AI response as Server-Sent Events (SSE). This endpoint is on the AI Core service (ai.datagol.ai). # AI Extraction & Knowledge Graph Source: https://api-docs.datagol.ai/ai-extraction-knowledge-graph Use AI Extraction and Knowledge Graph APIs to process content and build graph data. DataGOL exposes **AI Extraction** and **Knowledge Graph** APIs so you can extract structured data from documents and manage knowledge graphs in your workspace. **Where to find them:** Open the **API Reference** tab (top navigation). In the left sidebar you’ll see groups **AI Extraction** and **Knowledge Graph** — expand those to see and try each endpoint. ## AI Extraction APIs Base path: `https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/...` | Method | Endpoint | Summary | | ------ | --------------------------------------------------------------------------------------------------- | --------------------------------------- | | POST | `/noCo/api/v2/workspaces/{workspaceId}/extraction/schema/generate` | Generate Schema for Advanced Extraction | | POST | `/noCo/api/v2/workspaces/{workspaceId}/extraction/advanced/test` | Test API for Advanced Extraction | | POST | `/noCo/api/v2/workspaces/{workspaceId}/extraction` | Create Extraction | | PUT | `/noCo/api/v2/workspaces/{workspaceId}/extraction/{extraction_id}` | Update Extraction | | DELETE | `/noCo/api/v2/workspaces/{workspaceId}/extraction/{extractionId}` | Delete Extraction | | GET | `/noCo/api/v2/workspaces/{workspace_id}/extraction/{element_type}/{element_id}` | Get Extractions | | POST | `/noCo/api/v2/workspaces/{workspace_id}/extraction/{extraction_id}/{element_type}/{element_id}/run` | Trigger Extraction | | GET | `/noCo/api/v1/requestLog/status/{request_id}` | Poll Status | ## Knowledge Graph APIs Base path: `https://be.datagol.ai/ai/api/v2/knowledge-graph...` | Method | Endpoint | Summary | | ------ | ----------------------------------- | -------------------------- | | POST | `/ai/api/v2/knowledge-graph/create` | Create Knowledge Graph | | GET | `/ai/api/v2/knowledge-graph/status` | Get Knowledge Graph Status | | GET | `/ai/api/v2/knowledge-graph` | Get Knowledge Graph | ## AI Extraction (overview) AI Extraction lets you define schemas and run extraction jobs on workspace content (files, folders): schema generation from prompts, advanced extraction with custom schemas, and create/update/delete extraction configs. Use **Trigger Extraction** to run and **Poll Status** to check progress. ## Knowledge Graph (overview) Knowledge Graph APIs let you create and query knowledge graphs: **Create Knowledge Graph** to start a job, **Get Knowledge Graph Status** to check status, and **Get Knowledge Graph** to retrieve the graph. ## Authentication All AI Extraction and Knowledge Graph endpoints use the **x-auth-token** header (workbook/workspace API). Include your workspace token in each request. ## Next steps Go to the **API Reference** tab and expand **AI Extraction** or **Knowledge Graph** to see request parameters, bodies, and responses for each endpoint. # API Reference Source: https://api-docs.datagol.ai/api-reference Browse and try all DataGOL API endpoints. The **API Reference** section is generated from the OpenAPI specification. Use the sidebar to jump to any endpoint. Each endpoint page includes : * **Parameters** — Path, query, and header parameters * **Request body** — Schema and examples where applicable * **Responses** — Status codes and response schemas * **Try it** — Interactive playground when a server URL is configured Endpoints are grouped by tag (e.g. workflow, identity, widgets). Start with the endpoint you need and refer to the shared schemas for request/response shapes. # Create Extraction Source: https://api-docs.datagol.ai/api-reference/ai-extraction/create-extraction /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/extraction Creates an extraction configuration inside a workspace. Supports both STANDARD and ADVANCED extraction modes. # Delete Extraction Source: https://api-docs.datagol.ai/api-reference/ai-extraction/delete-extraction /openapi/openapi.yaml delete /noCo/api/v2/workspaces/{workspaceId}/extraction/{extractionId} ### 1️⃣ Overview **Purpose:** Performs a soft-delete on a specific extraction configuration. Instead of removing the record from the database entirely, the system flags the extraction as inactive (`active=false`), preserving historical logs while removing it from the active workspace view. ### 2️⃣ Endpoint ```http DELETE /noCo/api/v2/workspaces/{workspaceId}/extraction/{extractionId} ``` # Generate Schema for Advanced Extraction Source: https://api-docs.datagol.ai/api-reference/ai-extraction/generate-schema-for-advanced-extraction /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/extraction/schema/generate ## 1️⃣ Overview **Purpose:** Generates a schema based on provided file content or file identifier. The schema generation is driven by an instruction prompt. --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/extraction/schema/generate ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Identifier of the workspace | --- ## 4️⃣ Authentication Requires authentication using: ``` id="c3yq8n" Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "prompt": "string", "content": "string", "fileId": "string" } ``` --- ## 7️⃣ Field Descriptions ### Schema Generation Fields | Field | Type | Required | Description | | --- | --- | --- | --- | | prompt | string | ✅ Yes | Instruction for schema generation | | content | string | ❌ Optional | File content (if not using fileId) | | fileId | string | ❌ Optional | File ID (if not using content) | --- ## 8️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/extraction/schema/generate \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "prompt": "Extract schema from invoice file", "content": "file raw text content here" }' ``` --- ## 9️⃣ Behavior Summary Generates a schema using either file content or file ID based on the provided prompt instruction. # Get Extractions Source: https://api-docs.datagol.ai/api-reference/ai-extraction/get-extractions /openapi/openapi.yaml get /noCo/api/v2/workspaces/{workspace_id}/extraction/{element_type}/{element_id} ## 1️⃣ Overview **Purpose:** Retrieves all active extraction configurations associated with a specific element. Supports filtering by: - COLUMN - FILE - FOLDER --- ## 2️⃣ Endpoint ``` bash GET /noCo/api/v2/workspaces/{workspaceId}/extraction/{elementType}/{elementId} ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | elementType | string | ✅ Yes | COLUMN / FILE / FOLDER | | elementId | string | ✅ Yes | File, folder, or column ID | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Example Request ``` bash curl -X GET "https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/extraction/{elementType}/{elementId}" \ -H "Authorization: Bearer " ``` --- ## 7️⃣ Behavior Summary Returns all active extraction configurations linked to the specified element within the workspace. # Poll Status Source: https://api-docs.datagol.ai/api-reference/ai-extraction/poll-status /openapi/openapi.yaml get /noCo/api/v1/requestLog/status/{requestId} ## 1️⃣ Overview **Purpose:** Check the status of an asynchronous extraction request. Used to monitor extraction job progress triggered from the extraction execution endpoint. --- ## 2️⃣ Endpoint ``` bash GET /noCo/api/v1/requestLog/status/{requestId} ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | requestId | string | ✅ Yes | Request ID returned from Trigger Extraction endpoint | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Example Request ``` bash curl -X GET https://be.datagol.ai/noCo/api/v1/requestLog/status/{requestId} \ -H "Authorization: Bearer " ``` --- ## 7️⃣ Behavior Summary Retrieves the processing status of an asynchronous extraction request. This endpoint is used for polling extraction job execution progress. # Test API for Advanced Extraction Source: https://api-docs.datagol.ai/api-reference/ai-extraction/test-api-for-advanced-extraction /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/extraction/advanced/test ## 1️⃣ Overview **Purpose:** Runs an advanced extraction test using inline content or a file identifier. --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/extraction/advanced/test ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Identifier of the workspace | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "content": "string", "advancedSchema": {}, "elementId": "string" } ``` --- ## 7️⃣ Field Descriptions ### Extraction Test Fields | Field | Type | Required | Description | | --- | --- | --- | --- | | content | string | ✅ Yes | Inline content to test extraction | | advancedSchema | object | ✅ Yes | JSON schema for advanced extraction | | elementId | string | ❌ No | File ID for testing instead of content | --- ## 8️⃣ Example Request ``` bash curl -X POST https://{base_url}/noCo/api/v2/workspaces/{workspaceId}/extraction/advanced/test \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "content": "Sample invoice text", "advancedSchema": { "fields": [] } }' ``` --- ## 9️⃣ Behavior Summary Performs an advanced extraction test using either inline content or a file reference. # Test API for Standard extraction Source: https://api-docs.datagol.ai/api-reference/ai-extraction/test-api-for-standard-extraction /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/extraction/test ## 1️⃣ Overview **Purpose:** Runs a standard extraction test using inline content. --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/extraction/test ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Identifier of the workspace | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "content": "Transcript text here", "columnConfiguration": [ { "name": "Speaker Name", "description": "Extract speaker name" } ] } ``` --- ## 7️⃣ Field Descriptions ### Extraction Test Fields | Field | Type | Required | Description | | --- | --- | --- | --- | | content | string | ✅ Yes | Inline content to test extraction | | columnConfiguration | array | ✅ Yes | Column definitions | --- ## 8️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/extraction/test \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "content": "Sample document text", "columnConfiguration": [ { "name": "invoiceNumber", "type": "SINGLE_LINE_TEXT" } ] }' ``` --- ## 9️⃣ Behavior Summary Runs a standard extraction test on inline content or optional file references. # Trigger Extraction Source: https://api-docs.datagol.ai/api-reference/ai-extraction/trigger-extraction /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspace_id}/extraction/{extraction_id}/{element_type}/{element_id}/run ## 1️⃣ Overview **Purpose:** Triggers an extraction run for a specified extraction configuration and element. Supports extraction modes for: - New records only - Selected rows - Filter-based extraction - Full dataset extraction --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/extraction/{extractionId}/{elementType}/{elementId}/run?extractOnlyNew=true ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | extractionId | string | ✅ Yes | Extraction configuration ID | | elementType | string | ✅ Yes | COLUMN / FILE / FOLDER | | elementId | string | ✅ Yes | Element identifier | --- ## 4️⃣ Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | extractOnlyNew | boolean | ❌ No | Default false | Behavior: - `true` → Only new records are extracted - `false` → Selected records are upserted (update existing + insert new) --- ## 5️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 6️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | Optional | --- ## 7️⃣ Request Body Schema (Optional) ``` json { "rows": [], "whereClause": "string", "selectAll": true } ``` --- ## 8️⃣ Field Descriptions ### Extraction Execution Controls | Field | Type | Required | Description | | --- | --- | --- | --- | | rows | array | ❌ No | Specific rows to extract | | whereClause | string | ❌ No | Filter condition | | selectAll | boolean | ❌ No | Select all rows flag | --- ## 9️⃣ Example Request ### Trigger extraction for selected rows ``` bash curl -X POST "https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/extraction/{extractionId}/{elementType}/{elementId}/run?extractOnlyNew=true" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "selectAll": false, "rows": [ { "id": "row1", "name": "Sample Data" } ] }' ``` --- ## 🔟 Behavior Summary ``` Triggers an extraction execution job for the specified configuration. Supports: • Incremental Extraction — When extractOnlyNew=true, only new records are processed. • Upsert Extraction — When extractOnlyNew=false, existing records are updated and new records are inserted. • Selective Extraction — Allows extraction of specific rows using the rows field. • Filtered Extraction — Supports conditional extraction using whereClause. • Full Extraction — When selectAll=true, extracts all matching records (rows field should be omitted). ``` --- ## 📌 Additional Description When `selectAll` is true, the system extracts all matching records. If `selectAll` is false, the client must provide the complete row data in the `rows` field. The request supports two major extraction strategies: - **Incremental Extraction:** Controlled by `extractOnlyNew=true` - **Upsert Extraction:** When `extractOnlyNew=false`, existing records are updated and new records are inserted. # Update Extraction Source: https://api-docs.datagol.ai/api-reference/ai-extraction/update-extraction /openapi/openapi.yaml put /noCo/api/v2/workspaces/{workspaceId}/extraction/{extraction_id} ## 1️⃣ Overview **Purpose:** Updates an existing extraction configuration. Supports: - STANDARD or ADVANCED extraction modes - Column, file, or folder-based extraction - Schema-driven advanced extraction --- ## 2️⃣ Endpoint ``` bash PUT /noCo/api/v2/workspaces/{workspaceId}/extraction/{extractionId} ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | extractionId | string | ✅ Yes | Extraction configuration identifier | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "title": "string", "extractionMode": "string", "elementType": "string", "elementId": "string", "inputTableId": "string", "outputConfiguration": {}, "columnConfiguration": [], "primaryKeyColumnId": [], "storeExtractedData": true, "scheduleType": "string", "schedule": {}, "advancedSchema": {} } ``` --- ## 9️⃣ Behavior Summary Updates an extraction configuration within a workspace. # Create Thread Source: https://api-docs.datagol.ai/api-reference/conversations/create-thread /openapi/agents-openapi.yaml post /ai/api/v2/conversations Opens a new conversation session backed by a Custom Agent. Returns the conversationId required for the streaming endpoint. # List All Conversations Source: https://api-docs.datagol.ai/api-reference/conversations/list-all-conversations /openapi/agents-openapi.yaml get /ai/api/v2/conversations Returns the list of all conversations for the authenticated user. # Create a Custom Agent Source: https://api-docs.datagol.ai/api-reference/custom-agents/create-a-custom-agent /openapi/agents-openapi.yaml post /customAgents/api/v1 Creates a Custom AI Agent with the specified data sources, MCP tool servers, skills, and UI configuration. Returns the new agent record including its UUID. # Get Custom Agent by ID Source: https://api-docs.datagol.ai/api-reference/custom-agents/get-custom-agent-by-id /openapi/agents-openapi.yaml get /customAgents/api/v1/{agentId} Returns the full configuration of a specific Custom Agent. # List All Custom Agents Source: https://api-docs.datagol.ai/api-reference/custom-agents/list-all-custom-agents /openapi/agents-openapi.yaml get /customAgents/api/v1 Returns all Custom Agents accessible to the authenticated user within their company tenant. # Create Folder Source: https://api-docs.datagol.ai/api-reference/enterprise-search/create-folder /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspace_id}/folder ## 1️⃣ Overview **Purpose:** Creates a new folder inside a workspace. Supports nested folder creation by passing a `parentId`. --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/folder ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | string | ✅ Yes | The ID of the workspace where the folder will be created | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Request Body | Field | Type | Required | Description | | --- | --- | --- | --- | | name | string | ✅ Yes | Name of the folder to create | | parentId | string | ❌ No | ID of the parent folder for nested creation. Pass `null` for a root-level folder | --- ## 7️⃣ Example Request ``` bash curl --location 'https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/folder' \ --header 'Authorization: Bearer ' \ --data-raw '{"name":"test folder","parentId":null}' ``` --- ## 8️⃣ Behavior Summary ``` id="behcf1" Creates a new folder in the specified workspace. Returns the created folder object including its generated id. To create a nested folder, set parentId to the id of an existing folder. Pass parentId as null to create a root-level folder. ``` # Delete Folders or Files Source: https://api-docs.datagol.ai/api-reference/enterprise-search/delete-folders-or-files /openapi/openapi.yaml delete /noCo/api/v2/workspaces/{workspace_id}/folder ## 1️⃣ Overview **Purpose:** Deletes one or more folders or files from a workspace. Multiple items can be deleted in a single request by passing their IDs in the `ids` array. --- ## 2️⃣ Endpoint ``` bash DELETE /noCo/api/v2/workspaces/{workspaceId}/folder ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | string | ✅ Yes | The ID of the workspace containing the folders or files to delete | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Request Body | Field | Type | Required | Description | | --- | --- | --- | --- | | ids | array of strings | ✅ Yes | List of folder or file IDs to delete | --- ## 7️⃣ Example Request ``` bash curl --location --request DELETE 'https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/folder' \ --header 'Authorization: Bearer ' \ --data-raw '{"ids":["d287afa7-2006-4a91-ae24-03a548d0b58f"]}' ``` --- ## 8️⃣ Behavior Summary ``` id="behdf1" Deletes one or more folders or files from the specified workspace. Multiple IDs can be passed in a single request for bulk deletion. ``` # Get Enterprise Search Index Status Source: https://api-docs.datagol.ai/api-reference/enterprise-search/get-enterprise-search-index-status /openapi/openapi.yaml get /ai/api/v2/enterprise-search/connector/dg-s3-workspace/{workspaceId}/status ## 1️⃣ Overview **Purpose:** Retrieves the current indexing status of the enterprise search connector for a specific workspace. Use this endpoint to monitor whether indexing is in progress, completed, or failed. --- ## 2️⃣ Endpoint ``` bash GET /ai/api/v2/enterprise-search/connector/dg-s3-workspace/{workspaceId}/status ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | string | ✅ Yes | The ID of the workspace to check the index status for | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Example Request ``` bash curl --location 'https://ai.datagol.ai/ai/api/v2/enterprise-search/connector/dg-s3-workspace/{workspaceId}/status' \ --header 'Authorization: Bearer ' ``` --- ## 7️⃣ Behavior Summary ``` id="behes2" Returns the current indexing status of the enterprise search connector for the specified workspace. Typically used to poll the status after triggering a re-index via the Re-index Workspace Files endpoint. ``` # Re-index Workspace Files Source: https://api-docs.datagol.ai/api-reference/enterprise-search/re-index-workspace-files /openapi/openapi.yaml post /ai/api/v2/enterprise-search/connector/dg-s3-workspace/re-index ## 1️⃣ Overview **Purpose:** Triggers a search index job for all files in the specified workspace. Supports two modes controlled by the `full_reindex` flag: - **Full Re-index** — indexes all documents present in the workspace from scratch. - **Incremental Index** — processes only new or changed documents since the last index run. --- ## 2️⃣ Endpoint ``` bash POST /ai/api/v2/enterprise-search/connector/dg-s3-workspace/re-index?workspace_id={workspace_id}&full_reindex={true|false} ``` --- ## 3️⃣ Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspace_id | string | ✅ Yes | The ID of the workspace whose files are to be indexed | | full_reindex | boolean | ❌ No | `true` for full re-index of all documents; `false` for incremental index of new or changed documents only (default: false) | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Example Request ### Full Re-index ``` bash curl --location 'https://ai.datagol.ai/ai/api/v2/enterprise-search/connector/dg-s3-workspace/re-index?workspace_id={workspaceId}&full_reindex=true' \ --header 'Authorization: Bearer ' \ --data-raw '{}' ``` ### Incremental Index ``` bash curl --location 'https://ai.datagol.ai/ai/api/v2/enterprise-search/connector/dg-s3-workspace/re-index?workspace_id={workspaceId}&full_reindex=false' \ --header 'Authorization: Bearer ' \ --data-raw '{}' ``` --- ## 7️⃣ Behavior Summary ``` id="behes1" Triggers a search indexing job for the specified workspace. full_reindex=true: Re-indexes all documents in the workspace from scratch. full_reindex=false: Performs an incremental index, processing only new or changed documents since the last run. ``` # Upload File to Folder Source: https://api-docs.datagol.ai/api-reference/enterprise-search/upload-file-to-folder /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/folder/upload ## 1️⃣ Overview **Purpose:** Uploads one or more files into a specific folder within a workspace. Supports any file type. The target folder is specified via `parentId`. --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/folder/upload ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | string | ✅ Yes | The ID of the workspace to upload the file into | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Request Body (multipart/form-data) | Field | Type | Required | Description | | --- | --- | --- | --- | | files | file | ✅ Yes | The file(s) to upload | | parentId | string | ❌ No | ID of the target folder. If omitted, the file is uploaded to the workspace root | --- ## 7️⃣ Example Request ``` bash curl --location 'https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/folder/upload' \ --header 'Authorization: Bearer ' \ --form 'files=@"/path/to/file"' \ --form 'parentId="{folderId}"' ``` --- ## 8️⃣ Behavior Summary ``` id="behfu1" Uploads one or more files into the specified folder within a workspace. Returns an array of uploaded file objects, each containing the file id, name, type, size, and location metadata. If parentId is omitted, the file is placed at the workspace root level. ``` # Create Service Account Source: https://api-docs.datagol.ai/api-reference/getting-started/create-service-account /openapi/openapi.yaml post /idp/api/v1/company/serviceAccount ## 1️⃣ Overview **Purpose:** Creates a new service account within a specific company. A unique system-generated email (e.g., `@datagol.iam.serviceaccount.com`) is assigned to the account upon creation. --- ## 2️⃣ Endpoint ``` bash POST /idp/api/v1/company/serviceAccount ``` Base URL: ``` https://be.datagol.ai ``` --- ## 3️⃣ Authentication Requires Bearer Token User must have `ACCOUNT_ADMIN` or similar administrative privileges. --- ## 4️⃣ Request Headers | Header | Required | | --- | --- | | Authorization: Bearer | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 5️⃣ Request Body Schema ``` json { "name": "string", "description": "string" } ``` --- ## 6️⃣ Field Descriptions ### Service Account Fields | Field | Type | Required | Description | | --- | --- | --- | --- | | name | string | ✅ Yes | The unique identifier or display name for the service account with no spaces or special characters. | | description | string | ❌ No | A brief explanation of the account's purpose (can be an empty string). | --- ## 7️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/idp/api/v1/company/serviceAccount \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "ci_cd_service_account", "description": "Service account for CI/CD integrations" }' ``` --- ## 8️⃣ Behavior Summary Creates a new service account within the company and assigns a unique system-generated email address to it. # Generate Authentication Token Source: https://api-docs.datagol.ai/api-reference/getting-started/generate-authentication-token /openapi/openapi.yaml post /idp/api/v1/user/token ## 1️⃣ Overview **Purpose:** Generates an authentication token for a user in the DataGOL Platform. This endpoint validates the provided user credentials and returns a JWT token that can be used to authenticate subsequent API requests. --- ## 2️⃣ Endpoint ``` bash POST /idp/api/v1/user/token ``` Base URL: ``` https://be.datagol.ai ``` --- ## 3️⃣ Request Headers | Header | Required | | --- | --- | | Content-Type: application/json | ✅ Yes | --- ## 4️⃣ Request Body Schema ``` json { "email": "string", "password": "string" } ``` --- ## 5️⃣ Field Descriptions ### Token Generation Fields | Field | Type | Description | | --- | --- | --- | | email | string | The registered email address (e.g., sample_email@datagol.com). | | password | string | The user's account password. | --- ## 6️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/idp/api/v1/user/token \ -H "Content-Type: application/json" \ -d '{ "email": "sample_email@datagol.com", "password": "Password123" }' ``` --- ## 7️⃣ Example Response ``` json { "token": "eyXXXXXX" } ``` --- ## 8️⃣ Behavior Summary Validates the provided user credentials and generates a JWT authentication token. The returned token should be used in subsequent API requests for authentication, typically passed in request headers. # Get Service Token Source: https://api-docs.datagol.ai/api-reference/getting-started/get-service-token /openapi/openapi.yaml get /idp/api/v1/company/serviceAccount/{serviceTokenId}/token/reset ## 1️⃣ Overview **Purpose:** Resets and regenerates the access token for an existing service account. The newly generated token can optionally be configured to never expire. --- ## 2️⃣ Endpoint ``` bash POST /idp/api/v1/company/serviceAccount/{serviceAccountId}/token/reset?neverExpires=true ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | serviceAccountId | UUID | ✅ Yes | Identifier of the service account whose token will be reset | --- ## 4️⃣ Authentication Requires Bearer Token User must have `ACCOUNT_ADMIN` or similar administrative privileges. --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization: Bearer | ✅ Yes | --- ## 6️⃣ Example Request ``` bash curl -X POST "https://be.datagol.ai/idp/api/v1/company/serviceAccount/{serviceAccountId}/token/reset?neverExpires=true" \ -H "Authorization: Bearer " ``` --- ## 7️⃣ Behavior Summary Resets the existing service account token and generates a new one. If `neverExpires=true` is provided, the newly generated token will not expire. # Login to DataGOL Source: https://api-docs.datagol.ai/api-reference/getting-started/login-to-datagol /openapi/openapi.yaml post /idp/api/v1/user/login ## 1️⃣ Overview **Purpose:** Authenticates a user into the DataGOL Platform. On success, it returns the user's profile, including their administrative roles and assigned permissions within the workspace. --- ## 2️⃣ Endpoint ``` bash POST /idp/api/v1/user/login ``` Base URL: ``` https://be.datagol.ai ``` --- ## 3️⃣ Request Headers | Header | Required | | --- | --- | | Content-Type: application/json | ✅ Yes | --- ## 4️⃣ Request Body Schema ``` json { "email": "string", "password": "string" } ``` --- ## 5️⃣ Field Descriptions ### Login Fields | Field | Type | Description | | --- | --- | --- | | email | string | The registered email address (e.g., [sample_email@datagol.com](https://mailto:sample_email@datagol.com)). | | password | string | The user's account password. | --- ## 6️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/idp/api/v1/user/login \ -H "Content-Type: application/json" \ -d '{ "email": "sample_email@datagol.com", "password": "Password123" }' ``` --- ## 7️⃣ Behavior Summary Authenticates a user into the DataGOL Platform and returns the user profile with administrative roles and workspace permissions. # Create Knowledge Graph Source: https://api-docs.datagol.ai/api-reference/knowledge-graph/create-knowledge-graph /openapi/openapi.yaml post /ai/api/v2/knowledge-graph/create ## 1️⃣ Overview **Purpose:** Creates a knowledge graph from a specific file within a workspace. --- ## 2️⃣ Endpoint ``` bash POST /ai/api/v2/knowledge-graph/create?file_id={file_id}&workspace_id={workspace_id} ``` --- ## 3️⃣ Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | file_id | string | ✅ Yes | The ID of the file to create the knowledge graph from | | workspace_id | string | ✅ Yes | Workspace identifier where the knowledge graph will be created | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Example Request ``` bash curl -X POST "https://kg.datagol.ai/ai/api/v2/knowledge-graph/create?file_id={file_id}&workspace_id={workspace_id}" \ -H "Authorization: Bearer " ``` --- ## 7️⃣ Behavior Summary ``` id="behkg1" Creates a knowledge graph by processing the specified file. Supports semantic graph construction from workspace file content and stores graph metadata for downstream AI processing. ``` # Get files in Workspace Source: https://api-docs.datagol.ai/api-reference/knowledge-graph/get-files-in-workspace /openapi/openapi.yaml get /noCo/api/v2/workspaces/{workspace_id}/folder ## 1️⃣ Overview **Purpose:** Retrieves all folders and files available within a workspace. --- ## 2️⃣ Endpoint ``` bash GET /noCo/api/v2/workspaces/{workspace_id}/folder ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspace_id | UUID | ✅ Yes | Workspace identifier | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Example Request ``` bash curl -X GET https://be.datagol.ai/noCo/api/v2/workspaces/{workspace_id}/folder \ -H "Authorization: Bearer " ``` --- ## 7️⃣ Behavior Summary ``` id="beh2a" Retrieves all folders and files within the specified workspace. Supports hierarchical workspace storage structure and returns metadata of stored files. ``` # Get knowledge Graph Source: https://api-docs.datagol.ai/api-reference/knowledge-graph/get-knowledge-graph /openapi/openapi.yaml get /ai/api/v2/knowledge-graph ## 1️⃣ Overview **Purpose:** Retrieves nodes and relationships from a knowledge graph associated with a specific file. Supports limiting the number of returned graph entities. --- ## 2️⃣ Endpoint ``` bash GET /ai/api/v2/knowledge-graph?file_id={file_id}&limit={limit} ``` --- ## 3️⃣ Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | file_id | string | ✅ Yes | The ID of the file whose knowledge graph is to be fetched | | limit | number | ❌ No | Maximum number of nodes/relationships to return (default: 100 if not specified) | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Example Request ``` bash curl --location 'https://ai.datagol.ai/ai/api/v2/knowledge-graph?file_id={file_id}&limit={limit}' \ --header 'Authorization: Bearer ' ``` --- ## 7️⃣ Behavior Summary ``` id="behkg3" Returns knowledge graph data including nodes and relationships. Supports pagination-like control using the limit parameter. Default response size is 100 entities when limit is not provided. ``` # Get Knowledge Graph Status Source: https://api-docs.datagol.ai/api-reference/knowledge-graph/get-knowledge-graph-status /openapi/openapi.yaml get /ai/api/v2/knowledge-graph/status ## 1️⃣ Overview **Purpose:** Checks the processing or creation status of a knowledge graph for a specific file. Used to monitor asynchronous knowledge graph generation. --- ## 2️⃣ Endpoint ``` bash GET /ai/api/v2/knowledge-graph/status?file_id={fileId} ``` --- ## 3️⃣ Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | file_id | string | ✅ Yes | The ID of the file for which knowledge graph status is requested | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Example Request ``` bash curl --location 'https://ai.datagol.ai/ai/api/v2/knowledge-graph/status?file_id={fileId}' \ --header 'Authorization: Bearer ' ``` --- ## 7️⃣ Behavior Summary ``` id="behkg2" Retrieves the current processing status of knowledge graph generation. ``` # Add Lookup Column Source: https://api-docs.datagol.ai/api-reference/links-&-joins/add-lookup-column /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/columns ## 1️⃣ Overview **Purpose:** Adds one or more LOOKUP type columns to a specified table. A lookup column pulls field values from a linked (associated) table via an existing LINK column. --- ## 2️⃣ Endpoint ``` POST /noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/columns ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | tableId | UUID | ✅ Yes | Table identifier where the lookup column will be created | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ```json { "columns": [ { "description": "string", "uiMetadata": { "title": "string" }, "uiDataType": "LOOKUP", "colOptions": { "linkColumnId": "uuid", "lookupColumnId": "uuid" }, "name": "string" } ] } ``` --- ## 7️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | columns | array | ✅ Yes | Array of lookup column definitions to create | | columns[].description | string | ❌ No | Optional description of the column | | columns[].uiMetadata.title | string | ✅ Yes | Display name shown in the UI | | columns[].uiDataType | string | ✅ Yes | Must be `LOOKUP` | | columns[].colOptions.linkColumnId | UUID | ✅ Yes | ID of the existing LINK column connecting to the source table | | columns[].colOptions.lookupColumnId | UUID | ✅ Yes | ID of the column in the linked table whose values should be looked up | | columns[].name | string | ✅ Yes | Internal column name — must be unique within the table | --- ## 8️⃣ Example Request ```bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/columns \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "columns": [ { "description": "", "uiMetadata": { "title": "Name (from People)" }, "uiDataType": "LOOKUP", "colOptions": { "linkColumnId": "21224153-2f85-4b24-a306-4cfbc7e73f70", "lookupColumnId": "9b5e408d-69bb-42ca-8fa4-ba00f7994356" }, "name": "name_1774285509977" } ] }' ``` --- ## 9️⃣ Behavior Summary ``` Creates one or more LOOKUP columns in the target table. Supports: • Batch creation of multiple lookup columns in one request • linkColumnId — references the existing LINK column in the current table • lookupColumnId — references the column from the linked table to display • Column name must be unique within the table ``` # Add Row with Linked Records Source: https://api-docs.datagol.ai/api-reference/links-&-joins/add-row-with-linked-records /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables/{workbook_id}/rows ## 1️⃣ Overview **Purpose:** Creates a new row in the specified table and simultaneously links it to one or more records in associated tables via existing LINK columns. This endpoint supports: - Setting cell values for the new row at creation time - Linking the new row to existing records in associated tables using `linkColumnId` - Multiple link relations can be established in a single request --- ## 2️⃣ Endpoint ``` POST /noCo/api/v2/workspaces/{workspaceId}/tables/{workbook_id}/rows ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbook_id | UUID | ✅ Yes | workbook where the row will be created | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ```json { "cellValues": { "": "" }, "linkRecords": [ { "destinationRecordId": "integer", "linkColumnId": "uuid" } ] } ``` --- ## 7️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | cellValues | object | ✅ Yes | Key-value map of column names and their values for the new row | | cellValues.\ | any | ❌ No | Value for a specific column — pass empty string or empty array if no value | | linkRecords | array | ❌ No | List of link operations to perform when creating the row | | linkRecords[].destinationRecordId | integer | ✅ Yes | PK of the record in the associated table to link to | | linkRecords[].linkColumnId | UUID | ✅ Yes | ID of the LINK column that defines the relation | # Create Link Column (Manual-Link) Source: https://api-docs.datagol.ai/api-reference/links-&-joins/create-link-column-manual-link /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/column ## 1️⃣ Overview **Purpose:** Creates a new LINK type column in a table, establishing a bidirectional relationship between a parent table and a child/associated table. This endpoint supports: - Creating HAS_MANY, ONE_TO_ONE, and MANY_TO_MANY relation types - Automatically creating a reciprocal link column in the associated table > ⚠️ **Note:** Links are bidirectional. When a link is created from the parent with relation type `HAS_MANY`, a corresponding column with relation type `BELONGS_TO` is automatically created in the child table. --- ## 2️⃣ Endpoint ``` POST /noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/column ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | tableId | UUID | ✅ Yes | Source (parent) table identifier | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ```json { "uiDataType": "LINK", "colOptions": { "relationType": "HAS_MANY", "associateTableId": "uuid", "associateWorkspaceId": "uuid" }, "uiMetadata": { "title": "string" }, "settings": {}, "name": "string" } ``` --- ## 7️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | uiDataType | string | ✅ Yes | Must be `LINK` | | colOptions.relationType | string | ✅ Yes | Relation type: `HAS_MANY`, `ONE_TO_ONE`, or `MANY_TO_MANY` | | colOptions.associateTableId | UUID | ✅ Yes | The child or linked table ID | | colOptions.associateWorkspaceId | UUID | ✅ Yes | The workspace ID of the child (associated) table | | uiMetadata.title | string | ✅ Yes | Display name shown in the UI | | name | string | ✅ Yes | Internal column name — must be unique within the table | --- ## 8️⃣ Example Request ```bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/column \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "uiDataType": "LINK", "colOptions": { "relationType": "HAS_MANY", "associateTableId": "6a175502-6458-4314-b4c5-3c2f29626dea", "associateWorkspaceId": "b3e1a902-1234-4abc-9def-7f8a90bc1234" }, "uiMetadata": { "title": "people" }, "name": "people" }' ``` --- ## 9️⃣ Behavior Summary ``` Creates a LINK column in the source table. Supports: • HAS_MANY, ONE_TO_ONE, and MANY_TO_MANY relation types • Bidirectional — a BELONGS_TO column is auto-created in the child table • Column name must be unique within the table • Returns the full column object including colOptions with resolved IDs ``` # Create Link Column with Auto Join Condition Source: https://api-docs.datagol.ai/api-reference/links-&-joins/create-link-column-with-auto-join-condition /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspace_id}/tables/{table_id}/column ## 1️⃣ Overview **Purpose:** Creates a new LINK type column with an automatic join condition between the parent and child tables. Unlike a manual link, this allows defining column-level join conditions that filter how records are linked. This endpoint supports: - Defining join conditions between columns of two tables - Using operators like `EQUALS` for condition matching - Passing a raw SQL-style `whereClause` and `formula` for backend filtering --- ## 2️⃣ Endpoint ``` POST /noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/column ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | tableId | UUID | ✅ Yes | Source (parent) table identifier | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ```json { "uiDataType": "LINK", "colOptions": { "associateTableId": "uuid", "associateWorkspaceId": "uuid", "whereClause": "string" }, "uiMetadata": { "title": "string", "autoJoinConfig": { "joinConditions": [ { "id": "string", "currentTableColumn": "string", "linkedTableColumn": "string", "operator": "EQUALS" } ], "isSwapped": false } }, "formula": "string", "name": "string" } ``` --- ## 7️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | uiDataType | string | ✅ Yes | Must be `LINK` | | colOptions.associateTableId | UUID | ✅ Yes | The child or linked table ID | | colOptions.associateWorkspaceId | UUID | ✅ Yes | The workspace ID of the child (associated) table | | colOptions.whereClause | string | ✅ Yes | Raw SQL-style condition used for backend join filtering | | uiMetadata.title | string | ✅ Yes | Display name shown in the UI | | uiMetadata.autoJoinConfig | object | ✅ Yes | Configuration object defining the auto join conditions | | uiMetadata.autoJoinConfig.joinConditions | array | ✅ Yes | List of join condition objects | | uiMetadata.autoJoinConfig.joinConditions[].id | string | ✅ Yes | Unique identifier for the condition (client-generated) | | uiMetadata.autoJoinConfig.joinConditions[].currentTableColumn | string | ✅ Yes | Column name from the current (source) table to join on | | uiMetadata.autoJoinConfig.joinConditions[].linkedTableColumn | string | ✅ Yes | Column name from the linked (destination) table to join on | | uiMetadata.autoJoinConfig.joinConditions[].operator | string | ✅ Yes | Join operator — currently supports `EQUALS` | | uiMetadata.autoJoinConfig.isSwapped | boolean | ❌ No | Whether the join direction is swapped. Defaults to `false` | | formula | string | ✅ Yes | Raw SQL-style formula matching the whereClause, used for backend processing | | name | string | ✅ Yes | Internal column name — must be unique within the table | # De-Link Records Source: https://api-docs.datagol.ai/api-reference/links-&-joins/de-link-records /openapi/openapi.yaml delete /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/linkRecordV2 ## 1️⃣ Overview **Purpose:** Removes existing links between records in a source table and records in a destination table. Supports batch de-linking of multiple record pairs in a single request. --- ## 2️⃣ Endpoint ``` DELETE /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/linkRecordV2 ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Workbook identifier | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ```json [ { "sourceRecordId": integer, "destinationRecordId": integer, "linkColumnId": "uuid" } ] ``` --- ## 7️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | sourceRecordId | integer | ✅ Yes | Primary key of the record in the current (source) table | | destinationRecordId | integer | ✅ Yes | Primary key of the record in the destination table | | linkColumnId | UUID | ✅ Yes | LINK column ID or link dataType columnId | --- ## 8️⃣ Example Request ```bash curl -X DELETE https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/linkRecordV2 \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "sourceRecordId": 1, "destinationRecordId": 1, "linkColumnId": "21224153-2f85-4b24-a306-4cfbc7e73f70" }, { "sourceRecordId": 1, "destinationRecordId": 2, "linkColumnId": "21224153-2f85-4b24-a306-4cfbc7e73f70" } ]' ``` --- ## ``` # Get All Link Tables of Current Table Source: https://api-docs.datagol.ai/api-reference/links-&-joins/get-all-link-tables-of-current-table /openapi/openapi.yaml get /noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/linkTables ## 1️⃣ Overview **Purpose:** Retrieves all tables that are linked to a specified table within a workspace. Useful for discovering all relationships (link columns) associated with a table. --- ## 2️⃣ Endpoint ``` GET /noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/linkTables ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | tableId | UUID | ✅ Yes | Table identifier to query linked tables for | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Example Request ```bash curl -X GET https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/linkTables \ -H "Authorization: Bearer " ``` --- ## 7️⃣ Behavior Summary ``` Returns all tables linked to the specified table. Includes metadata about link columns and relation types. ``` # Get Link Data Source: https://api-docs.datagol.ai/api-reference/links-&-joins/get-link-data /openapi/openapi.yaml get /noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/{linkColumnId}/linkData ## 1️⃣ Overview **Purpose:** Retrieves the linked records for a specific row via a LINK column. Given a source record's row ID, this returns all destination records that are linked to it through the specified link column. --- ## 2️⃣ Endpoint ``` GET /noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/{linkColumnId}/linkData?id={rowId} ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | tableId | UUID | ✅ Yes | Source table identifier | | linkColumnId | UUID | ✅ Yes | ID of the LINK column to fetch linked data for | --- ## 4️⃣ Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | id | integer | ✅ Yes | The row ID of the source record whose linked records you want to retrieve | --- ## 5️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 6️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 7️⃣ Example Request ```bash curl -X GET 'https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/{linkColumnId}/linkData?id=1' \ -H "Authorization: Bearer " ``` --- ## 8️⃣ Behavior Summary ``` Returns all records linked to the specified source row via the given LINK column. Supports: • Fetching linked records for any LINK column type (HAS_MANY, ONE_TO_ONE, MANY_TO_MANY) • id query param — row ID of the source record in the current table • linkColumnId — identifies which link column's data to retrieve ``` # Link Records Source: https://api-docs.datagol.ai/api-reference/links-&-joins/link-records /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/linkRecordV2 ## 1️⃣ Overview **Purpose:** Links one or more records from a source table to records in a destination table via a LINK column. Supports batch linking of multiple record pairs in a single request. --- ## 2️⃣ Endpoint ``` POST /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/linkRecordV2 ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Workbook identifier | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ```json [ { "sourceRecordId": integer, "destinationRecordId": integer, "linkColumnId": "uuid" } ] ``` --- ## 7️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | sourceRecordId | integer | ✅ Yes | The row ID of the source record in the current table that you want to link to the destination record. | | destinationRecordId | integer | ✅ Yes | The row ID of the destination record in the linked table that you want to link to the source record. | | linkColumnId | UUID | ✅ Yes | ID of the LINK type column in the current table, or the link dataType columnId for a LookUp column | --- ## 8️⃣ Example Request ```bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/linkRecordV2 \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '[ { "sourceRecordId": 1, "destinationRecordId": 1, "linkColumnId": "21224153-2f85-4b24-a306-4cfbc7e73f70" }, { "sourceRecordId": 1, "destinationRecordId": 2, "linkColumnId": "21224153-2f85-4b24-a306-4cfbc7e73f70" } ]' ``` --- ## 9️⃣ Behavior Summary ``` Links records between two tables via a LINK column. Supports: • Batch linking multiple record pairs in one request • sourceRecordId — PK of the record in the current table • destinationRecordId — PK of the record in the destination table • linkColumnId — the LINK column ID or link dataType columnId for LookUp ``` # Get Conversation Messages Source: https://api-docs.datagol.ai/api-reference/messaging/get-conversation-messages /openapi/agents-openapi.yaml get /conversations/{conversationId}/messages Retrieves a chronologically ordered list of user messages, AI responses, and deep system agent routing execution data for a specific conversation thread. # Stream a Message to the Agent Source: https://api-docs.datagol.ai/api-reference/messaging/stream-a-message-to-the-agent /openapi/agents-openapi.yaml post /ai/api/v2/messages/streaming Sends a user message and streams the AI response as Server-Sent Events (SSE). This endpoint is on the AI Core service (ai.datagol.ai). # Get Custom Agent Permissions Source: https://api-docs.datagol.ai/api-reference/permissions/get-custom-agent-permissions /openapi/agents-openapi.yaml get /noCo/api/v2/elementPermissions/{elementType}/{agentId} Returns all users who have access to the specified agent and their permission levels. # Share Agent with Team Members Source: https://api-docs.datagol.ai/api-reference/permissions/share-agent-with-team-members /openapi/agents-openapi.yaml post /noCo/api/v2/elementPermissions/bulk Grants one or more users access to a Custom Agent in a single atomic operation. Supports VIEWER, EDITOR, and CREATOR permission levels. # Get Workspace by ID Source: https://api-docs.datagol.ai/api-reference/reference-data/get-workspace-by-id /openapi/agents-openapi.yaml get /noCo/api/v2/workspaces/{workspaceId} Fetches workspace details scoped to a Custom Agent. Called when a user opens the agent from the side panel to load context-specific workspace data. # List All AI Connectors Source: https://api-docs.datagol.ai/api-reference/reference-data/list-all-ai-connectors /openapi/agents-openapi.yaml get /connector/api/v1/instance Returns all AI connector instances available to the tenant. Use the id values (as strings) in configs.connectors for CONNECTOR type entries. # List All Workspaces Source: https://api-docs.datagol.ai/api-reference/reference-data/list-all-workspaces /openapi/agents-openapi.yaml get /noCo/api/v2/workspaces Returns all workspaces in the company tenant. Use workspace id values as workspaceId in WORKBOOK_RAG and WORKSPACE_DOCUMENTS connector objects. # List Team Members Source: https://api-docs.datagol.ai/api-reference/reference-data/list-team-members /openapi/agents-openapi.yaml get /idp/api/v1/team Returns all users in the company. Use userId values when sharing an agent via the bulk permissions endpoint. # Search Workspaces and Workbooks Source: https://api-docs.datagol.ai/api-reference/reference-data/search-workspaces-and-workbooks /openapi/agents-openapi.yaml get /noCo/api/v2/workspaces/search Returns a flat list of workbook entries (`type=TABLE`) across all workspaces accessible to the authenticated user. Each item includes a `workspaceId`, `workspaceName`, and a workbook `id` (UUID). Group results by `workspaceId` / `workspaceName` to reconstruct the workspace → workbook hierarchy. Use the workbook `id` as the reference in `WORKBOOK_RAG` connector objects. # User Sign Up Source: https://api-docs.datagol.ai/api-reference/sign-up/user-sign-up /openapi/openapi.yaml post /idp/api/v1/user/sign-up ## 1️⃣ Overview **Purpose:** Registers a new user account. Supports two sign-up flows: - **Self Registration** — User registers independently. No hash required. An OTP is sent to the email for verification. - **Workspace Invitation** — User was invited to a workspace via email. The invitation `hash` (received in the invitation email) must be provided along with name and password. --- ## 2️⃣ Endpoint ``` bash POST /idp/api/v1/user/sign-up ``` --- ## 3️⃣ Authentication No authentication required. This is a public endpoint. --- ## 4️⃣ Request Headers | Header | Required | | --- | --- | | Content-Type: application/json | ✅ Yes | --- ## 5️⃣ Request Body Schema ``` json { "email": "string", "password": "string", "firstname": "string", "lastname": "string", "hash": "string" } ``` --- ## 6️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | email | string | ✅ Yes | User's email address | | password | string | ✅ Yes | Min 8 chars, must include uppercase, lowercase, number, and special character | | firstname | string | ✅ Yes | User's first name | | lastname | string | ✅ Yes | User's last name | | hash | string | ⚠️ Conditional | Required only for workspace invitation flow. UUID received in the invitation email. Must be omitted for self-registration. | --- ## 7️⃣ Sign-Up Flows ### 🔵 Self Registration ```json { "email": "user@example.com", "password": "password123", "firstname": "John", "lastname": "Doe" } ``` - No `hash` required - OTP is sent to the provided email - User must verify email via `/idp/api/v1/user/signUp/verifyEmailOtp` ### 🟢 Workspace Invitation ```json { "email": "user@example.com", "password": "password123", "firstname": "John", "lastname": "Doe", "hash": "e0754cfc-f7d1-4cc3-8690-e34a2f17291d" } ``` - `hash` is mandatory and must match the one received in the invitation email - User is directly linked to the inviting workspace upon successful registration --- ## 8️⃣ Behavior Summary ``` • Self Registration — OTP is dispatched to the email. Account is pending until OTP is verified. • Workspace Invitation — Hash is validated against the invitation. Account is activated and linked to the workspace. • Password Policy — Enforced for both flows. ``` --- ## 📌 Additional Notes - For self-registration, the OTP verification step is mandatory to activate the account. - For workspace invitation, the `hash` is single-use and time-limited. - `firstname` and `lastname` are required for both flows. # Verify Email OTP for Sign Up Source: https://api-docs.datagol.ai/api-reference/sign-up/verify-email-otp-for-sign-up /openapi/openapi.yaml post /idp/api/v1/user/signUp/verifyEmailOtp ## 1️⃣ Overview **Purpose:** Verifies the OTP sent to the user's email as the second step of the **self-registration flow**. On successful verification, the user's account is activated. > ⚠️ This endpoint is only applicable for the **Self Registration** flow. Users who signed up via a **Workspace Invitation** (with a hash) do not need to complete this step. --- ## 2️⃣ Endpoint ``` bash POST /idp/api/v1/user/signUp/verifyEmailOtp ``` --- ## 3️⃣ Authentication No authentication required. This is a public endpoint. --- ## 4️⃣ Request Headers | Header | Required | | --- | --- | | Content-Type: application/json | ✅ Yes | --- ## 5️⃣ Request Body Schema ``` json { "email": "string", "otp": "string" } ``` --- ## 6️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | email | string | ✅ Yes | Must match the email used in the sign-up request | | otp | string | ✅ Yes | One-time password sent to the user's email after sign-up | --- ## 7️⃣ Behavior Summary ``` Second step of the Self Registration flow. • OTP Validation — The OTP must match the one dispatched during sign-up. • Account Activation — On successful verification, the user account is fully activated. • OTP Expiry — OTP is time-limited. If expired, the user must re-initiate the sign-up. • Flow Specific — Only applicable for self-registered users. Invitation-based users are activated immediately upon sign-up. ``` --- ## 📌 Additional Notes - This is **Step 2** of the self-registration flow. Step 1 is `POST /idp/api/v1/user/sign-up`. - The email must exactly match the one used during sign-up. - Workspace invitation users skip this step entirely as their account is activated via hash validation. # Add Row Source: https://api-docs.datagol.ai/api-reference/workbook/add-row /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows ## 1️⃣ Overview **Purpose:** Adds a new row to a workbook within a workspace. --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows ````````` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Workbook identifier | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "cellValues": {} } ``` --- ## 7️⃣ Field Descriptions ### Row Data | Field | Type | Required | Description | | --- | --- | --- | --- | | cellValues | object | ✅ Yes | Key-value mapping of workbook column internal names to their values | --- ## 8️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "cellValues": { "first_name": "John", "years_of_experience": 5, "is_active": true, "start_date": "2024-02-18T05:00:00+00:00" } }' ``` --- ## 9️⃣ Behavior Summary ``` id="beh1b" Inserts a new record into the workbook. Supports: • Dynamic column-value mapping using cellValues object • Internal column names must be used as keys • Data validation is performed before insertion • Date values must follow YYYY-MM-DD format ``` # Add Rows (Bulk) Source: https://api-docs.datagol.ai/api-reference/workbook/add-rows-bulk /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows/bulk ## 1️⃣ Overview **Purpose:** Adds multiple new rows to a workbook within a workspace in a single request. --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows/bulk ``````` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Workbook identifier | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json [ { "cellValues": {} } ] `````` --- ## 7️⃣ Field Descriptions ### Bulk Row Data | Field | Type | Required | Description | | --- | --- | --- | --- | | cellValues | object | ✅ Yes | Key-value mapping of workbook column internal names to their values | --- ## 8️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows/bulk \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ --data-raw '[{"cellValues":{"first_name":"John","years_of_experience":5,"is_active":true,"start_date":"2024-02-18T05:00:00+00:00"}},{"cellValues":{"first_name":"Jane","years_of_experience":3,"is_active":false,"start_date":"2023-06-01T05:00:00+00:00"}}]' ````` --- ## 9️⃣ Behavior Summary ``` id="beh1b" Inserts multiple new records into the workbook in a single request. Supports: • Top-level array of row objects — not wrapped in a parent object • Internal column names must be used as keys • Data validation is performed on all rows before insertion • Date values must follow YYYY-MM-DD format • All rows are inserted atomically. ```` # Create Column Source: https://api-docs.datagol.ai/api-reference/workbook/create-column /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables/{workbook_Id}/column ## 1️⃣ Overview **Purpose:** Creates a new column inside a workbook. Supports multiple column types such as: - Text column - Number column - Date column - Other supported UI data types --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/column ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Workbook identifier | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "uiDataType": "string", "uiMetadata": {}, "name": "string" } ``` --- ## 7️⃣ Field Descriptions ### Column Configuration | Field | Type | Required | Description | | --- | --- | --- | --- | | uiDataType | string | ✅ Yes | Column type (e.g., SINGLE_LINE_TEXT, NUMBER, DATE etc.) | | uiMetadata | object | ✅ Yes | Metadata for UI display (e.g., `{ "title": "My Column" }`) | | name | string | ✅ Yes | Internal column name (snake_case recommended) | --- ## 8️⃣ Example Request ``` bash curl --location 'https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/column' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "uiDataType": "SINGLE_LINE_TEXT", "uiMetadata": { "title": "sample text" }, "description": "some description" "name": "sample_text" }' ``` --- ## 9️⃣ Behavior Summary ``` id="behcol2" Creates a new workbook column. Supports: • Multiple UI data types (TEXT, NUMBER, DATE, etc.) • UI metadata configuration for rendering • Snake_case internal column naming • Server-side validation before creation ``` # Create Workbook Source: https://api-docs.datagol.ai/api-reference/workbook/create-workbook /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables ## 1️⃣ Overview **Purpose:** Creates a new Workbook inside a specified workspace. This endpoint creates: - A new table (workbook container) - Basic metadata (title and optional description) - Table type configuration (e.g., DYNAMIC) --- ## 2️⃣ Endpoint ``` POST /noCo/api/v2/workspaces/{workspaceId}/tables ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Identifier of the workspace where the workbook will be created | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Required Permissions User must have: - `CREATOR` or EDITOR permission --- ## 6️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 7️⃣ Request Body Schema ``` { "title": "string", "description": "string", "tableType": "DYNAMIC | STATIC"} ``` --- ## 8️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | title | string | ✅ Yes | Display name of the workbook | | description | string | ❌ | Workbook description | | tableType | enum | ❌ | Type of table (e.g., DYNAMIC, STATIC) | --- ## 9️⃣ Example Request ``` curl -X POST \https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables \-H "Authorization: Bearer " \-H "Content-Type: application/json" \-d '{ "title": "Workbook 1", "description": "", "tableType": "DYNAMIC"}' ``` --- ## 🔄 Behavior When this endpoint is called: 1. Validate workspace access 2. Create workbook metadata 3. Initialize table configuration 4. Persist configuration 5. Return created workbook object --- ## 🔹 Table Type Behavior | Type | Description | | --- | --- | | DYNAMIC | Supports computed fields, AI columns, formulas | | STATIC | Manual data entry only | --- ## ✅ Successful Response Example ``` { "id": "generated-table-uuid", "title": "Workbook 1", "tableType": "DYNAMIC", "createdAt": "2026-02-26T13:00:00Z"} ``` --- # 📌 Behavior Summary This endpoint: > Creates a new Workbook (table) with basic metadata inside a workspace; It supports: - Workbook creation with minimal configuration - Optional description - Table type selection # Delete Column Source: https://api-docs.datagol.ai/api-reference/workbook/delete-column /openapi/openapi.yaml delete /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/columns/{columnId} ## 1️⃣ Overview **Purpose:** Deletes an existing column from a specified table within a workspace. --- ## 2️⃣ Endpoint ``` bash DELETE /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/columns/{columnId} ```` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Table identifier | | columnId | UUID | ✅ Yes | Identifier of the column to delete | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body No request body required. The column to delete is identified entirely by the `columnId` path parameter. --- ## 7️⃣ Example Request ``` bash curl -X DELETE 'https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/columns/{columnId}' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` --- ## 8️⃣ Behavior Summary ``` id="behcol4" Deletes a column from the specified workbook table. Validation Rules: • workspaceId, workbookId, and columnId must all be valid • User must have delete permission on the column • System-generated or formula columns may not be deletable • Deletion is permanent — column data cannot be recovered ``` # Delete Rows Source: https://api-docs.datagol.ai/api-reference/workbook/delete-rows /openapi/openapi.yaml delete /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows ## 1️⃣ Overview **Purpose:** Deletes one or more rows from a workbook within a workspace. --- ## 2️⃣ Endpoint ``` bash DELETE /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Workbook identifier | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "rowIds": [] } ``` --- ## 7️⃣ Field Descriptions ### Row Deletion Payload | Field | Type | Required | Description | | --- | --- | --- | --- | | rowIds | array | ✅ Yes | List of row identifiers to delete | --- ## 8️⃣ Example Request ``` bash curl -X DELETE 'https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ --data-raw '{"rowIds":[40]}' ``` --- ## 9️⃣ Behavior Summary ``` Deletes one or more workbook rows. Supports bulk deletion using rowIds array. Validation Rules: • Workbook must exist within workspace. • User must have write/delete permission. • Provided rowIds must be valid. ``` # Generate AI Column Source: https://api-docs.datagol.ai/api-reference/workbook/generate-ai-column /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/column # Create AI Generated Column ## 1️⃣ Overview **Purpose:** Creates a new column in a specified workspace table. The column can optionally be AI-generated using a configured language model. When `aiSettings.enabled = true`, the column becomes a computed AI column that auto-generates values based on a prompt and row data. --- ## 2️⃣ Endpoint ``` POST /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/column ``` ### Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | ID of the workspace | | tableId | UUID | ✅ Yes | ID of the target table | --- ## 3️⃣ Authentication Requires **Bearer Token (JWT)**. ``` Authorization: Bearer ``` ### Required Permissions User must have: - `CREATE_DATASOURCE` or equivalent column creation permission - Table edit access --- ## 4️⃣ Request Headers | Header | Value | | --- | --- | | Content-Type | application/json | | Authorization | Bearer token | --- ## 5️⃣ Request Body Schema ``` { "name": "string", "uiDataType": "SINGLE_LINE_TEXT | NUMBER | ...", "description": "string", "required": false, "uiMetadata": { "title": "string" }, "settings": { "aiSettings": { "enabled": true, "prompt": "string", "model": "string", "webAccess": false } }} ``` --- ## 6️⃣ Field Descriptions ### Core Column Fields | Field | Type | Required | Description | | --- | --- | --- | --- | | name | string | ✅ | Internal column name | | uiDataType | enum | ✅ | Data type of the column | | description | string | ❌ | Column description | | required | boolean | ❌ | Whether the column is mandatory | | uiMetadata.title | string | ❌ | Display name in UI | --- ### 🤖 AI Settings (Optional) | Field | Type | Required | Description | | --- | --- | --- | --- | | enabled | boolean | ✅ (if aiSettings present) | Enables AI computation | | prompt | string | ✅ | Prompt used to generate values | | model | string | ✅ | LLM model to use | | webAccess | boolean | ❌ | Allows external web search (if supported) | --- ## 7️⃣ Behavior ### If `aiSettings.enabled = false` - Column behaves as a standard manual input column. ### If `aiSettings.enabled = true` - Column becomes computed. - Value is generated automatically using: - Row context - Prompt - Selected model - Users may not manually edit values (depending on system rules). - Generation may trigger: - On row creation - On row update - On manual regeneration --- ## 8️⃣ Example – Create AI Column ``` curl -X POST \https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{tableId}/column \-H "Authorization: Bearer " \-H "Content-Type: application/json" \-d '{ "name": "col", "uiDataType": "SINGLE_LINE_TEXT", "required": false, "settings": { "aiSettings": { "enabled": true, "prompt": "Extract first name from full name", "model": "gpt-4o-mini", "webAccess": false } }}' ``` --- ## 9️⃣ Example Use Case If table has: | full_name | | --- | | John Smith | | Alice Brown | AI column prompt: ``` Extract first name from full name ``` Generated column: | full_name | first_name | | --- | --- | | John Smith | John | | Alice Brown | Alice | --- ## 🔟 Response (Example) ``` { "id": "column-uuid", "name": "col", "uiDataType": "SINGLE_LINE_TEXT", "aiEnabled": true, "createdAt": "timestamp"} ``` # Get All Workbooks in workspace Source: https://api-docs.datagol.ai/api-reference/workbook/get-all-workbooks-in-workspace /openapi/openapi.yaml get /noCo/api/v2/workspaces/{workspaceId}/tables ## 1️⃣ Overview **Purpose:** Retrieve a list of all Workbooks associated with a specific workspace. Used to populate workspace dashboards or fetch workbook structure metadata for synchronization tasks. --- ## 2️⃣ Endpoint ``` bash GET /noCo/api/v2/workspaces/{workspaceId}/tables ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Identifier of the workspace to query | --- ## 4️⃣ Query Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | isIncludeColumns | boolean | ❌ No | If `true`, the response includes column metadata for each workbook | --- ## 5️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 6️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Accept | ❌ No | --- ## 7️⃣ Example Request ``` bash curl -X GET https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables?isIncludeColumns=true \ -H "Authorization: Bearer " ``` --- ## 8️⃣ Response Fields | Field | Type | Description | | --- | --- | --- | | id | string | Unique identifier for the workbook | | title | string | Display name of the workbook | | columns | array | Column metadata (returned only when `isIncludeColumns=true`) | | tableType | enum | Type of workbook (`DYNAMIC`, `STATIC`) | --- ## 9️⃣ Behavior Summary ``` Retrieves all workbooks within the specified workspace. If isIncludeColumns=true, column definitions such as name, type, and UI metadata are included in the response. Results are typically returned in the order of workbook position configured in the workspace. ``` # Get Row Data By ID Source: https://api-docs.datagol.ai/api-reference/workbook/get-row-data-by-id /openapi/openapi.yaml get /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows/{rowId} ## 1️⃣ Overview **Purpose:** Retrieves a single row's complete data from a specified table within a workspace using its unique row ID. This endpoint returns: - All column values for the row - AI-generated values (if applicable) - Formula-calculated values - System fields (if configured to return them) --- ## 2️⃣ Endpoint ``` GET /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows/{rowId} ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Identifier of the workspace | | workbookId | UUID | ✅ Yes | Identifier of the table | | rowId | string / number | ✅ Yes | Unique identifier of the row | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Required Permissions User must have: - Workspace access - Table view permission - Row read permission If table contains: - AI columns → permission to view generated content required - Restricted columns → values may be masked or omitted --- ## 6️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | Optional | --- ## 7️⃣ Request Example ``` curl -X GET https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows/{rowId} \ -H "Authorization: Bearer " ``` --- ## 8️⃣ Successful Response ### Example Response ``` { "id": 1, "values": { "name": "dega", "status": "Active", "ai_summary": "Generated summary text", "created_at": "2026-02-20T10:00:00Z" }, "createdAt": "2026-02-20T10:00:00Z", "updatedAt": "2026-02-26T12:45:00Z"} ``` --- ## 9️⃣ Response Fields | Field | Description | | --- | --- | | id | Row identifier | | values | Key-value map of column names and values | | createdAt | Row creation timestamp | | updatedAt | Last modification timestamp | --- # 🔄 Behavior When this endpoint is called: 1. Validate workspace access 2. Validate table existence 3. Validate row existence 4. Validate user read permissions 5. Retrieve row data 6. Include: - Standard column values - AI-generated values - Formula results 7. Return structured JSON response --- # 🤖 AI Column Handling If the table contains AI-enabled columns: - Returns last generated value - Does not trigger regeneration - If generation is asynchronous and pending: - May return null - Or may return processing status (implementation-dependent) --- # 📊 Formula Column Handling If a column is a formula: - Returned value is the computed result - Manual override is not applicable --- # 📌 Behavior Summary This endpoint retrieves complete data for a specific row by ID within a workspace table. It supports standard column retrieval, AI-generated values, formula-computed values, and permission-based visibility. # Get Workbook Data Source: https://api-docs.datagol.ai/api-reference/workbook/get-workbook-data /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/cursor ## 1️⃣ Overview **Purpose:** Retrieves records from a workbook within a workspace using **cursor-based pagination**. Supports: - Filtering queries - Sorting rules - Pagination traversal --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/cursor ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Workbook identifier | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "requestPageDetails": { "pageNumber": 1, "pageSize": 500 }, "sortOptions": [], "whereClause": "string" } ``` --- ## 7️⃣ Field Descriptions ### Pagination Configuration | Field | Type | Required | Description | | --- | --- | --- | --- | | requestPageDetails | object | ✅ Yes | Pagination configuration | | requestPageDetails.pageNumber | number | ✅ Yes | Page number to retrieve (increment to fetch next page) | | requestPageDetails.pageSize | number | ✅ Yes | Number of records per page | | sortOptions | array | ❌ No | Sorting rules for query results | | whereClause | string | ❌ No | SQL-like conditional filter expression | --- ## 8️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/cursor \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "requestPageDetails": { "pageNumber": 1, "pageSize": 500 }, "sortOptions": [ { "columnName": "first_name", "direction": "DESC" },{ "columnName": "last_updated", "direction": "ASC" } ], "whereClause": "(`first_name` like '%d%' and `years_of_experience` > 4 and `start_date` between '2004-01-01' and '2009-12-31' and `is_active` = true)" }' ``` --- ## 9️⃣ Behavior Summary ``` Retrieves workbook records using cursor-based pagination. Supports: • Dynamic filtering using whereClause • Multi-field sorting using sortOptions • Efficient pagination traversal using pageNumber and pageSize • Large dataset handling without loading entire workbook data ``` # Get Workbook Schema Source: https://api-docs.datagol.ai/api-reference/workbook/get-workbook-schema /openapi/openapi.yaml get /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId} ## 1️⃣ Overview **Purpose:** Retrieves metadata and detailed information about a specific workbook within a workspace. --- ## 2️⃣ Endpoint ``` bash GET /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId} ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Workbook (table) identifier | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 6️⃣ Example Request ``` bash curl -X GET https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId} \ -H "Authorization: Bearer " ``` --- ## 7️⃣ Behavior Summary ``` Retrieves workbook metadata and configuration details. Returns workbook properties including: • Workbook title and description • Table type and structure • Column definitions • UI metadata • Workspace association information ``` # Update Column Source: https://api-docs.datagol.ai/api-reference/workbook/update-column /openapi/openapi.yaml put /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/columns/{columnId} ## 1️⃣ Overview **Purpose:** Updates an existing column's metadata and configuration within a specified table in a workspace. This endpoint supports: - Updating column display name - Changing UI data type - Updating UI metadata (title, precision, etc.) - Modifying column options --- ## 2️⃣ Endpoint ``` PUT /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/columns/{columnId} ````` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Workspace identifier | | workbookId | UUID | ✅ Yes | Table identifier | | columnId | UUID | ✅ Yes | Column identifier | --- ## 4️⃣ Authentication Requires **Bearer JWT Token** ``` Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "id": "uuid", "name": "string", "uiDataType": "string", "colOptions": {}, "uiMetadata": { "title": "string", "precision": null } } ``` --- ## 7️⃣ Field Descriptions ### Column Configuration | Field | Type | Required | Description | | --- | --- | --- | --- | | id | UUID | ✅ Yes | Unique identifier of the column to update | | name | string | ✅ Yes | Internal column name | | uiDataType | string | ✅ Yes | Column type (e.g., SINGLE_LINE_TEXT, NUMBER, DATE) | | uiMetadata | object | ✅ Yes | Metadata for UI display | | uiMetadata.title | string | ✅ Yes | Display name shown in the UI | | --- ## 8️⃣ Example Request ``` bash curl -X PUT https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/columns/{columnId} \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "id": "6d9ae325-6fcd-4bd6-a732-b59e424fc095", "name": "question", "uiDataType": "SINGLE_LINE_TEXT", "colOptions": {}, "uiMetadata": { "title": "Question", "precision": null } }' ``` --- ## 9️⃣ Behavior Summary ``` id="behcol3" Updates an existing column's metadata and configuration. Supports: • Updating internal column name • Changing UI data type • Updating display title via uiMetadata • Setting precision for numeric columns • Passing additional column options via colOptions • Server-side validation before update ``` # Update Row In Workbook Source: https://api-docs.datagol.ai/api-reference/workbook/update-row-in-workbook /openapi/openapi.yaml put /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows # 1️⃣ Overview **Purpose:** Updates an existing row in a specified table within a workspace. This endpoint allows: - Updating one or more column values in a row - Triggering AI column regeneration (if dependent fields change) - Recomputing formulas (if applicable) --- ## 2️⃣ Endpoint ``` PUT /noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows ```````` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Identifier of the workspace | | workbookId | UUID | ✅ Yes | Identifier of the table | --- ## 4️⃣ Authentication Requires Authorization ``` Authorization: Bearer ``` --- ## 5️⃣ Required Permissions User must have: - Row edit permission - Table edit access - Workspace access If row updates affect: - AI columns → AI execution permission required - Formula columns → system recalculates automatically --- ## 6️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | ## 7️⃣ Request Body Schema ``` { "id": "number | string", "cellValues": { "columnName": "value" } ``` --- ## 8️⃣ Field Descriptions | Field | Type | Required | Description | | --- | --- | --- | --- | | id | Row identifier | ✅ Yes | Unique row ID | | cellValues | Object | ❌ | Key-value map using column names | --- ## 9️⃣ Example Request ``` curl -X PUT \https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/tables/{workbookId}/rows \-H "Authorization: Bearer " \-H "Content-Type: application/json" \-d '{ "id": 1, "cellValues": { "name": "dega" } ``` --- ## AI Column Interaction If the table contains AI-enabled columns: - Updating dependent fields may: - Automatically regenerate AI values - Trigger asynchronous processing - If AI column is manual-override enabled: - System may preserve manual values --- ## ✅ Validation Rules - Row ID must exist - Cannot update system-generated columns - Cannot update formula-only columns - Data must match column type - Required columns cannot be null --- # Add User to Workspace Source: https://api-docs.datagol.ai/api-reference/workspaces/add-user-to-workspace /openapi/openapi.yaml post /noCo/api/v2/workspaces/{workspaceId}/bulkUsers ## 1️⃣ Overview **Purpose:** Allows adding multiple users to a specific workspace in a single request. Each user is assigned a role within the workspace. Upon being added, the invited user receives an email containing a registration link with a unique `hash` and `type` as query parameters: ``` http:///register?hash=e0754cfc-f7d1-4cc3-8690-e34a2f17291d&type=WORK_SPACE ``` - `hash` — A unique UUID tied to the workspace invitation. Must be passed in the sign-up API to complete registration. - `type` — Indicates the invitation context. `WORK_SPACE` means the user is being invited to a workspace. --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces/{workspaceId}/bulkUsers ``` --- ## 3️⃣ Path Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workspaceId | UUID | ✅ Yes | Identifier of the workspace | --- ## 4️⃣ Authentication Requires authentication using: ``` bash Authorization: Bearer ``` --- ## 5️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 6️⃣ Request Body Schema ``` json { "workSpaceUsers": [ { "email": "string", "role": "string" } ], "message": "string" } ``` --- ## 7️⃣ Field Descriptions ### Workspace Users | Parameter | Type | Required | Description | | --- | --- | --- | --- | | workSpaceUsers | array | ✅ Yes | List of users to be added to the workspace | | workSpaceUsers.email | string | ✅ Yes | Email ID of the user | | workSpaceUsers.role | string | ✅ Yes | Role assigned in the workspace (CREATOR, EDITOR, VIEWER) | | message | string | ❌ No | Optional message sent along with the invite | --- ## 8️⃣ Invitation Flow Once this API is called successfully, the invited user receives an email with a registration link: ``` http:///register?hash=e0754cfc-f7d1-4cc3-8690-e34a2f17291d&type=WORK_SPACE ``` The user must use this link to complete their registration by calling: ``` POST /idp/api/v1/user/sign-up ``` With the `hash` extracted from the link: ``` json { "email": "user@example.com", "password": "password123", "firstname": "John", "lastname": "Doe", "hash": "e0754cfc-f7d1-4cc3-8690-e34a2f17291d" } ``` > ⚠️ The `hash` is single-use and time-limited. If expired, the workspace admin must re-invite the user. --- ## 9️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces/{workspaceId}/bulkUsers \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "workSpaceUsers": [ { "email": "user1@datagol.com", "role": "EDITOR" }, { "email": "user2@datagol.com", "role": "VIEWER" } ], "message": "Workspace access invitation" }' ``` --- ## 🔟 Behavior Summary ``` Enables bulk addition of users to a workspace and assigns roles to each user. • Role Assignment — Each user is assigned CREATOR, EDITOR, or VIEWER role. • Invitation Email — Each invited user receives an email with a registration link containing a unique hash and type=WORK_SPACE. • Hash-Based Registration — The invited user must use the hash from the email link to complete sign-up via POST /idp/api/v1/user/sign-up. • OTP Not Required — Workspace-invited users are activated via hash validation and do not go through the OTP verification step. ``` # Create Workspace Source: https://api-docs.datagol.ai/api-reference/workspaces/create-workspace /openapi/openapi.yaml post /noCo/api/v2/workspaces ## 1️⃣ Overview **Purpose:** Creates a new workspace in the DataGOL Platform. Workspaces help organize users, resources, and configurations within the platform. --- ## 2️⃣ Endpoint ``` bash POST /noCo/api/v2/workspaces ``` --- ## 3️⃣ Authentication Requires authentication using: ``` id="l8v3z7" Authorization: Bearer ``` --- ## 4️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | | Content-Type: application/json | ✅ Yes | --- ## 5️⃣ Request Body Schema ``` json { "name": "string", "description": "string" } ``` --- ## 6️⃣ Field Descriptions ### Workspace Fields | Field | Type | Required | Description | | --- | --- | --- | --- | | name | string | ✅ Yes | The display name of the workspace | | description | string | ❌ No | A brief description of the workspace (can be an empty string) | --- ## 7️⃣ Example Request ``` bash curl -X POST https://be.datagol.ai/noCo/api/v2/workspaces \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "Sales Workspace", "description": "Workspace for sales team data" }' ``` --- ## 8️⃣ Behavior Summary Creates a new workspace in the DataGOL Platform to organize users, resources, and configurations. # Get All Workspaces Source: https://api-docs.datagol.ai/api-reference/workspaces/get-all-workspaces /openapi/openapi.yaml get /noCo/api/v2/workspaces ## 1️⃣ Overview **Purpose:** Retrieves the list of all workspaces accessible to the authenticated user or service account. --- ## 2️⃣ Endpoint ``` bash GET /noCo/api/v2/workspaces ``` --- ## 3️⃣ Authentication Requires Bearer-style authentication using: ``` Authorization: Bearer ``` --- ## 4️⃣ Request Headers | Header | Required | | --- | --- | | Authorization | ✅ Yes | --- ## 5️⃣ Example Request ``` bash curl -X GET https://be.datagol.ai/noCo/api/v2/workspaces \ -H "Authorization: Bearer " ``` --- ## 6️⃣ Behavior Summary This endpoint returns all workspaces that are accessible to the authenticated user or service account. It supports workspace-level access control and filters results based on user permissions. # DataGOL Custom Agents API Source: https://api-docs.datagol.ai/custom-agents Complete reference for creating, configuring, and interacting with Custom AI Agents on the DataGOL platform — including connectors, MCP servers, sub-agents, voice, and streaming. ## Overview DataGOL Custom Agents are fully configurable AI assistants that combine your company's data sources (workspaces, knowledge bases, connectors), external tools (MCP servers), sub-agents, and voice capabilities into a single deployable interface. The lifecycle of a Custom Agent is organized into the following groups: ### Create Agent `POST /customAgents/api/v1` — define the agent's identity, data connectors, MCP tools, and UI behavior. Returns the `agentId` used in every subsequent call. ### Create a thread `POST /ai/api/v2/conversations` — create the conversation record, embedding the agent ID, selected model, and scope (`PRIVATE` / `SHARED`). Returns the `conversationId` required for streaming. ### Converse `POST /ai/api/v2/messages/streaming` — send the user message and receive the agent's SSE-streamed response. Pass `selectedLlmModel` to switch models per message. ### Sharing and Permissions `GET /noCo/api/v2/elementPermissions/CUSTOM_AGENT/{agentId}` — verify who currently has access to the agent. `GET /idp/api/v1/team` — fetch the full team roster to populate the share dialog with user IDs and display names. `POST /noCo/api/v2/elementPermissions/bulk` — grant `CREATOR`, `EDITOR`, or `VIEWER` access to selected team members by `userId`. ### Misc `POST /ai/api/v1/builder/chat/complete?resourceType=CUSTOM_AGENT&resourceId={agentId}` — called client-side when the user types their first message. Uses `gpt-4o-mini` + a tool call to produce a concise 5-word conversation title before the conversation record is created. *** ## Authentication Every request to the DataGOL backend requires a signed JWT passed as a Bearer token. Tokens are issued by the DataGOL Identity Provider (`/idp`) after login. They embed the user's `companyId`, `userId`, roles, and permissions. Tokens are short-lived — refresh them before they expire. ### Required headers for every request | Header | Value | Required | | --------------- | -------------------- | -------- | | `Authorization` | `Bearer ` | **Yes** | | `Content-Type` | `application/json` | **Yes** | | `Accept` | `*/*` | Yes | ### Optional / contextual headers | Header | Value | When to send | | ------------- | ------------------------------ | ------------------------------------------ | | `Referer` | `https://your-app.datagol.ai/` | Recommended — used for CORS validation | | `Origin` | `https://your-app.datagol.ai` | Required for cross-origin browser requests | | `credentials` | `include` | Required only for the Streaming API | Never include raw browser-only headers (`sec-ch-ua`, `sec-fetch-*`) in server-to-server calls. They are browser hints and will be ignored or may cause unexpected behavior. *** ## Base URLs | Service | Environment | Base URL | Purpose | | ----------- | ----------- | ----------------------- | -------------------------------------- | | Backend API | Production | `https://be.datagol.ai` | Agent CRUD, conversations, permissions | | AI Core | Production | `https://ai.datagol.ai` | Chat completion, streaming | *** ## Reference APIs ### Supporting Lookups Before creating an agent you will typically fetch the IDs you need: *** #### GET List All Custom Agents ```bash cURL theme={null} curl 'https://be.datagol.ai/customAgents/api/v1' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` **`GET /customAgents/api/v1`** Returns all Custom Agents accessible to the authenticated user within their company tenant. **Response** — array of agent summaries including `id`, `name`, `description`, `isPublished`, and `configs`. *** #### GET Get Custom Agent by ID **`GET /customAgents/api/v1/{agentId}`** The UUID of the Custom Agent returned from the create or list endpoint. ```bash cURL theme={null} curl 'https://be.datagol.ai/customAgents/api/v1/f1c6ff59-f4b7-476e-b306-f8531b42863d' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` *** #### GET List All Workspaces **`GET /noCo/api/v2/workspaces`** Returns all workspaces in the company tenant. Use `id` values as `workspaceId` in connector objects. ```bash cURL theme={null} curl 'https://be.datagol.ai/noCo/api/v2/workspaces' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` *** #### GET Search Workspaces and Workbooks **`GET /noCo/api/v2/workspaces/search`** Used by the **Knowledge Base** section in the agent builder UI. Returns a flat list of all workbooks (type `TABLE`) across every workspace the authenticated user can access. Group the results by `workspaceId` / `workspaceName` to render the workspace → workbook tree shown in the UI. This is the endpoint you should call when populating the workbook picker. Unlike `GET /noCo/api/v2/workspaces` (which returns workspace metadata only), this endpoint returns the individual workbooks inside each workspace in a single call. **Query parameters:** | Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------------------------------------------------------------------- | | `query` | string | No | Free-text filter on workbook / workspace name. Pass empty string or omit for all. | | `type` | string | **Yes** | Must be `TABLE` to retrieve workbooks. | ```bash cURL theme={null} curl 'https://be.datagol.ai/noCo/api/v2/workspaces/search?query=&type=TABLE' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` **Response** — flat array of workbook objects. Each item carries the parent `workspaceId` and `workspaceName` so you can group them client-side. **Response item fields:** | Field | Type | Description | | ------------------------- | ------- | ---------------------------------------------------------------------------------------- | | `id` | UUID | Workbook UUID — use as `id` in `WORKBOOK_RAG` connector objects | | `name` | string | Workbook display name | | `description` | string | Optional content description | | `workspaceId` | UUID | Parent workspace UUID — use to group workbooks by workspace | | `workspaceName` | string | Parent workspace display name | | `workspaceCreatedBy` | integer | User ID of the workspace owner | | `tableCreatedBy` | integer | User ID who created the workbook | | `uiMetadata.dataProvider` | string | Storage backend: `JDBC`, `SPARK`, `SNOWFLAKE`, `BIGQUERY`, `REDSHIFT`, `ATHENA`, `MYSQL` | | `uiMetadata.title` | string | Optional display title override | | `uiMetadata.favorite` | boolean | Whether the workbook is marked as a favourite | **Example response (trimmed):** ```json theme={null} [ { "type": "TABLE", "isFolder": false, "id": "ec345675-06bf-4133-b8c3-f8fc1934b839", "name": "dg_order_item.csv", "description": "", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "workspaceName": "Link_v2", "workspaceCreatedBy": 371, "tableCreatedBy": 371, "uiMetadata": { "dataProvider": "JDBC" } }, { "type": "TABLE", "isFolder": false, "id": "ca45078d-ed26-4752-a7a7-4aed24af033c", "name": "dg_Order.csv", "description": "", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "workspaceName": "Link_v2", "workspaceCreatedBy": 371, "tableCreatedBy": 371, "uiMetadata": { "dataProvider": "JDBC" } }, { "type": "TABLE", "isFolder": false, "id": "bb3f3d22-bdef-45ec-8723-08f874e42247", "name": "Airbnb - SNOWFLAKE", "description": "", "workspaceId": "c50161cf-14dd-42a5-9b62-f8b6d89b48e9", "workspaceName": "BI Sanity (Bi team only)", "workspaceCreatedBy": 280, "tableCreatedBy": 41, "uiMetadata": { "dataProvider": "SNOWFLAKE" } } // ... more workbooks grouped across workspaces ] ``` To build the workspace → workbook tree, reduce the flat array by `workspaceId`: ```js theme={null} const tree = results.reduce((acc, item) => { const ws = acc[item.workspaceId] ?? { name: item.workspaceName, workbooks: [] }; ws.workbooks.push({ id: item.id, name: item.name }); acc[item.workspaceId] = ws; return acc; }, {}); ``` The workbook `id` can then be used directly as the connector `id` in `WORKBOOK_RAG` objects. *** #### GET List All Connectors **`GET /connector/api/v1/instance`** Returns all AI connectors (type `CONNECTOR` / `sourceType: AI`) available to the tenant. Use connector `id` values in the `configs.connectors` array. ```bash cURL theme={null} curl 'https://be.datagol.ai/connector/api/v1/instance' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` *** #### GET List Team Members **`GET /idp/api/v1/team`** Returns all users in the company. Use `userId` values when sharing an agent. ```bash cURL theme={null} curl 'https://be.datagol.ai/idp/api/v1/team' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` *** #### GET List All Conversations **`GET /ai/api/v2/conversations`** Returns the list of all conversations for the authenticated user. *** *** ## POST Create Custom Agent **`POST /customAgents/api/v1`** Creates a fully configured Custom AI Agent. This is the most complex endpoint — every field is documented below. ```bash cURL theme={null} curl --location 'https://be.datagol.ai/customAgents/api/v1' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '' ``` *** ### `uiMetadata` — UI Presentation Layer Controls how the agent looks and behaves in the DataGOL chat interface. Defines which UI capabilities are enabled for this agent. Whether users can download the chat conversation as a file. * `true` — A download button appears in the conversation toolbar. * `false` — Download is disabled. Model selector configuration shown in the chat UI. Whether users can switch models mid-conversation. * `true` — A model selector dropdown is shown in the chat header. * `false` — The default model is locked; no switcher is displayed. List of model IDs available in the selector. Users can only pick from this list. **Supported values (as of May 2026):** | Model ID | Provider | | --------------------------- | ----------------------- | | `gpt-5.2` | OpenAI | | `gpt-4.1` | OpenAI | | `o4-mini` | OpenAI | | `vertex_ai/claude-opus-4-7` | Anthropic via Vertex AI | | `claude-sonnet-4-6` | Anthropic | | `claude-haiku-4-5-20251001` | Anthropic | | `claude-opus-4-6` | Anthropic | The model pre-selected when a conversation starts. Must be in `supportedModels`. **Example:** `"gpt-5.2"` Whether users can upload files (PDFs, CSVs, images) into the conversation for the agent to analyze. * `true` — File upload button is shown in the chat input area. * `false` — File upload is hidden. Background color for the agent logo bubble. Accepts any valid CSS color value (hex, rgb, named). **Example:** `"#1a1a2e"` | `""` (empty = use default) Text/icon color rendered on top of the logo background. **Example:** `"#ffffff"` | `""` (empty = use default) Placeholder text in the chat input box. Use this to hint at what the agent specializes in. **Example:** `"What is EBITDA? And How Its Calculated"` **Default:** `""` (empty = generic placeholder) Tags that describe ideal use cases for this agent. Displayed as chips in the agent discovery UI. **Example:** `["Financial Analysis", "P&L Reports", "KPI Extraction"]` **Default:** `[]` Suggested opening messages shown to users before they start typing. Each item renders as a clickable button in the chat. **Example:** `["What is EBITDA?", "Summarize Q1 revenue", "Show me the cost breakdown"]` **Default:** `[]` Custom logo for the agent card. Set to `null` to use the default DataGOL icon. **Default:** `null` *** ### `configs` — Agent Runtime Configuration The `configs` object is the brain of the agent — it defines every data source, tool, and capability the agent can access at runtime. *** #### `configs.connectors` — Data Sources Array of data connectors the agent can retrieve information from. Supports three distinct connector types. UUID of the data source. For `WORKBOOK_RAG` and `WORKSPACE_DOCUMENTS`, this is the workbook/workspace UUID. For `KNOWLEDGE_BASE`, this is the knowledge base UUID. For `CONNECTOR`, this is the numeric connector instance ID (as a string). Determines how the agent retrieves data from this source. | Value | Behavior | | --------------------- | -------------------------------------------------------------------------------------------------- | | `WORKBOOK_RAG` | RAG (Retrieval Augmented Generation) over a single workbook file (CSV, Excel, etc.) in a workspace | | `WORKSPACE_DOCUMENTS` | RAG over all documents in an entire workspace | | `KNOWLEDGE_BASE` | Searches a synced knowledge base (Google Drive, Web, etc.) | | `CONNECTOR` | Routes to an AI-side connector instance for real-time data access | Where the connector data comes from. | Value | Meaning | | --------- | ------------------------------------------------------ | | `BACKEND` | Data indexed and served by the DataGOL backend | | `AI` | Data fetched live by the AI microservice at query time | Type-specific metadata. See breakdown below by connector type. *** **Type: `WORKBOOK_RAG`** — Single file RAG Attaches a specific workbook file for the agent to search over using vector retrieval. ```json theme={null} { "id": "ec345675-06bf-4133-b8c3-f8fc1934b839", "type": "WORKBOOK_RAG", "sourceType": "BACKEND", "data": { "title": "dg_order_item.csv", "description": "Order line items with quantities and prices", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "workspaceName": "Link_v2" } } ``` Display name of the workbook file (typically the filename). Optional description of the file content to help the agent understand what data it contains. UUID of the workspace containing this workbook. Fetch from `GET /noCo/api/v2/workspaces`. Display name of the workspace. Used in UI labels. *** **Type: `WORKSPACE_DOCUMENTS`** — Full workspace RAG Attaches an entire workspace — every document in it becomes searchable by the agent. ```json theme={null} { "id": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "type": "WORKSPACE_DOCUMENTS", "sourceType": "BACKEND", "data": { "name": "Link_v2" } } ``` Display name of the workspace. *** **Type: `KNOWLEDGE_BASE`** — Synced external knowledge Connects the agent to a synced knowledge base (Google Drive folder, web scrape, etc.). The `data` object is the full knowledge base entity returned by the knowledge base API. ```json theme={null} { "id": "bca6c483-9205-4724-81e3-f4340b79efbc", "type": "KNOWLEDGE_BASE", "sourceType": "BACKEND", "data": { "id": "bca6c483-9205-4724-81e3-f4340b79efbc", "companyId": 1, "userId": 371, "type": "GOOGLE_DRIVE", "name": "Mahi Changes Verifications", "status": "ACTIVE", "lastSyncAt": "2026-05-01T18:56:45.544+0000", "lastSyncStatus": "SUCCESS", "sourceId": null, "credentialId": 7219087, "activeConfig": null, "latestRun": { "id": "036f1723-1b57-4e06-9295-17bb24fdbd58", "connectorId": "bca6c483-9205-4724-81e3-f4340b79efbc", "runType": "INCREMENTAL", "status": "SUCCESS", "temporalWorkflowId": "kb-sync-036f1723-1b57-4e06-9295-17bb24fdbd58", "startedAt": "2026-05-01T18:56:44.855+0000", "finishedAt": "2026-05-01T18:56:45.543+0000", "errorMessage": null, "statsJson": {}, "checkpointJson": null } } } ``` Same as the connector `id`. Tenant company ID. ID of the user who created the knowledge base. Knowledge base source type. | Value | Source | | -------------- | -------------------------- | | `GOOGLE_DRIVE` | Google Drive folder | | `WEB` | Web scrape / website crawl | Display name of the knowledge base. `ACTIVE` or `INACTIVE`. Timestamp of the last successful sync. `SUCCESS` or `FAILED`. ID of the OAuth credential used to access the source. `null` for open sources like web. Details of the most recent sync run. `INCREMENTAL` or `FULL`. `SUCCESS`, `FAILED`, or `RUNNING`. Sync statistics — e.g. `{ "total": 49, "failed": 0, "completed": 49 }`. *** **Type: `CONNECTOR`** — AI-side live connector Routes queries to a live connector instance managed by the AI microservice (e.g. a database connector, API connector). ```json theme={null} { "id": "315", "type": "CONNECTOR", "sourceType": "AI" } ``` Numeric connector instance ID (as a string). Obtain from `GET /connector/api/v1/instance`. *** #### `configs.mcpConfigs` — MCP Tool Servers Array of MCP (Model Context Protocol) server configurations. MCP servers expose tools (functions) the agent can invoke during reasoning — e.g. querying a live database, calling a Slack webhook, or reading from a workspace. ```json theme={null} [ { "id": 18, "name": "Workspace MCP", "description": "Access Link_v2 workspace data in real time", "url": "https://testing-mcp.datagol.ai/workspace/...", "transport": "streamable_http", "serverType": "CUSTOM", "companyId": 1 } ] ``` Unique ID of the MCP server record. Assigned by the platform when the server is registered. Display name shown in the agent builder UI and tool call traces. Description of what tools this MCP server exposes. Full URL of the MCP server endpoint. For `WORKBOOK` serverType this can be empty — the platform resolves it from `data`. **Example:** `"https://testing-mcp.datagol.ai/workspace/link-v2?workspace_id=...&token=..."` Protocol used to communicate with the MCP server. | Value | Protocol | | ----------------- | ----------------------------------------- | | `streamable_http` | HTTP with streaming support (recommended) | Where the MCP server is hosted. | Value | Meaning | | ---------- | ----------------------------------------------------------- | | `CUSTOM` | An externally hosted MCP server (n8n, custom API, etc.) | | `WORKBOOK` | A DataGOL-managed MCP server backed by a workspace workbook | Tenant scoping — the company ID this MCP server belongs to. Required only for `serverType: WORKBOOK`. Contains the workbook and workspace IDs used to resolve the server URL automatically. ```json theme={null} { "id": "ca45078d-ed26-4752-a7a7-4aed24af033c", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53" } ``` *** #### `configs.webSearchEnabled` Enables real-time web search. When `true`, the agent can search the internet to supplement its responses with up-to-date information. * `true` — A web search tool is injected into the agent's tool set. * `false` — Agent is restricted to its configured data sources only. *** #### `configs.skillIds` Numeric IDs of skills attached to this agent. The AI engine uses these IDs to load the corresponding skill content at runtime. **Example:** `[10, 11]` *** ### Top-Level Fields Controls whether the agent is visible and usable by team members beyond the creator. * `false` — Draft mode. Only the creator can access it. * `true` — Published. Users with shared permissions can open and chat with the agent. The system prompt injected at the start of every conversation with this agent. This is the core instruction set — be specific about role, output format, and behavior. **Example:** ``` Scan this document and extract all key metrics, numbers, and quantitative statements (such as revenue, costs, growth rates, counts, targets, and timelines). Organize them into a structured table with columns for metric name, value, unit, date or period, and a short description of what the metric represents. ``` A short human-readable description of what the agent does. Shown in the agent card in the UI. **Example:** `"This Agent Details you through the Complete financial related Data"` Display name of the agent. Shown in the agent list and chat header. **Example:** `"Financial Agent"` ### Complete Request Example ```json theme={null} { "name": "Financial Agent", "description": "This Agent Details you through the Complete financial related Data", "prompt": "Scan this document and extract all key metrics, numbers, and quantitative statements (such as revenue, costs, growth rates, counts, targets, and timelines). Organize them into a structured table with columns for metric name, value, unit, date or period, and a short description of what the metric represents. If there are assumptions or caveats around specific numbers, briefly note those as well.", "isPublished": false, "uiMetadata": { "bestFor": [], "conversationStarters": [], "logo": null, "style": { "logo": { "bgColor": "", "textColor": "" } }, "input": { "placeholder": "What is EBITDA? And How Its Calculated" }, "capabilities": { "models": { "enabled": true, "supportedModels": [ "gpt-5.2", "vertex_ai/claude-opus-4-7", "claude-sonnet-4-6", "claude-haiku-4-5-20251001", "o4-mini" ], "defaultValue": "gpt-5.2" }, "allowDownload": true, "conversationFiles": { "enabled": true } } }, "configs": { "mcpConfigs": [ { "id": 18, "name": "Workspace MCP", "description": "", "url": "https://testing-mcp.datagol.ai/workspace/link-v2?workspace_id=a336506d-540e-4a78-809b-daf501687bca&token=", "transport": "streamable_http", "serverType": "CUSTOM", "companyId": 1 }, { "id": 35, "name": "New MCP Server", "description": "", "url": "Financial Sub Agent", "transport": "streamable_http", "serverType": "CUSTOM", "companyId": 1 }, { "serverType": "WORKBOOK", "name": "dg_Order.csv", "description": "", "url": "", "transport": "streamable_http", "data": { "id": "ca45078d-ed26-4752-a7a7-4aed24af033c", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53" } }, { "serverType": "WORKBOOK", "name": "Install Metrics", "description": "", "url": "", "transport": "streamable_http", "data": { "id": "3095f6c0-b399-4e0f-b367-7db38b0a8453", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53" } } ], "connectors": [ { "id": "ec345675-06bf-4133-b8c3-f8fc1934b839", "type": "WORKBOOK_RAG", "sourceType": "BACKEND", "data": { "title": "dg_order_item.csv", "description": "", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "workspaceName": "Link_v2" } }, { "id": "753bd2d1-3426-41f2-b78d-a24a5a4cb0dd", "type": "WORKBOOK_RAG", "sourceType": "BACKEND", "data": { "title": "dg_customer.csv", "description": "", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "workspaceName": "Link_v2" } }, { "id": "ca45078d-ed26-4752-a7a7-4aed24af033c", "type": "WORKBOOK_RAG", "sourceType": "BACKEND", "data": { "title": "dg_Order.csv", "description": "", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "workspaceName": "Link_v2" } }, { "id": "aff24e82-564b-468a-9727-392a08f017bc", "type": "WORKBOOK_RAG", "sourceType": "BACKEND", "data": { "title": "dg_products.csv", "description": "", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "workspaceName": "Link_v2" } }, { "id": "3095f6c0-b399-4e0f-b367-7db38b0a8453", "type": "WORKBOOK_RAG", "sourceType": "BACKEND", "data": { "title": "Install Metrics", "description": "", "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "workspaceName": "Link_v2" } }, { "id": "055b4db3-96e1-45e1-8ff5-3a911b779a53", "type": "WORKSPACE_DOCUMENTS", "sourceType": "BACKEND", "data": { "name": "Link_v2" } }, { "id": "bca6c483-9205-4724-81e3-f4340b79efbc", "type": "KNOWLEDGE_BASE", "sourceType": "BACKEND", "data": { "id": "bca6c483-9205-4724-81e3-f4340b79efbc", "companyId": 1, "userId": 371, "type": "GOOGLE_DRIVE", "name": "Mahi Changes Verifications", "status": "ACTIVE", "lastSyncAt": "2026-05-01T18:56:45.544+0000", "lastSyncStatus": "SUCCESS", "sourceId": null, "credentialId": 7219087, "activeConfig": null, "latestRun": { "id": "036f1723-1b57-4e06-9295-17bb24fdbd58", "connectorId": "bca6c483-9205-4724-81e3-f4340b79efbc", "runType": "INCREMENTAL", "status": "SUCCESS", "temporalWorkflowId": "kb-sync-036f1723-1b57-4e06-9295-17bb24fdbd58", "startedAt": "2026-05-01T18:56:44.855+0000", "finishedAt": "2026-05-01T18:56:45.543+0000", "errorMessage": null, "statsJson": {}, "checkpointJson": null } } }, { "id": "315", "type": "CONNECTOR", "sourceType": "AI" } ], "webSearchEnabled": true, "skillIds": [ 10, 11 ] } } ``` ### Response ```json theme={null} { "id": "7bf5f4d6-743d-414f-aa4a-96f7a20ce0fd", "name": "Financial Agent", "description": "This Agent Details you through the Complete financial related Data", "isPublished": false, "prompt": "...", "configs": { "..." }, "uiMetadata": { "..." }, "skills": [ "..." ], "createdAt": "2026-05-18T10:00:00.000+0000", "updatedAt": "2026-05-18T10:00:00.000+0000" } ``` *** ## POST Share Agent (Bulk Permissions) **`POST /noCo/api/v2/elementPermissions/bulk`** Grants one or more users access to a Custom Agent. ```bash cURL theme={null} curl --location 'https://be.datagol.ai/noCo/api/v2/elementPermissions/bulk' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "permissions": [ { "elementId": "7bf5f4d6-743d-414f-aa4a-96f7a20ce0fd", "elementType": "CUSTOM_AGENT", "userId": 935, "permission": "CREATOR" } ] }' ``` Array of permission grants to apply in a single atomic operation. UUID of the Custom Agent to share. Returned by the create or list agent endpoint. Must be `"CUSTOM_AGENT"` for agent sharing. ID of the user to grant access to. Fetch from `GET /idp/api/v1/team`. Permission level to grant. | Value | Can View | Can Edit | Can Delete | Can Share | | --------- | -------- | -------- | ---------- | --------- | | `VIEWER` | Yes | No | No | No | | `EDITOR` | Yes | Yes | No | No | | `CREATOR` | Yes | Yes | Yes | Yes | *** ## GET Custom Agent Permissions **`GET /noCo/api/v2/elementPermissions/CUSTOM_AGENT/{agentId}`** Returns all users who have access to the specified agent and their permission levels. UUID of the Custom Agent. ```bash cURL theme={null} curl 'https://be.datagol.ai/noCo/api/v2/elementPermissions/CUSTOM_AGENT/7bf5f4d6-743d-414f-aa4a-96f7a20ce0fd' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` *** ## POST Generate Conversation Name **`POST /ai/api/v1/builder/chat/complete`** *(AI Core service)* Generates a concise conversation name based on the user's first message. Called automatically after the first message is sent. **Query params:** | Param | Value | | -------------- | ------------------------ | | `resourceType` | `CUSTOM_AGENT` | | `resourceId` | UUID of the Custom Agent | ````json Request Body theme={null} { "model": "gpt-4o-mini", "messages": [ { "role": "system", "content": "You are an advanced AI conversation assistant. Generate a clear and concise name for the conversation that accurately reflects its main topic. Keep it to max 5 words." }, { "role": "user", "content": "First User Message:\n```\nSummarise the data\n```" } ], "tools": [ { "type": "function", "function": { "name": "generate_conversation_name", "description": "Use this function to generate a conversation name based on the first user message", "parameters": { "type": "object", "properties": { "conversation_name": { "type": "string", "description": "A clear and concise name for the conversation that reflects its main topic" } }, "required": ["conversation_name"] } } } ], "tool_choice": "auto" } ```` *** ## POST Initiate Conversation **`POST /ai/api/v2/conversations`** Opens a new conversation session backed by a Custom Agent. Returns a `conversationId` required for the streaming endpoint. ```bash cURL theme={null} curl --location 'https://be.datagol.ai/ai/api/v2/conversations' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "name": "Data Summary Request", "active": true, "scope": "PRIVATE", "userId": 371, "agentType": "CustomAgent", "uiMetadata": { "type": "CustomAgent", "parameters": { "customAgentId": "1526da2b-3264-4118-b141-87857369b0bd", "parameters": { "customAgentId": "1526da2b-3264-4118-b141-87857369b0bd" } }, "configuration": { "llmModel": "gpt-5.2" } } }' ``` Display name for this conversation. Auto-generated by the naming API (step 3) or user-supplied. Always `true` when creating a new conversation. Visibility of the conversation. | Value | Behavior | | --------- | ------------------------------------------------ | | `PRIVATE` | Only the creating user can see this conversation | | `SHARED` | Visible to all users with access to the agent | ID of the authenticated user creating the conversation. Must match the token's `userId` claim. Must be `"CustomAgent"` for custom agent conversations. UUID of the Custom Agent that backs this conversation. Passed twice (at `parameters` and `parameters.parameters`) for backward compatibility. Active LLM model for this conversation. Must be a value from `uiMetadata.capabilities.models.supportedModels`. **Response** — returns a `conversationId` (UUID) used in the streaming endpoint. *** ## POST Streaming Message **`POST /ai/api/v2/messages/streaming`** *(AI Core service)* Sends a user message to the agent and streams the response as Server-Sent Events (SSE). This endpoint hits `ai.datagol.ai`, not `be.datagol.ai`. Ensure your HTTP client supports streaming responses (SSE). ```bash cURL theme={null} curl 'https://ai.datagol.ai/ai/api/v2/messages/streaming' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'credentials: include' \ -H 'Referer: https://app.datagol.ai/' \ --data-raw '{ "agentType": "CustomAgent", "type": "CustomAgent", "conversationId": "", "message": "Hi", "parameters": { "customAgentId": "" }, "uiMetadata": { "parameters": {} }, "selectedLlmModel": "gpt-5.4" }' ``` Must be `"CustomAgent"`. Must be `"CustomAgent"`. (Duplicates `agentType` for routing purposes.) The conversation ID returned by `POST /ai/api/v2/conversations`. The user's message text to send to the agent. UUID of the Custom Agent. Must match the agent that backs this conversation. The model to use for this specific message. Can be changed per message to switch models mid-conversation. Pass as `{ "parameters": {} }` unless overriding model-level parameters. **Response** — SSE stream of delta tokens and tool call events. Parse events with `data: ` prefix. ```text Sample Response theme={null} :heartbeat {"content":17534,"response_type":"message_id","metadata":null} :keep-alive {"content":"Hi.","response_type":"text","metadata":null} :keep-alive ``` | Field | Type | Description | | --------------- | ---------------- | --------------------------------------------------------------- | | `content` | string \| number | The text delta (or message ID on the first event) | | `response_type` | string | `"message_id"` for the first event; `"text"` for content chunks | | `metadata` | object \| null | Reserved for future use; currently `null` | *** ## GET Workspace by ID **`GET /noCo/api/v2/workspaces/{workspaceId}`** Fetches workspace details scoped to the current Custom Agent. Called when a user opens the agent from the side panel to load context-specific workspace data. **Query params:** | Param | Type | Description | | -------------- | ------ | --------------------- | | `resourceType` | string | Always `CUSTOM_AGENT` | | `resourceId` | UUID | The Custom Agent UUID | ```bash cURL theme={null} curl 'https://be.datagol.ai/noCo/api/v2/workspaces/055b4db3-96e1-45e1-8ff5-3a911b779a53?resourceType=CUSTOM_AGENT&resourceId=ac861ca7-d3c6-47ac-be63-abc49344b254' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' ``` *** ## Error Handling All endpoints return standard HTTP status codes. | Code | Meaning | Common Cause | | ----- | --------------------- | ----------------------------------------------------------------------- | | `200` | Success | — | | `400` | Bad Request | Malformed JSON, missing required fields | | `401` | Unauthorized | Missing or expired JWT token | | `403` | Forbidden | User lacks required permission (`CREATE_COPILOT`, `EDIT_COPILOT`, etc.) | | `404` | Not Found | Agent, workspace, or connector ID does not exist in this tenant | | `500` | Internal Server Error | Upstream AI service error or unhandled exception | *** ## Connector Type Quick Reference | Type | sourceType | Use Case | | --------------------- | ---------- | ----------------------------------------- | | `WORKBOOK_RAG` | `BACKEND` | RAG over a single CSV/Excel workbook | | `WORKSPACE_DOCUMENTS` | `BACKEND` | RAG over all files in a workspace | | `KNOWLEDGE_BASE` | `BACKEND` | Synced Google Drive or web knowledge base | | `CONNECTOR` | `AI` | Live data via AI connector instance | *** ## Model ID Reference | Model ID | Provider | Notes | | --------------------------- | -------------------- | ----------------------------------- | | `gpt-5.2` | OpenAI | GPT-5 series, high capability | | `gpt-4.1` | OpenAI | GPT-4.1 | | `o4-mini` | OpenAI | Reasoning model, faster and cheaper | | `vertex_ai/claude-opus-4-7` | Anthropic via Vertex | Claude Opus on GCP | | `claude-opus-4-6` | Anthropic | Claude Opus direct | | `claude-sonnet-4-6` | Anthropic | Claude Sonnet, balanced | | `claude-haiku-4-5-20251001` | Anthropic | Claude Haiku, fastest | # Introduction Source: https://api-docs.datagol.ai/introduction Get started with the DataGOL API and understand core concepts. Welcome to the **DataGOL API** documentation. This site documents the full API surface for workflows, connectors, widgets, identity, ETL, and more. Use the **API Reference** tab to browse and try endpoints. ## What you'll find here * **Documentation** — Overview and getting started (this section). * **API Reference** — Auto-generated reference from the OpenAPI spec, including request/response schemas and an interactive playground where supported. ## Base URL API requests use the base URL configured in the OpenAPI specification (for example, `https://www.domain.com`). Override it in the API playground if your environment uses a different host. ## Next steps Open the **API Reference** tab and pick an endpoint to view parameters, request bodies, and responses. # Links & Joins Source: https://api-docs.datagol.ai/links-joins LINK and LOOKUP are special workbook column types that enable relational data modeling across tables. ## Overview LINK and LOOKUP are special workbook column types that enable relational data modeling across tables. | Column Type | Purpose | | ----------- | ---------------------------------------------------- | | `LINK` | Defines a relationship between two tables | | `LOOKUP` | Projects columns from an associated table via a link | Both are configured through `ColumnDTO.colOptions`. A table can have multiple link columns, and each link can have multiple lookup columns. *** ## UI Data Types Special column used to represent inter-table relations. Special column used to project associated table fields via a link. *** ## LINK Semantics A LINK column stores metadata for: | Field | Description | | ---------------------- | ------------------------------- | | `workbookId` | Current table | | `associatedTableId` | Associated (linked) table | | `relationType` | Type of relationship | | `linkColumnId` | Link column identifier | | `associateWorkspaceId` | Associated Workspace identifier | **Supported relation patterns:** | Pattern | Description | | -------------- | --------------------------------------------------------------- | | `ONE_TO_ONE` | Each record in the source maps to one record in the destination | | `HAS_MANY` | One source record maps to many destination records | | `MANY_TO_MANY` | Many source records map to many destination records | *** ## LOOKUP Semantics A LOOKUP column is tightly coupled with a specific LINK column. * References a link using `linkColumnId` * Represents a selected column from the associated table * Multiple lookup columns can be defined for the same link *** ## Metadata in `ColumnDTO.colOptions` Use `colOptions` to persist link/lookup metadata. | Field | Description | | ---------------------- | ------------------------------------------------------------------------ | | `columnId` | Current column ID | | `tableId` | Current table ID | | `associatedTableId` | Associated workbook ID | | `associateWorkspaceId` | Associated workspace ID for the destination workbook | | `linkColumnId` | Link column ID — used by LOOKUP; references the LINK column's `columnId` | | `relationType` | Relation semantics for LINK | *** ## Manual Linking Record Flow To create manual record-level links: Fetch the associated workbook schema and data using the associate workspace Id. User selects associated record(s) to link. Send linking payload with `sourceRecordId`, `destinationRecordId`, and `linkColumnId`. Backend resolves link metadata from `linkColumnId` — relation type, associated table, and direction/constraints. Backend applies relation rules and stores the link relation. *** ## Record Linking Contract | Field | Description | | --------------------- | ------------------------------ | | `sourceRecordId` | PK of the current table row | | `destinationRecordId` | PK of the associated table row | | `linkColumnId` | LINK column identifier | | `tableId` | Current table ID | Backend derives all remaining relation metadata from the link configuration. *** ## Important Notes LINK and LOOKUP are **column-level constructs** first — record linking is a data-level operation built on top. * LOOKUP behavior depends on LINK existence and metadata integrity * With multiple links to the same associated table, each LOOKUP must bind to the correct `linkColumnId` * Always treat the associated row ID as the associated table PK for linking UI selection # API Reference Source: https://api-docs.datagol.ai/reference openapi/openapi.yaml # Workbook MCP — Tools And Connection Reference Source: https://api-docs.datagol.ai/workbook-mcp Public reference for the DataGOL Workbook MCP server, its tools, and how to connect. ## Overview The **DataGOL Workbook MCP** server exposes a single DataGOL workbook (table) over the **Model Context Protocol (MCP)**. Clients such as AI assistants, Cursor, or custom applications connect via **Streamable HTTP** and can read or write the workbook using the tools listed below. Always call **`get_table_schema`** first to get table metadata and column information before using other tools. ## MCP tools — quick reference | # | Tool | Purpose | | -- | --------------------------- | ------------------------------------------------------------------------- | | 1 | `get_table_schema` | Returns table and column metadata. **Call this first.** | | 2 | `query_table_data` | Fetches rows with filtering, sorting, and pagination (simple data fetch). | | 3 | `execute_query` | Runs complex SQL (aggregations, `GROUP BY`, `JOIN`s). | | 4 | `add_row` | Adds one row with given cell values. | | 5 | `update_row` | Updates an existing row by `row_id`. | | 6 | `add_row_comment` | Adds a comment on a row. | | 7 | `create_column` | Creates a new column (**DYNAMIC** tables only). | | 8 | `create_formula_column` | Creates a formula column (SQL expression). | | 9 | `create_ai_generate_column` | Creates an AI Generate column; optional bulk run. | | 10 | `run_ai_generate_bulk` | Runs AI generate on many rows (optionally filtered). | | 11 | `run_ai_generate_row` | Runs AI generate on a single row. | | 12 | `update_column` | Updates column name, title, description, type, formula, or options. | | 13 | `update_table` | Updates table title, description, or delete guard. | | 14 | `delete_column` | Deletes a column (when allowed by schema). | ## How to connect * **Endpoint**: `https://:/mcp` (Streamable HTTP) * **Required**: `workspace_id`, `table_id`, `token` (query string or headers) **Query string example** ```text theme={null} https://:/mcp?workspace_id=&table_id=&token= ``` **Headers (alternative)** * `X-Datagol-Workspace-Id` * `X-Datagol-Table-Id` * `X-Datagol-Token` * Optional: `X-Datagol-Host` **Health checks (no auth)**\ `GET /health` and `GET /ready` return `200` with: ```json theme={null} { "status": "ok" } ``` ## Schema first `get_table_schema` returns: * **`dataProvider`** — Backend (for example, PostgreSQL, Snowflake); use for the correct SQL / `WHERE` dialect. * **`tableType`** — `STATIC` (add rows, update column title only) or `DYNAMIC` (add / update columns). * **`connectionName`** — Table name to use in raw SQL for `execute_query`. * **`primaryKeyColumnName`** — Column whose value is the row ID; use as `row_id` in `update_row`, `add_row_comment`, `run_ai_generate_row`. * **`columns`** — IDs, names, types, and flags (for example, `isDataEditable`, `isDeletable`). Use this information to call other tools correctly. ## Data fetching — `query_table_data` vs `execute_query` | Use case | Tool | Notes | | --------------------------------------- | ------------------ | ---------------------------------------------------------- | | Simple filtering, sort, paginate | `query_table_data` | `where_clause`, `sort_column`, `page_number`, `page_size`. | | Aggregations (`SUM`, `COUNT`, `AVG`, …) | `execute_query` | Raw SQL with `GROUP BY`. | | Complex SQL (`JOIN`s, subqueries, etc.) | `execute_query` | Full SQL support; maximum 100 rows. | ## Tool details ### 1. `get_table_schema` Returns the full schema and metadata for the workbook table. * **Parameters**: *None* * **Returns**: Table metadata, columns (`id`, `name`, `uiDataType`, `uiMetadata`, flags), `dataProvider`, `tableType`, `connectionName`, `primaryKeyColumnName`. ### 2. `query_table_data` Fetches table data with optional filtering, sorting, and pagination.\ Use for simple data fetch (list rows with filters). Each row includes `id` (`row_id`) — use it with `update_row`, `add_row_comment`, or `run_ai_generate_row`. * **Parameters**: * `page_number` (optional, default `1`) * `page_size` (optional, default `100`, max `500`) * `where_clause` (optional) * `sort_column` (optional) * `sort_direction` (optional, default `"ASC"`) * `last_cursor_values` (optional, from previous response for next page) * **Returns**: `table_name`, `columns`, `total_records`, `page_number`, `total_pages`, `is_last_page`, `rows` (each with `id` + `cellValues`), `last_cursor_values`. `where_clause`: Use column names from the schema. Examples: `total_amount > 1000`, `status IN ('A','B')`.\ Do **not** include the `WHERE` keyword. ### 3. `execute_query` Executes raw SQL for complex queries only: * Aggregations (`SUM`, `COUNT`, `AVG`, `MIN`, `MAX`) * `GROUP BY` * `JOIN`s and subqueries Do **not** use for simple filtering — use `query_table_data` instead. * **Parameters**: * `sql` (required) — SQL string. Use `connectionName` from the schema as the table name. * **Returns**: Query result; at most 100 rows (`LIMIT 100` added if not present). ### 4. `add_row` Adds one row to the table. * **Parameters**: * `cell_values` (required) — Object mapping column name (from schema) to value, for example: ```json theme={null} { "name": "Acme", "amount": 100 } ``` Use only editable columns (`isDataEditable`). * **Returns**: Created row or error. ### 5. `update_row` Updates an existing row. The `row_id` is: * The value of the `primaryKeyColumnName` column (from `get_table_schema`), or * The `id` in rows returned by `query_table_data`. * **Parameters**: * `row_id` (required) — Row ID (primary key value). * `cell_values` (required) — Object mapping column name to new values; only include columns to update. * **Returns**: Updated row: `{ id, cellValues, cellValuesByColumnId }`. ### 6. `add_row_comment` Adds a comment on a row. * **Parameters**: * `row_id` (required) — Row ID (primary key value). * `comment` (required) — Comment text. * **Returns**: API response or error. ### 7. `create_column` Creates a new column. **DYNAMIC** tables only. * **Parameters**: * `name` (required) * `title` (required) * `data_type` (optional, default `SINGLE_LINE_TEXT`) * `options` (optional, for `SINGLE_SELECT` / `MULTI_SELECT`) * **Returns**: Created column or error. Supported `data_type` values: `DATE`, `NUMBER`, `ATTACHMENT`, `USER`, `SINGLE_LINE_TEXT`, `CHECKBOX`, `EMAIL`, `PHONE_NUMBER`, `URL`, `SINGLE_SELECT`, `DECIMAL`, `DURATION`, `PERCENTAGE`, `CURRENCY`, `LONG_TEXT`, `MULTI_SELECT`, `JSON`, `FORMULA`, `ID`, `AI_GENERATE`. ### 8. `create_formula_column` Creates a formula column (SQL expression). **DYNAMIC** tables only. * **Parameters**: * `name` (required) * `title` (required) * `formula` (required) * `formula_type` (optional, default `"SQL"`) * **Returns**: Created column or error. ### 9. `create_ai_generate_column` Creates an AI Generate column; optionally runs AI generate on all rows. **DYNAMIC** tables only. * **Parameters**: * `name` (required) * `title` (required) * `prompt` (required) * `model` (optional, default `gpt-4o-mini`) * `web_access` (optional, default `false`) * `run_after_create` (optional, default `false`) * **Returns**: Created column; optionally `runAiGenerateResult`. ### 10. `run_ai_generate_bulk` Runs AI generate on many rows for an `AI_GENERATE` column.\ By default processes all rows; optionally filter with `where_clause`. For a single row, use `run_ai_generate_row` instead. * **Parameters**: * `column_id` (required) — UUID from `get_table_schema` (`columns[].id` for the `AI_GENERATE` column). * `select_all` (optional, default `true`) * `where_clause` (optional) * `filter_params` (optional) * **Returns**: Bulk run result or error. ### 11. `run_ai_generate_row` Runs AI generate on a single row for an `AI_GENERATE` column.\ For many rows, use `run_ai_generate_bulk` instead. * **Parameters**: * `column_id` (required) — UUID from `get_table_schema`. * `row_id` (required) — Row ID (primary key value). * **Returns**: Updated row: `{ id, cellValues, cellValuesByColumnId }`. ### 12. `update_column` Updates an existing column. Only change what the schema allows (for example `isMetaDataEditable`, `isDataTypeEditable`). * **Parameters**: * `column_id` (required) * `name`, `title`, `description`, `data_type`, `formula`, `options` (all optional) * **Returns**: Updated column or error. For `SINGLE_SELECT` / `MULTI_SELECT`, `options` are merged by value; existing options are not removed. ### 13. `update_table` Updates the workbook table (title, description, delete guard). * **Parameters**: * `title` (optional) * `description` (optional) * `delete_guard` (optional) * **Returns**: Updated table or error. ### 14. `delete_column` Deletes a column. Only when the schema marks it as deletable (`isDeletable`). * **Parameters**: * `column_id` (required) — from `get_table_schema`. * **Returns**: Success or error. ## Row ID reference The `row_id` used by `update_row`, `add_row_comment`, and `run_ai_generate_row` is: * The value of the `primaryKeyColumnName` column (from `get_table_schema`), or * The `id` field in each row returned by `query_table_data`. ## Summary * **Total tools**: 14 — schema, query / execute, add / update row, add comment, create / update / delete column, formula column, AI generate column + bulk + row, update table. * **Protocol**: MCP over Streamable HTTP at `/mcp` with `workspace_id`, `table_id`, and `token`. * **Best practice**: Call `get_table_schema` first. Use `query_table_data` for simple filtering; use `execute_query` for aggregations and complex SQL. Use `primaryKeyColumnName` or row `id` for row-level operations.