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 Authorization header using the format SSWS <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

get

Get a list of all agents in this account - id, name, description

Authorizations

Authorization

AuthorizationstringRequired

Token

Header parameters

AuthorizationanyOptional

For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '

Responses

200

successful operation

application/json

stringOptional

get/agents/v1/

HTTPcURLJavaScriptPython

GET /api/agents/v1/ HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*

200

successful operation

[
  {
    "createdByName": "[e-mail]",
    "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"
  }
]

Deprecated

[DEPRECATED] Get the agent's response to user text

post

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.

Authorizations

Authorization

AuthorizationstringRequired

Token

Path parameters

agentIdstringRequired

Id of the Agent in the system

Example: 3756809c-4032-4e48-b3f0-2a6d30a03a54

Query parameters

userTextstringRequired

The last text from the user. Must be url encoded.

Example: What is the status of the order?

llmProviderIdstringRequired

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.

Example: 3756809c-4032-4e48-b3f0-2a6d30a03a54

propertiesstringOptional

Any additional properties to be passed to influence execution

Header parameters

AuthorizationanyOptional

For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '

Body

application/json

objectOptional

Responses

200

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

application/json

objectOptional

post/agents/v1/{agentId}/response

HTTPcURLJavaScriptPython

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

200

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

Get LLM providers configured in Dataworkz

get

Returns a map containing unique identifier and LLM models that have been configured

Authorizations

Authorization

AuthorizationstringRequired

Token

Header parameters

AuthorizationanyOptional

For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '

Responses

200

successful operation

application/json

objectOptional

get/agents/v1/llm-providers

HTTPcURLJavaScriptPython

GET /api/agents/v1/llm-providers HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*

200

successful operation

{
  "47b51bb5-bdfa-413d-8bfa-ff040ab1c901": "llama-2-13b-chat"
}

Get the A2A Agent Card for a specific agent

get

Get the A2A Agent Card for a specific agent. The Agent Card details are available in the A2A specification.

Authorizations

Authorization

AuthorizationstringRequired

Token

Path parameters

agentIdstringRequired

Responses

200

OK

application/json

namestringOptional

descriptionstringOptional

urlstringOptional

versionstringOptional

documentationUrlstringOptional

defaultInputModesstring[]Optional

defaultOutputModesstring[]Optional

supportsAuthenticatedExtendedCardbooleanOptional

securitySchemesobjectOptional

securityobject[]Optional

iconUrlstringOptional

get/agents/v1/a2a/{agentId}/.well-known/agent.json

HTTPcURLJavaScriptPython

GET /api/agents/v1/a2a/{agentId}/.well-known/agent.json HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*

200

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

get

Get the A2A Agent Card for a specific agent. The Agent Card details are available in the A2A specification

Authorizations

Authorization

AuthorizationstringRequired

Token

Path parameters

agentIdstringRequired

Header parameters

AuthorizationanyOptional

For Dataworkz API Token use the format 'SSWS ' and for OAuth2 generated JWT token use 'Bearer '

Responses

200

OK

application/json

namestringOptional

descriptionstringOptional

urlstringOptional

versionstringOptional

documentationUrlstringOptional

defaultInputModesstring[]Optional

defaultOutputModesstring[]Optional

supportsAuthenticatedExtendedCardbooleanOptional

securitySchemesobjectOptional

securityobject[]Optional

iconUrlstringOptional

get/agents/v1/a2a/{agentId}/.well-known/agent-card.json

HTTPcURLJavaScriptPython

GET /api/agents/v1/a2a/{agentId}/.well-known/agent-card.json HTTP/1.1
Host: ragapps.dataworkz.com
Authorization: YOUR_API_KEY
Accept: */*

200

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

The A2A streaming response endpoint of the Agent

post

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 -

{
  "jsonrpc": "2.0",
  "id": "msg-1752069031164-mzzokdfi3",
  "result": {
    "kind": "status-update",
    "taskId": "8b785e97-fbf5-4951-a09b-a70e32cd07fb",
    "status": {
      "state": "completed",
      "message": {
        "kind": "message",
        "role":  "agent",
        "parts": [
          {
            "kind": "text",
            "text": "Hello! How can I assist you today?",
            "metadata": {
              "mimetype": "text/plain"
            },
            "kind": "text"
          }
        ],
        "messageId": "49b7d288-27f6-4210-bdd8-d63fecbd0251",
        "contextId": "7c43d2c8-e111-4a57-bbeb-82e9d694a316",
        "taskId": "8b785e97-fbf5-4951-a09b-a70e32cd07fb",
        "metadata": {},
        "kind": "message"
      },
      "timestamp": "2025-08-25T10:39:40.450635"
    },
    "contextId": "7c43d2c8-e111-4a57-bbeb-82e9d694a316",
    "final": true,
    "kind": "status-update"
  }
}

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

{
  "jsonrpc": "2.0",
  "id": "msg-1752069031164-mzzokdfi3",
  "result": {
    "kind": "status-update",
    "taskId": "8b785e97-fbf5-4951-a09b-a70e32cd07fb",
    "status": {
      "state": "working",
      "message": {
        "kind": "message",
        "role": "agent",
        "parts": [
          {
            "kind": "data",
            "data": {
              "status": {
                "planning": {
                  "llmThought": "Scenario has no tools so generating the minimal plan.",
                  "type": "Planning",
                  "name": "Plan",
                  "metadata": {},
                  "status": "completed"
                },
                "executions": [],
                "agentResponse": {
                  "type": "Join",
                  "name": "Agent Response",
                  "metadata": {},
                  "status": "in_progress"
                },
                "type": "Iteration",
                "name": "Iteration 0",
                "metadata": {},
                "status": "in_progress"
              }
            }
          }
        ],
        "messageId": "4e307055-9754-4137-a1bb-d6aeeca1dc7e",
        "contextId": "7c43d2c8-e111-4a57-bbeb-82e9d694a316",
        "taskId": "8b785e97-fbf5-4951-a09b-a70e32cd07fb",
        "metadata": {
          "type": "DW_STATUS_UPDATE"
        }
      },
      "timestamp": "2025-08-25T10:39:38.679435"
    },
    "contextId": "7c43d2c8-e111-4a57-bbeb-82e9d694a316",
    "final": false
  }
}

Authorizations

Authorization

AuthorizationstringRequired

Token

Path parameters

agentIdstringRequired

Id of the Agent in the system

Example: 3756809c-4032-4e48-b3f0-2a6d30a03a54

Query parameters

llmIdstringOptional

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

Example: 3756809c-4032-4e48-b3f0-2a6d30a03a54

propertiesstringOptional

Any additional properties to be passed to influence execution

Body

application/json

jsonrpcstringOptional

idobjectOptional

methodstringOptional

paramsobjectOptional

Responses

200

OK

text/event-streamapplication/json

timeoutinteger · int64Optional

post/agents/v1/a2a/{agentId}/stream

HTTPcURLJavaScriptPython

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

200

OK

{
  "timeout": 1
}