Public API

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

Header	Type	Required	Description
`api-key`	string	Yes	Your API authentication key
`Content-Type`	string	Yes	Must be `application/json`

Request Body

Field	Type	Required	Description	Constraints
`agent_id`	string	Yes	Unique identifier for the AI agent to use	-
`user_input`	string	Yes	The user’s message or query to process	Max 10,000 characters
`conversation_id`	string	No	ID of existing conversation to continue	If omitted, creates new conversation
`contact_id`	string	No	External identifier to associate conversation with a contact	Max 255 characters
`stream`	boolean	No	Enable real-time response streaming	Default: `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 method	Agent identifier	Contact identifier
Public API	`agent_id` in the JSON body	`contact_id` in the JSON body
Chat bubble widget	`data-agent-id` on the script tag	`data-contact-id` on the script tag
Floating pill widget	`data-agent-id` plus `data-layout="floating"`	`data-contact-id` on the script tag
Inline iframe	Agent ID in `/iframe-widget/YOUR_AGENT_ID`	`contactId` query parameter
Fullscreen link	Agent ID in `/fullscreen-widget/YOUR_AGENT_ID`	`contactId` 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:

Field	Type	Description
`agent_id`	string	The agent that processed the request
`user_id`	string	Identifier for the user account
`conversation_id`	string	ID of the conversation (new or existing)
`contact_id`	string	External contact identifier (if provided)
`response`	string	The AI agent’s generated response
`owner`	string	Owner of the agent
`error`	boolean	Indicates 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 Type	Description
`RUN_STARTED`	Workflow execution has begun
`TEXT_MESSAGE_START`	AI has started generating a text response
`TEXT_MESSAGE_CONTENT`	Incremental text content (streaming)
`TEXT_MESSAGE_END`	AI has finished generating text response
`TOOL_CALL_START`	AI has started using a tool/function
`TOOL_CALL_END`	AI has finished using a tool/function
`RUN_FINISHED`	Workflow execution completed successfully
`RUN_ERROR`	An 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"}

Getting Started

Brand Agents

AI Workforce

Knowledge Bases

Deployment

Dev Guide

Product Updates

Overview

When to Use the Public API

Authentication

Endpoints

Run Workflow

Request Headers

Request Body

Example Request

Contact ID and User Grouping

Identity Fields by Deployment Method

Response Formats

1. Standard Response (stream: false)

2. Streaming Response (stream: true)

​Overview

​When to Use the Public API

​Authentication

​Endpoints

​Run Workflow

​Request Headers

​Request Body

​Example Request

​Contact ID and User Grouping

​Identity Fields by Deployment Method

​Response Formats

​1. Standard Response (stream: false)

​2. Streaming Response (stream: true)

Overview

When to Use the Public API

Authentication

Endpoints

Run Workflow

Request Headers

Request Body

Example Request

Contact ID and User Grouping

Identity Fields by Deployment Method

Response Formats

1. Standard Response (stream: false)

2. Streaming Response (stream: true)