> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sketricgen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Public API

> SketricGen Public API reference — run AI agent workflows, stream responses, and manage conversations with RESTful endpoints and API key auth.

## 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](/deploy/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](https://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

```json theme={null}
{
	"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:

```text theme={null}
customer_12345
user_uuid_550e8400-e29b-41d4-a716-446655440000
customer_hash_abc123def456
```

Avoid:

```text theme={null}
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:

```json theme={null}
{
	"agent_id": "agent_abc123xyz",
	"user_input": "What's my order status?",
	"contact_id": "customer_12345",
	"stream": false
}
```

Widget equivalent:

```html theme={null}
<script
  src="https://jswidget.sketricgen.ai/widget-embed.js"
  data-agent-id="YOUR_AGENT_ID"
  data-contact-id="customer_12345"
></script>
```

Iframe equivalent:

```html theme={null}
<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:**

```json theme={null}
{
	"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"}
```