Runtime API - SketricGen Docs

Overview

The SketricGen Runtime API executes agents that you created in SketricGen. Use it to send a message, continue a conversation, attach previously uploaded files, stream the response, or resume a Human Input pause. The customer-facing Runtime API intentionally exposes one programmatic execution endpoint. Teamspace and agent management belong to the Admin API, while conversational AI management belongs to the SketricGen MCP server. Base URL: https://chat-v2.sketricgen.ai/api/v1

When to use the Runtime API

Use the Runtime API when you want to call an existing 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

Every Runtime API request requires a Teamspace Runtime API key beginning with sk_runtime_. Create it from Teamspace settings → API keys → Create key → Runtime key. Choose the narrowest project and agent scope that supports the integration. The plaintext key is shown once. Required Header:

API-KEY: sk_runtime_YOUR_KEY

Do not use an Admin API key beginning with sk_admin_ here. Admin keys manage Teamspace resources; they do not execute agents.

Quick start

export SKETRICGEN_RUNTIME_API_KEY="sk_runtime_YOUR_KEY"

curl -X POST "https://chat-v2.sketricgen.ai/api/v1/run-workflow" \
  -H "API-KEY: $SKETRICGEN_RUNTIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123xyz",
    "user_input": "Summarize the latest product feedback.",
    "stream": false
  }'

Keep the Runtime API key on a server or in a secret manager. Do not call the Runtime API directly from public browser code.

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	Teamspace Runtime API key beginning with `sk_runtime_`
`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
`assets`	array	No	Previously uploaded asset file IDs to include with the message	Array of file ID strings
`stream`	boolean	No	Enable real-time response streaming	Default: `false`
`disable_conversation_history`	boolean	No	Skip prior messages when processing this turn	Default: `false`
`hitl_resume`	object	No	Resume a paused Human Input request	Requires `conversation_id`

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

​Overview

​When to use the Runtime API

​Authentication

​Quick start

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