DataGOL Custom Agents API - DataGOL API Docs

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

Stream Messages

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.

Fetch Agent Permissions

GET /noCo/api/v2/elementPermissions/CUSTOM_AGENT/{agentId} — verify who currently has access to the agent.

List Team Members

GET /idp/api/v1/team — fetch the full team roster to populate the share dialog with user IDs and display names.

Share Team Members

POST /noCo/api/v2/elementPermissions/bulk — grant CREATOR, EDITOR, or VIEWER access to selected team members by userId.

Misc

Generate Conversation Name

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 <jwt_token>`	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

curl 'https://be.datagol.ai/customAgents/api/v1' \
  -H 'Authorization: Bearer <token>' \
  -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}

agentId

string (UUID)

required

The UUID of the Custom Agent returned from the create or list endpoint.

curl 'https://be.datagol.ai/customAgents/api/v1/f1c6ff59-f4b7-476e-b306-f8531b42863d' \
  -H 'Authorization: Bearer <token>' \
  -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.

curl 'https://be.datagol.ai/noCo/api/v2/workspaces' \
  -H 'Authorization: Bearer <token>' \
  -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.

curl 'https://be.datagol.ai/noCo/api/v2/workspaces/search?query=&type=TABLE' \
  -H 'Authorization: Bearer <token>' \
  -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):

[
  {
    "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:

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.

curl 'https://be.datagol.ai/connector/api/v1/instance' \
  -H 'Authorization: Bearer <token>' \
  -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.

curl 'https://be.datagol.ai/idp/api/v1/team' \
  -H 'Authorization: Bearer <token>' \
  -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.

curl --location 'https://be.datagol.ai/customAgents/api/v1' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '<see full body below>'

`uiMetadata` — UI Presentation Layer

Controls how the agent looks and behaves in the DataGOL chat interface.

uiMetadata

object

required

Show uiMetadata fields

uiMetadata.capabilities

object

required

Defines which UI capabilities are enabled for this agent.

Show capabilities fields

uiMetadata.capabilities.allowDownload

boolean

required

Whether users can download the chat conversation as a file.

true — A download button appears in the conversation toolbar.
false — Download is disabled.

uiMetadata.capabilities.models

object

required

Model selector configuration shown in the chat UI.

Show models fields

uiMetadata.capabilities.models.enabled

boolean

required

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.

uiMetadata.capabilities.models.supportedModels

array of strings

required

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

uiMetadata.capabilities.models.defaultValue

string

required

The model pre-selected when a conversation starts. Must be in supportedModels.Example: "gpt-5.2"

uiMetadata.capabilities.conversationFiles.enabled

boolean

required

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.

uiMetadata.style.logo.bgColor

string

Background color for the agent logo bubble. Accepts any valid CSS color value (hex, rgb, named).Example: "#1a1a2e" | "" (empty = use default)

uiMetadata.style.logo.textColor

string

Text/icon color rendered on top of the logo background.Example: "#ffffff" | "" (empty = use default)

uiMetadata.input.placeholder

string

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)

uiMetadata.bestFor

array of strings

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: []

uiMetadata.conversationStarters

array of strings

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: []

uiMetadata.logo

object | null

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

object

required

Show configs fields

`configs.connectors` — Data Sources

configs.connectors

array

required

Array of data connectors the agent can retrieve information from. Supports three distinct connector types.

Show Connector object fields (all types)

configs.connectors[].id

string

required

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).

configs.connectors[].type

string

required

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

configs.connectors[].sourceType

string

required

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

configs.connectors[].data

object

Type-specific metadata. See breakdown below by connector type.

Type: WORKBOOK_RAG — Single file RAGAttaches a specific workbook file for the agent to search over using vector retrieval.

{
  "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"
  }
}

Show WORKBOOK_RAG data fields

data.title

string

required

Display name of the workbook file (typically the filename).

data.description

string

Optional description of the file content to help the agent understand what data it contains.

data.workspaceId

string (UUID)

required

UUID of the workspace containing this workbook. Fetch from GET /noCo/api/v2/workspaces.

data.workspaceName

string

required

Display name of the workspace. Used in UI labels.

Type: WORKSPACE_DOCUMENTS — Full workspace RAGAttaches an entire workspace — every document in it becomes searchable by the agent.

{
  "id": "055b4db3-96e1-45e1-8ff5-3a911b779a53",
  "type": "WORKSPACE_DOCUMENTS",
  "sourceType": "BACKEND",
  "data": {
    "name": "Link_v2"
  }
}

Show WORKSPACE_DOCUMENTS data fields

data.name

string

required

Display name of the workspace.

Type: KNOWLEDGE_BASE — Synced external knowledgeConnects 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.

{
  "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
    }
  }
}

Show KNOWLEDGE_BASE data fields

data.id

string (UUID)

required

Same as the connector id.

data.companyId

integer

required

Tenant company ID.

data.userId

integer

required

ID of the user who created the knowledge base.

data.type

string

required

Knowledge base source type.

Value	Source
`GOOGLE_DRIVE`	Google Drive folder
`WEB`	Web scrape / website crawl

data.name

string

required

Display name of the knowledge base.

data.status

string

required

ACTIVE or INACTIVE.

data.lastSyncAt

string (ISO 8601)

Timestamp of the last successful sync.

data.lastSyncStatus

string

SUCCESS or FAILED.

data.credentialId

integer | null

ID of the OAuth credential used to access the source. null for open sources like web.

data.latestRun

object

Details of the most recent sync run.

data.latestRun.runType

string

INCREMENTAL or FULL.

data.latestRun.status

string

SUCCESS, FAILED, or RUNNING.

data.latestRun.statsJson

object

Sync statistics — e.g. { "total": 49, "failed": 0, "completed": 49 }.

Type: CONNECTOR — AI-side live connectorRoutes queries to a live connector instance managed by the AI microservice (e.g. a database connector, API connector).

{
  "id": "315",
  "type": "CONNECTOR",
  "sourceType": "AI"
}

string

required

Numeric connector instance ID (as a string). Obtain from GET /connector/api/v1/instance.

`configs.mcpConfigs` — MCP Tool Servers

configs.mcpConfigs

array

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.

[
  {
    "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
  }
]

Show MCP config fields

mcpConfigs[].id

integer

Unique ID of the MCP server record. Assigned by the platform when the server is registered.

mcpConfigs[].name

string

required

Display name shown in the agent builder UI and tool call traces.

mcpConfigs[].description

string

Description of what tools this MCP server exposes.

mcpConfigs[].url

string

required

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=..."

mcpConfigs[].transport

string

required

Protocol used to communicate with the MCP server.

Value	Protocol
`streamable_http`	HTTP with streaming support (recommended)

mcpConfigs[].serverType

string

required

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

mcpConfigs[].companyId

integer

Tenant scoping — the company ID this MCP server belongs to.

mcpConfigs[].data

object

Required only for serverType: WORKBOOK. Contains the workbook and workspace IDs used to resolve the server URL automatically.

{
  "id": "ca45078d-ed26-4752-a7a7-4aed24af033c",
  "workspaceId": "055b4db3-96e1-45e1-8ff5-3a911b779a53"
}

`configs.webSearchEnabled`

configs.webSearchEnabled

boolean

required

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`

