Skip to main content

​
Overview

SketricGen provides a high-performance Public API service that enables AI-powered conversational workflows using custom agents you design in the Web App. This API provides endpoints for running AI workflows, managing conversations, and streaming real-time responses. Base URL: https://chat-v2.sketricgen.ai/api/v1

​
When to Use the Public API

Use the Public API when you want to call a SketricGen agent from your own product, backend, workflow runner, or custom UI. Common use cases:
  • Run AI Workforce agents from your own application
  • Add SketricGen agents to an internal product experience
  • Build a custom chat UI instead of using the hosted website widget
  • Trigger an agent from backend jobs or server-side automations
  • Keep conversation identity aligned with users or contacts in your own system
If you only need a copy-paste website chat bubble or iframe, use Deploy an AI Chatbot to a Custom Website instead.

​
Authentication

All API requests require authentication via an API key in the request headers. Required Header: 
api-key: your_api_key_here
(You can retrieve it from your account setting at www.sketricgen.ai/profile)

​
Endpoints

​
Run Workflow

POST /run-workflow Execute an AI workflow using a specified agent to generate intelligent responses based on user input.

​
Request Headers

HeaderTypeRequiredDescription
api-keystringYesYour API authentication key
Content-TypestringYesMust be application/json

​
Request Body

FieldTypeRequiredDescriptionConstraints
agent_idstringYesUnique identifier for the AI agent to use-
user_inputstringYesThe user’s message or query to processMax 10,000 characters
conversation_idstringNoID of existing conversation to continueIf omitted, creates new conversation
contact_idstringNoExternal identifier to associate conversation with a contactMax 255 characters
streambooleanNoEnable real-time response streamingDefault: false

​
Example Request

{
	"agent_id": "agent_abc123xyz",
	"user_input": "Help me analyze this quarterly sales data",
	"conversation_id": "conv_def456ghi",
	"contact_id": "customer_12345",
	"stream": false
}

​
Contact ID and User Grouping

Use contact_id when your product already knows who the end user or contact is. Conversations sent with the same agent_id and contact_id are grouped under the same contact in SketricGen. This is useful when you want to:
  • See all conversations from one customer or app user together
  • Continue reviewing a user’s history across multiple sessions
  • Connect SketricGen conversations back to your CRM, database, or product user record
  • Use the same identity model across API, widget, iframe, and other channels
Use a stable internal ID, UUID, or hashed value. Do not send emails, phone numbers, names, or other directly identifiable personal data as the contact ID. Good examples: 
customer_12345
user_uuid_550e8400-e29b-41d4-a716-446655440000
customer_hash_abc123def456
Avoid: 
john.doe@email.com
555-123-4567
John Doe

​
Identity Fields by Deployment Method

The same agent can be deployed through the website widget, iframe, fullscreen link, or Public API. The identity fields change slightly by deployment method:
Deployment methodAgent identifierContact identifier
Public APIagent_id in the JSON bodycontact_id in the JSON body
Chat bubble widgetdata-agent-id on the script tagdata-contact-id on the script tag
Floating pill widgetdata-agent-id plus data-layout="floating"data-contact-id on the script tag
Inline iframeAgent ID in /iframe-widget/YOUR_AGENT_IDcontactId query parameter
Fullscreen linkAgent ID in /fullscreen-widget/YOUR_AGENT_IDcontactId query parameter
API example: 
{
	"agent_id": "agent_abc123xyz",
	"user_input": "What's my order status?",
	"contact_id": "customer_12345",
	"stream": false
}
Widget equivalent: 
<script
  src="https://jswidget.sketricgen.ai/widget-embed.js"
  data-agent-id="YOUR_AGENT_ID"
  data-contact-id="customer_12345"
></script>
Iframe equivalent: 
<iframe
  src="https://www.sketricgen.ai/iframe-widget/YOUR_AGENT_ID?contactId=customer_12345"
  width="100%"
  height="700px"
  frameborder="0"
></iframe>
If the visitor is anonymous, omit the contact identifier. The widget will use its browser-stored anonymous contact behavior, while API requests without contact_id create conversations without your external user mapping.

​
Response Formats

The endpoint supports two response modes.

​
1. Standard Response (stream: false)

HTTP Status: 201 Created Response Body:
FieldTypeDescription
agent_idstringThe agent that processed the request
user_idstringIdentifier for the user account
conversation_idstringID of the conversation (new or existing)
contact_idstringExternal contact identifier (if provided)
responsestringThe AI agent’s generated response
ownerstringOwner of the agent
errorbooleanIndicates if an error occurred
Example Response: 
{
	"agent_id": "agent_abc123xyz",
	"user_id": "user_789xyz",
	"conversation_id": "conv_def456ghi",
	"contact_id": "customer_12345",
	"response": "I'll help you analyze your quarterly sales data. Please share the data file or provide the key metrics you'd like me to examine.",
	"owner": "company_abc",
	"error": false
}

​
2. Streaming Response (stream: true)

HTTP Status: 200 OK Content-Type: text/event-stream When streaming is enabled, the endpoint returns real-time Server-Sent Events (SSE) as the AI processes the request. Event Types:
Event TypeDescription
RUN_STARTEDWorkflow execution has begun
TEXT_MESSAGE_STARTAI has started generating a text response
TEXT_MESSAGE_CONTENTIncremental text content (streaming)
TEXT_MESSAGE_ENDAI has finished generating text response
TOOL_CALL_STARTAI has started using a tool/function
TOOL_CALL_ENDAI has finished using a tool/function
RUN_FINISHEDWorkflow execution completed successfully
RUN_ERRORAn error occurred during execution
Example Streaming Events: 
data: {"type": "RUN_STARTED", "timestamp": 1640995200, "thread_id": "conv_def456ghi", "run_id": "run_123abc"}

data: {"type": "TEXT_MESSAGE_START", "timestamp": 1640995201, "message_id": "msg_456def"}

data: {"type": "TEXT_MESSAGE_CONTENT", "timestamp": 1640995202, "message_id": "msg_456def", "delta": "I'll help"}

data: {"type": "TEXT_MESSAGE_CONTENT", "timestamp": 1640995203, "message_id": "msg_456def", "delta": " you analyze"}

data: {"type": "TEXT_MESSAGE_END", "timestamp": 1640995210, "message_id": "msg_456def"}

data: {"type": "RUN_FINISHED", "timestamp": 1640995211, "thread_id": "conv_def456ghi", "run_id": "run_123abc"}