Quickstart

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

Prerequisites

A Runtype account (sign up free)
An API key (get one here)

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

1 const response = await fetch('https://api.runtype.com/v1/users/profile', {
2   headers: {
3     'Authorization': 'Bearer YOUR_API_KEY'
4   }
5 });
6 const profile = await response.json();
7 console.log(profile);

Python

1 import requests
2 
3 response = requests.get(
4     'https://api.runtype.com/v1/users/profile',
5     headers={'Authorization': 'Bearer YOUR_API_KEY'}
6 )
7 print(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

1 const 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
30 const reader = response.body.getReader();
31 const decoder = new TextDecoder();
32 
33 while (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: step_start
data: {"stepName": "Greeting", "stepType": "prompt"}
event: step_delta
data: {"text": "Hello"}
event: step_delta
data: {"text": " there"}
event: step_delta
data: {"text": ", Quick Test!"}
event: step_complete
data: {"stepName": "Greeting", "result": "Hello there, Quick Test!..."}
event: flow_complete
data: {"success": true, "recordId": "rec_abc123", "flowId": "flow_xyz789"}

Step 4: Using the SDK (Recommended)

Install our TypeScript SDK for a better developer experience:

$ npm install @runtypelabs/sdk

1 import { RuntypeClient, FlowBuilder } from '@runtypelabs/sdk';
2 
3 const client = new RuntypeClient({
4   apiKey: process.env.RUNTYPE_API_KEY
5 });
6 
7 // Using the FlowBuilder for a fluent API
8 const 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 
21 console.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:

1 const 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 
9 const validation = await builder.validate(client);
10 if (!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

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

Prerequisites

A Runtype account (sign up free)
An API key (get one here)

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

1 const response = await fetch('https://api.runtype.com/v1/users/profile', {
2   headers: {
3     'Authorization': 'Bearer YOUR_API_KEY'
4   }
5 });
6 const profile = await response.json();
7 console.log(profile);

Python

1 import requests
2 
3 response = requests.get(
4     'https://api.runtype.com/v1/users/profile',
5     headers={'Authorization': 'Bearer YOUR_API_KEY'}
6 )
7 print(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

1 const 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
30 const reader = response.body.getReader();
31 const decoder = new TextDecoder();
32 
33 while (true) {
34   const { done, value } = await reader.read();
35   if (done) break;
36   console.log(decoder.decode(value));
37 }

Step 3: Understanding the Response

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

event: step_start
data: {"stepName": "Greeting", "stepType": "prompt"}
event: step_delta
data: {"text": "Hello"}
event: step_delta
data: {"text": " there"}
event: step_delta
data: {"text": ", Quick Test!"}
event: step_complete
data: {"stepName": "Greeting", "result": "Hello there, Quick Test!..."}
event: flow_complete
data: {"success": true, "recordId": "rec_abc123", "flowId": "flow_xyz789"}

Step 4: Using the SDK (Recommended)

Install our TypeScript SDK for a better developer experience:

$ npm install @runtypelabs/sdk

1 import { RuntypeClient, FlowBuilder } from '@runtypelabs/sdk';
2 
3 const client = new RuntypeClient({
4   apiKey: process.env.RUNTYPE_API_KEY
5 });
6 
7 // Using the FlowBuilder for a fluent API
8 const 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 
21 console.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

1 const 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 
9 const validation = await builder.validate(client);
10 if (!validation.valid) {
11   for (const issue of validation.errors) {
12     console.error(issue.code, issue.message);
13   }
14 }

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

$	curl https://api.runtype.com/v1/users/profile \
>	-H "Authorization: Bearer YOUR_API_KEY"

1	const response = await fetch('https://api.runtype.com/v1/users/profile', {
2	headers: {
3	'Authorization': 'Bearer YOUR_API_KEY'
4	}
5	});
6	const profile = await response.json();
7	console.log(profile);

1	import requests
2
3	response = requests.get(
4	'https://api.runtype.com/v1/users/profile',
5	headers={'Authorization': 'Bearer YOUR_API_KEY'}
6	)
7	print(response.json())

$	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"
>	}
>	}
>	]
>	}
>	}'

1	const 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
30	const reader = response.body.getReader();
31	const decoder = new TextDecoder();
32
33	while (true) {
34	const { done, value } = await reader.read();
35	if (done) break;
36	console.log(decoder.decode(value));
37	}

1	import { RuntypeClient, FlowBuilder } from '@runtypelabs/sdk';
2
3	const client = new RuntypeClient({
4	apiKey: process.env.RUNTYPE_API_KEY
5	});
6
7	// Using the FlowBuilder for a fluent API
8	const 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
21	console.log(result.getResult('Personalized Greeting'));

1	const 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
9	const validation = await builder.validate(client);
10	if (!validation.valid) {
11	for (const issue of validation.errors) {
12	console.error(issue.code, issue.message);
13	}
14	}