Getting Started

Quickstart

This guide will help you make your first Runtype API call and execute an AI flow.

Prerequisites

Step 1: Test Your API Key

Let’s verify your API key works by checking your profile:

cURL
$curl https://api.runtype.com/v1/users/profile \
>  -H "Authorization: Bearer YOUR_API_KEY"
TypeScript
1const response = await fetch('https://api.runtype.com/v1/users/profile', {
2  headers: {
3    'Authorization': 'Bearer YOUR_API_KEY'
4  }
5});
6const profile = await response.json();
7console.log(profile);
Python
1import requests
2
3response = requests.get(
4    'https://api.runtype.com/v1/users/profile',
5    headers={'Authorization': 'Bearer YOUR_API_KEY'}
6)
7print(response.json())

Step 2: Create and Execute a Flow

The /dispatch endpoint is the main way to execute AI flows. Here’s a minimal example:

cURL
$curl https://api.runtype.com/v1/dispatch \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "inputs": {
>      "customerName": "Acme Corp",
>      "topic": "sales report"
>    },
>    "flow": {
>      "name": "Hello World Flow",
>      "steps": [
>        {
>          "id": "greeting",
>          "name": "Greeting",
>          "type": "prompt",
>          "order": 1,
>          "config": {
>            "model": "gpt-5.4-mini",
>            "userPrompt": "Create a greeting for {{customerName}} about their {{topic}}!",
>            "outputVariable": "greeting"
>          }
>        }
>      ]
>    }
>  }'
TypeScript
1const response = await fetch('https://api.runtype.com/v1/dispatch', {
2  method: 'POST',
3  headers: {
4    'Authorization': 'Bearer YOUR_API_KEY',
5    'Content-Type': 'application/json'
6  },
7  body: JSON.stringify({
8    inputs: {
9      customerName: 'Acme Corp',
10      topic: 'sales report'
11    },
12    flow: {
13      name: 'Hello World Flow',
14      steps: [{
15        id: 'greeting',
16        name: 'Greeting',
17        type: 'prompt',
18        order: 1,
19        config: {
20          model: 'gpt-5.4-mini',
21          userPrompt: 'Create a greeting for {{customerName}} about their {{topic}}!',
22          outputVariable: 'greeting'
23        }
24      }]
25    }
26  })
27});
28
29// Handle streaming response
30const reader = response.body.getReader();
31const decoder = new TextDecoder();
32
33while (true) {
34  const { done, value } = await reader.read();
35  if (done) break;
36  console.log(decoder.decode(value));
37}

The inputs field lets you pass variables directly accessible as {{varName}} in templates. For transient data, inputs provides cleaner syntax than record.metadata. Use record.metadata when you need data to persist with the record in the database.

Step 3: Understanding the Response

The dispatch endpoint returns a Server-Sent Events (SSE) stream:

event: execution_start
data: {"type":"execution_start","executionId":"exec_abc123","seq":0,"kind":"flow","flowId":"flow_xyz789","flowName":"Customer Greeting","totalSteps":1}
event: step_start
data: {"type":"step_start","executionId":"exec_abc123","seq":1,"id":"step_greeting","name":"Greeting","stepType":"prompt","index":0,"totalSteps":1}
event: text_start
data: {"type":"text_start","executionId":"exec_abc123","seq":2,"id":"text_1"}
event: text_delta
data: {"type":"text_delta","executionId":"exec_abc123","seq":3,"id":"text_1","delta":"Hello there, Quick Test!"}
event: text_complete
data: {"type":"text_complete","executionId":"exec_abc123","seq":4,"id":"text_1"}
event: step_complete
data: {"type":"step_complete","executionId":"exec_abc123","seq":5,"id":"step_greeting","name":"Greeting","success":true,"result":"Hello there, Quick Test!..."}
event: execution_complete
data: {"type":"execution_complete","executionId":"exec_abc123","seq":6,"kind":"flow","success":true,"finalOutput":"Hello there, Quick Test!..."}

The stream events

Every streaming endpoint (/v1/dispatch, /v1/agents/{id}/execute, and the client chat routes) emits one shared set of event names across flows and agents, such as execution_start, step_start, text_delta, tool_start, tool_input_complete, and execution_complete. These are the events documented in the API reference and the generated SDK types.

Install our TypeScript SDK for a better developer experience:

$npm install @runtypelabs/sdk
1import { RuntypeClient, FlowBuilder } from '@runtypelabs/sdk';
2
3const client = new RuntypeClient({
4  apiKey: process.env.RUNTYPE_API_KEY
5});
6
7// Using the FlowBuilder for a fluent API
8const result = await new FlowBuilder()
9  .createFlow({ name: 'Customer Greeting' })
10  .withInputs({
11    customerName: 'John Doe',
12    accountType: 'premium'
13  })
14  .prompt({
15    name: 'Personalized Greeting',
16    model: 'gpt-5.4',
17    userPrompt: 'Create a warm greeting for {{customerName}} ({{accountType}} customer)'
18  })
19  .run(client);
20
21console.log(result.getResult('Personalized Greeting'));

The withInputs() method passes data that’s accessible as {{varName}} in your prompts. This is the recommended approach for passing dynamic data to flows.

Validate before running

Call validate() to check a flow before you run it. It surfaces structural issues, undeclared-variable warnings, and sub-optimal model selections at author time, without creating or executing the flow:

1const builder = new FlowBuilder()
2  .createFlow({ name: 'Customer Greeting' })
3  .prompt({
4    name: 'Personalized Greeting',
5    model: 'gpt-5.4',
6    userPrompt: 'Create a warm greeting for {{customerName}}'
7  });
8
9const validation = await builder.validate(client);
10if (!validation.valid) {
11  for (const issue of validation.errors) {
12    console.error(issue.code, issue.message);
13  }
14}

validate() runs against the public validation endpoint and does not consume execution quota. Pass an authenticated client to additionally check that referenced tools, flows, and agents exist in your account — validation.context.accountChecksPerformed reports whether those checks ran.

Import an Existing Product Spec

If you already have a product described as JSON, you can preview and create it through Runtype’s import flow instead of building it step by step.

  • Use Importing Products for A2A agent cards, raw Full Product Objects, and hosted JSON imports
  • Use FPO Templates when you want creators to publish reusable product templates with user-fillable variables

These flows power /now, “Deploy to Runtype” buttons, and other integrations that hand Runtype a complete product definition.

Next Steps

Core Concepts

Learn about flows, records, and steps

API Reference

Explore all available endpoints

TypeScript SDK

Full SDK documentation

Guides

In-depth tutorials and examples