configs.skillIds

array of integers

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

isPublished

boolean

required

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.

prompt

string

required

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.

description

string

required

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"

name

string

required

Display name of the agent. Shown in the agent list and chat header.Example: "Financial Agent"

Complete Request Example

{
  "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=<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

{
  "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 /noCo/api/v2/elementPermissions/bulk Grants one or more users access to a Custom Agent.

curl --location 'https://be.datagol.ai/noCo/api/v2/elementPermissions/bulk' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "permissions": [
      {
        "elementId": "7bf5f4d6-743d-414f-aa4a-96f7a20ce0fd",
        "elementType": "CUSTOM_AGENT",
        "userId": 935,
        "permission": "CREATOR"
      }
    ]
  }'

permissions

array

required

Array of permission grants to apply in a single atomic operation.

Show Permission object fields

permissions[].elementId

string (UUID)

required

UUID of the Custom Agent to share. Returned by the create or list agent endpoint.

permissions[].elementType

string

required

Must be "CUSTOM_AGENT" for agent sharing.

permissions[].userId

integer

required

ID of the user to grant access to. Fetch from GET /idp/api/v1/team.

permissions[].permission

string

required

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.

agentId

string (UUID)

required

UUID of the Custom Agent.

curl 'https://be.datagol.ai/noCo/api/v2/elementPermissions/CUSTOM_AGENT/7bf5f4d6-743d-414f-aa4a-96f7a20ce0fd' \
  -H 'Authorization: Bearer <token>' \
  -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

Request Body

{
  "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.

curl --location 'https://be.datagol.ai/ai/api/v2/conversations' \
  --header 'Authorization: Bearer <token>' \
  --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"
      }
    }
  }'

