APIs
REST API reference for invoking Dataworkz Agents from external systems.
Dataworkz Agents bring together data from multiple systems through Tools. Using a declarative mechanism to build Agents, they form a powerful Agentic RAG system. The API lets you integrate Agents into any external system.
💡 Note: All API calls require an API token. Follow these steps to generate an API key. Provide the API key in the
Authorizationheader using the formatSSWS <your api key>.
Concepts
Dataworkz Agents expose a stateless API. Each request includes the conversation history so far, and the API responds to the user's question or text. Build and save Agents in Dataworkz using the Agent Builder. Retrieve the agentId from the Agent card in the product UI.
LLMProviderId
The LLMProviderId is the identifier of an LLM Configuration defined in Dataworkz. Dataworkz supports multiple LLM configurations, each used for a specific purpose.
API
Get a list of all agents in this account - id, name, description
Token
For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '
successful operation
GET /api/agents/v1/ HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*
successful operation
[
{
"createdByName": "abc@example.com",
"agentId": "47e8366d-5db8-45ae-8457-9259a46bbdad",
"createdDate": "2025-02-17 04:45:32.593",
"name": "Customer Support Agent",
"description": "The agent acts as a customer support representative for users to ask questions and get help.",
"scenariosCount": "5"
}
]For the given agent specified by the agentId, get the agent's response for the user's text and the conversation history.
Note: This invocation is stateless and does not integrate with Dataworkz's Conversation Store. This API is expected to be deprecated within a few releases. Look at the A2A APIs instead.
Request Body:
The request body has to be a json object with keys - conversationHistory, contextValues (optional). conversationHistory: list object to pass conversation history between user and AI. Each object in the list follows the format - { "by": "AI", "text": "Hi" } or { "by": "USER", "text": "Hi" } contextValues: Any context values if present can be passed - { "contextValueName": contextValue }
Note: This endpoint is deprecated - Take a look at 'The A2A streaming response endpoint of the Agent' for the supported way to invoke an Agent.
Token
Id of the Agent in the system
3756809c-4032-4e48-b3f0-2a6d30a03a54The last text from the user. Must be url encoded.
What is the status of the order?Id of the LLM to use for the agent. This must be one of the LLMs configured in this account. Currently, gpt-4 and llama3-70B models are supported. Id can be copied from the LLM Configuration page.
3756809c-4032-4e48-b3f0-2a6d30a03a54Any additional properties to be passed to influence execution
For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '
successful operation. The agent's response is available in 'answer'. If structuredResponse is configured then it is available in the key 'structuredResponse'. Probe is returned in the 'probe'.
POST /api/agents/v1/{agentId}/response?userText=text&llmProviderId=text HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 169
{
"conversationHistory": [
{
"by": "USER",
"text": "Hi"
},
{
"by": "AI",
"text": "Hi! How can I assist you today?"
}
],
"contextValues": {
"variable1": "value1",
"variable2": {
"obj": "val"
}
}
}successful operation. The agent's response is available in 'answer'. If structuredResponse is configured then it is available in the key 'structuredResponse'. Probe is returned in the 'probe'.
{
"status": "OK",
"data": {
"question": "Hi",
"systemName": "TestAgent",
"answer": "Hello! How can I assist you today?",
"scenario": "Greet",
"type": "agent",
"questionUuid": "e9e6d058-79ff-4165-a409-d0e9a38b4802",
"status": "COMPLETED",
"systemId": "5ccea050-aff5-4e37-8572-d2e486987843",
"structuredResponse": {
"scenario": "Greet",
"agentResponse": "Hello! How can I assist you today?",
"responseType": "Finish",
"structuredOutput": ""
},
"queryPlan": "",
"probe": ""
}
}Returns a map containing unique identifier and LLM models that have been configured
Token
For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '
successful operation
GET /api/agents/v1/llm-providers HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*
successful operation
{
"47b51bb5-bdfa-413d-8bfa-ff040ab1c901": "llama-2-13b-chat"
}Get the A2A Agent Card for a specific agent. The Agent Card details are available in the A2A specification.
Token
OK
GET /api/agents/v1/a2a/{agentId}/.well-known/agent.json HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*
OK
{
"name": "text",
"description": "text",
"url": "text",
"provider": {
"organization": "text",
"url": "text"
},
"version": "text",
"documentationUrl": "text",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"stateTransitionHistory": true,
"extensions": [
{
"description": "text",
"params": {},
"required": true,
"uri": "text"
}
]
},
"defaultInputModes": [
"text"
],
"defaultOutputModes": [
"text"
],
"skills": [
{
"id": "text",
"name": "text",
"description": "text",
"tags": [
"text"
],
"examples": [
"text"
],
"inputModes": [
"text"
],
"outputModes": [
"text"
]
}
],
"supportsAuthenticatedExtendedCard": true,
"securitySchemes": {},
"security": [
{}
],
"iconUrl": "text"
}Get the A2A Agent Card for a specific agent. The Agent Card details are available in the A2A specification
Token
For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '
OK
GET /api/agents/v1/a2a/{agentId}/.well-known/agent-card.json HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*
OK
{
"name": "text",
"description": "text",
"url": "text",
"provider": {
"organization": "text",
"url": "text"
},
"version": "text",
"documentationUrl": "text",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"stateTransitionHistory": true,
"extensions": [
{
"description": "text",
"params": {},
"required": true,
"uri": "text"
}
]
},
"defaultInputModes": [
"text"
],
"defaultOutputModes": [
"text"
],
"skills": [
{
"id": "text",
"name": "text",
"description": "text",
"tags": [
"text"
],
"examples": [
"text"
],
"inputModes": [
"text"
],
"outputModes": [
"text"
]
}
],
"supportsAuthenticatedExtendedCard": true,
"securitySchemes": {},
"security": [
{}
],
"iconUrl": "text"
}Sends a message to an agent to initiate/continue a task AND subscribes the client to real-time updates for that task via Server-Sent Events (SSE). Refer to the A2A specification for details.
Supported Extensions:
Refer to this for details on how extensions are activated.
To activate an extension you MUST send its URI in an HTTP Header named
X-A2A-Extensions.
Send Context Variables
Dataworkz A2A Agents API supports an A2A extension to send context values for an agent invocation. This might change in the future as the spec evolves. To use this extension you must -
activate this extension by sending a header in your request -
X-A2A-Extensions: https://dataworkz.com/agents/ext/provided-values/v1.The context values should be present in the input Message in a DataPart as a Json Object with keys as the variable names and the values as their value (see example below).
Metadata for the Part must include the URI
https://dataworkz.com/agents/ext/provided-values/v1 : true
Here's an example of a Part definition for sending context values
{
"kind": "data",
"metadata": { "https://dataworkz.com/agents/ext/provided-values/v1": true },
"data": {
"context-var": "value",
"context-var-2": { ... value ... }
}
}Response
Agent Response : The Agent's Response is available in an Server-Sent Event of kind : status-update where status: is of state: completed. Basically, only events that are final events can have the agent response - successful or failure. Here's an example -
Task Updates : The Agent system emits Server-Sent Events as it progresses through the Agent Execution. These are available as DataParts and they are marked with this metadata "type": "DW_STATUS_UPDATE".
Token
Id of the Agent in the system
3756809c-4032-4e48-b3f0-2a6d30a03a54Id of the LLM to use for the agent. This must be one of the LLMs configured in this account. Id can be copied from the LLM Configuration page or retrieved by a call to the llm-providers endpoint. If not provided, the llmId configured in the agent is used, if that's not present then the llm marked default in LLM Configurations is used. If not LLM Id is found, the request will fail.
3756809c-4032-4e48-b3f0-2a6d30a03a54Any additional properties to be passed to influence execution
OK
POST /api/agents/v1/a2a/{agentId}/stream HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 54
{
"jsonrpc": "text",
"id": {},
"method": "text",
"params": {}
}OK
{
"timeout": 1
}Last updated