For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dashboard
User GuideDeveloper GuidesAPI Reference
User GuideDeveloper GuidesAPI Reference
  • Getting Started
    • Introduction
    • Authentication
    • Quickstart
  • Guides
    • Working with Tools
    • Runtime Tools
    • FPO Templates
    • Importing Products
  • Integrations
    • MCP Servers
Dashboard
LogoLogo
On this page
  • Quickstart
  • Prerequisites
  • Step 1: Test Your API Key
  • Step 2: Create and Execute a Flow
  • Step 3: Understanding the Response
  • Step 4: Using the SDK (Recommended)
  • Import an Existing Product Spec
  • Next Steps
Getting Started

Quickstart

Was this page helpful?
Previous

Working with Tools

Next
Built with

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
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-4o-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-4o-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: 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
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-4o',
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.

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