name

string

required

Display name for this conversation. Auto-generated by the naming API (step 3) or user-supplied.

active

boolean

required

Always true when creating a new conversation.

scope

string

required

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

userId

integer

required

ID of the authenticated user creating the conversation. Must match the token’s userId claim.

agentType

string

required

Must be "CustomAgent" for custom agent conversations.

uiMetadata.parameters.customAgentId

string (UUID)

required

UUID of the Custom Agent that backs this conversation. Passed twice (at parameters and parameters.parameters) for backward compatibility.

uiMetadata.configuration.llmModel

string

required

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).

curl 'https://ai.datagol.ai/ai/api/v2/messages/streaming' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'credentials: include' \
  -H 'Referer: https://app.datagol.ai/' \
  --data-raw '{
    "agentType": "CustomAgent",
    "type": "CustomAgent",
    "conversationId": "<conversationId>",
    "message": "Hi",
    "parameters": {
      "customAgentId": "<customAgentId>"
    },
    "uiMetadata": {
      "parameters": {}
    },
    "selectedLlmModel": "gpt-5.4"
  }'

agentType

string

required

Must be "CustomAgent".

type

string

required

Must be "CustomAgent". (Duplicates agentType for routing purposes.)

conversationId

string (UUID)

required

The conversation ID returned by POST /ai/api/v2/conversations.

message

string

required

The user’s message text to send to the agent.

parameters.customAgentId

string (UUID)

required

UUID of the Custom Agent. Must match the agent that backs this conversation.

selectedLlmModel

string

required

The model to use for this specific message. Can be changed per message to switch models mid-conversation.

uiMetadata

object

Pass as { "parameters": {} } unless overriding model-level parameters.

Response — SSE stream of delta tokens and tool call events. Parse events with data: prefix.

: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

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 <token>' \
  -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

​Overview

​Create Agent

​Create a thread

​Converse

​Sharing and Permissions

​Misc

​Authentication

​Required headers for every request

​Optional / contextual headers

​Base URLs

​Reference APIs

​Supporting Lookups

​GET List All Custom Agents

​GET Get Custom Agent by ID

​GET List All Workspaces

​GET Search Workspaces and Workbooks

​GET List All Connectors

​GET List Team Members

​GET List All Conversations

​POST Create Custom Agent

​uiMetadata — UI Presentation Layer

​configs — Agent Runtime Configuration

​configs.connectors — Data Sources

​configs.mcpConfigs — MCP Tool Servers

​configs.webSearchEnabled

​configs.skillIds

​Top-Level Fields

​Complete Request Example

​Response

​POST Share Agent (Bulk Permissions)

​GET Custom Agent Permissions

​POST Generate Conversation Name

​POST Initiate Conversation

​POST Streaming Message

​GET Workspace by ID

​Error Handling

​Connector Type Quick Reference

​Model ID Reference

Overview

Create Agent

Create a thread

Converse

Sharing and Permissions

Misc

Authentication

Required headers for every request

Optional / contextual headers

Base URLs

Reference APIs

Supporting Lookups

GET List All Custom Agents

GET Get Custom Agent by ID

GET List All Workspaces

GET Search Workspaces and Workbooks

GET List All Connectors

GET List Team Members

GET List All Conversations

POST Create Custom Agent

`uiMetadata` — UI Presentation Layer

`configs` — Agent Runtime Configuration

`configs.connectors` — Data Sources

`configs.mcpConfigs` — MCP Tool Servers

`configs.webSearchEnabled`

`configs.skillIds`

Top-Level Fields

Complete Request Example

Response

POST Share Agent (Bulk Permissions)

GET Custom Agent Permissions

POST Generate Conversation Name

POST Initiate Conversation

POST Streaming Message

GET Workspace by ID

Error Handling

Connector Type Quick Reference

Model ID Reference