Importing Products

Runtype’s /now flow is backed by public JSON import endpoints. You can use them to preview a product architecture from a hosted JSON file or pasted JSON, then create the product once the preview looks correct.

Raw FPO documents and FPO templates currently require version: "1.0". Templates also require productObject.version: "1.0".

Supported Sources

The import APIs support explicit JSON sources only:

A2A agent cards
raw Full Product Object (FPO) JSON
FPO template JSON

The following are intentionally unsupported:

GitHub repository homepages
README and markdown URLs
raw JSON passed through query params
generic website or repo crawling

GitHub URLs are supported only when they point to a specific JSON file. github.com/.../blob/... URLs and raw GitHub file URLs are normalized automatically before fetch. Gists must use a raw gist file URL that points to one concrete JSON file.

Import Flow

The import flow has three steps:

Preview the source with POST /v1/quick-start/imports/preview
Reload the preview later with GET /v1/quick-start/imports/:token
Create the product with POST /v1/quick-start/create

Preview endpoints are public. Product creation requires authentication.

Step 1: Preview a Hosted JSON Document

Use a URL source when you want /now or your own app to preview a public JSON file directly.

cURL

$ curl https://api.runtype.com/v1/quick-start/imports/preview \
>   -H "Content-Type: application/json" \
>   -d '{
>     "source": {
>       "kind": "url",
>       "url": "https://raw.githubusercontent.com/runtypelabs/core/main/docs/templates/quick-start/customer-support-fpo.json"
>     }
>   }'

TypeScript

1 const previewResponse = await fetch('https://api.runtype.com/v1/quick-start/imports/preview', {
2   method: 'POST',
3   headers: {
4     'Content-Type': 'application/json',
5   },
6   body: JSON.stringify({
7     source: {
8       kind: 'url',
9       url: 'https://raw.githubusercontent.com/runtypelabs/core/main/docs/templates/quick-start/customer-support-fpo.json',
10     },
11   }),
12 })
13 
14 const preview = await previewResponse.json()
15 console.log(preview.importToken)
16 console.log(preview.sourceType) // "fpo"
17 console.log(preview.preview.productName)

Step 1b: Preview Pasted JSON

Use a JSON source when you already have the document in memory and do not want to host it first.

cURL

$ curl https://api.runtype.com/v1/quick-start/imports/preview \
>   -H "Content-Type: application/json" \
>   -d @- <<'EOF'
$ {
>   "source": {
>     "kind": "json",
>     "label": "Customer Support Template",
>     "content": "{\"version\":\"1.0\",\"productObject\":{\"version\":\"1.0\",\"product\":{\"name\":\"{{productName}}\",\"description\":\"Support automation for {{companyName}}\"},\"capabilities\":[{\"id\":\"cap_support\",\"name\":\"Support Agent\",\"description\":\"Handle incoming support requests.\",\"agent\":{\"name\":\"{{productName}} Agent\",\"description\":\"Handle support requests for {{companyName}}.\",\"model\":\"claude-sonnet-4-5\"}}],\"tools\":[],\"surfaces\":[{\"id\":\"surface_chat\",\"name\":\"{{productName}} Chat\",\"type\":\"chat\",\"config\":{},\"routes\":[{\"capabilityId\":\"cap_support\"}]}],\"_meta\":{\"schemaVersion\":\"1.0\",\"catalogVersion\":\"1.0\",\"generatedAt\":\"2026-03-07T00:00:00.000Z\",\"generatorVersion\":\"1.0.0\",\"planHash\":\"import-json-example\"}},\"template\":{\"variables\":[{\"key\":\"productName\",\"label\":\"Product Name\",\"inputType\":\"text\",\"required\":true,\"defaultValue\":\"Acme Support Copilot\"},{\"key\":\"companyName\",\"label\":\"Company Name\",\"inputType\":\"text\",\"required\":true}]}}"
>   }
> }
$ EOF

TypeScript

1 const templateDocument = await fetch('/customer-support-template.json').then((response) =>
2   response.text()
3 )
4 
5 const previewResponse = await fetch('https://api.runtype.com/v1/quick-start/imports/preview', {
6   method: 'POST',
7   headers: {
8     'Content-Type': 'application/json',
9   },
10   body: JSON.stringify({
11     source: {
12       kind: 'json',
13       label: 'Customer Support Template',
14       content: templateDocument,
15     },
16   }),
17 })
18 
19 const preview = await previewResponse.json()
20 console.log(preview.sourceType) // "fpo-template"
21 console.log(preview.template?.variables)

Step 2: Reload a Preview Session

Preview responses return an importToken. Use it to restore the same preview after an auth redirect or page refresh.

cURL

$ curl https://api.runtype.com/v1/quick-start/imports/qsi_example_token

TypeScript

1 const session = await fetch(
2   'https://api.runtype.com/v1/quick-start/imports/qsi_example_token'
3 ).then((response) => response.json())
4 
5 console.log(session.importToken)
6 console.log(session.architecture)

Preview sessions currently expire after 30 minutes. If the token is missing or expired, the API returns SESSION_NOT_FOUND.

Step 3: Create the Product

Use the import token to create the product after the preview is accepted.

For raw FPO imports:

cURL

$ curl https://api.runtype.com/v1/quick-start/create \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "importToken": "qsi_example_token"
>   }'

TypeScript

1 const createResponse = await fetch('https://api.runtype.com/v1/quick-start/create', {
2   method: 'POST',
3   headers: {
4     Authorization: 'Bearer YOUR_API_KEY',
5     'Content-Type': 'application/json',
6   },
7   body: JSON.stringify({
8     importToken: 'qsi_example_token',
9   }),
10 })
11 
12 const created = await createResponse.json()
13 console.log(created.redirectUrl)

For FPO template imports, pass the variable values collected from your UI:

cURL

$ curl https://api.runtype.com/v1/quick-start/create \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "importToken": "qsi_template_token",
>     "variables": {
>       "companyName": "Acme",
>       "knowledgeBaseUrl": "https://docs.acme.com",
>       "searchApiKey": "fc_live_123"
>     }
>   }'

TypeScript

1 const created = await fetch('https://api.runtype.com/v1/quick-start/create', {
2   method: 'POST',
3   headers: {
4     Authorization: 'Bearer YOUR_API_KEY',
5     'Content-Type': 'application/json',
6   },
7   body: JSON.stringify({
8     importToken: 'qsi_template_token',
9     variables: {
10       companyName: 'Acme',
11       knowledgeBaseUrl: 'https://docs.acme.com',
12       searchApiKey: process.env.FIRECRAWL_API_KEY,
13     },
14   }),
15 }).then((response) => response.json())
16 
17 console.log(created.product.id)
18 console.log(created.redirectUrl)

Secret template values are used to resolve the final product object, but they are not stored in preview payloads, quick-start provenance metadata, or the create response.

Deploy to Runtype Buttons

For repository buttons, link directly to a hosted JSON document:

1 [![Deploy to Runtype](https://runtype.com/badge.svg)](https://use.runtype.com/now?from=https%3A%2F%2Fraw.githubusercontent.com%2Fruntypelabs%2Fcore%2Fmain%2Fdocs%2Ftemplates%2Fquick-start%2Fcustomer-support-fpo.json)

The hosted example files used in this guide live at:

docs/templates/quick-start/customer-support-fpo.json
docs/templates/quick-start/customer-support-fpo-template.json
docs/templates/quick-start/deploy-to-runtype.md

Importing Products

Raw FPO documents and FPO templates currently require version: "1.0". Templates also require productObject.version: "1.0".

Supported Sources

The import APIs support explicit JSON sources only:

A2A agent cards
raw Full Product Object (FPO) JSON
FPO template JSON

The following are intentionally unsupported:

GitHub repository homepages
README and markdown URLs
raw JSON passed through query params
generic website or repo crawling

Import Flow

The import flow has three steps:

Preview the source with POST /v1/quick-start/imports/preview
Reload the preview later with GET /v1/quick-start/imports/:token
Create the product with POST /v1/quick-start/create

Preview endpoints are public. Product creation requires authentication.

Step 1: Preview a Hosted JSON Document

Use a URL source when you want /now or your own app to preview a public JSON file directly.

cURL

$ curl https://api.runtype.com/v1/quick-start/imports/preview \
>   -H "Content-Type: application/json" \
>   -d '{
>     "source": {
>       "kind": "url",
>       "url": "https://raw.githubusercontent.com/runtypelabs/core/main/docs/templates/quick-start/customer-support-fpo.json"
>     }
>   }'

TypeScript

1 const previewResponse = await fetch('https://api.runtype.com/v1/quick-start/imports/preview', {
2   method: 'POST',
3   headers: {
4     'Content-Type': 'application/json',
5   },
6   body: JSON.stringify({
7     source: {
8       kind: 'url',
9       url: 'https://raw.githubusercontent.com/runtypelabs/core/main/docs/templates/quick-start/customer-support-fpo.json',
10     },
11   }),
12 })
13 
14 const preview = await previewResponse.json()
15 console.log(preview.importToken)
16 console.log(preview.sourceType) // "fpo"
17 console.log(preview.preview.productName)

Step 1b: Preview Pasted JSON

Use a JSON source when you already have the document in memory and do not want to host it first.

cURL

$ curl https://api.runtype.com/v1/quick-start/imports/preview \
>   -H "Content-Type: application/json" \
>   -d @- <<'EOF'
$ {
>   "source": {
>     "kind": "json",
>     "label": "Customer Support Template",
>     "content": "{\"version\":\"1.0\",\"productObject\":{\"version\":\"1.0\",\"product\":{\"name\":\"{{productName}}\",\"description\":\"Support automation for {{companyName}}\"},\"capabilities\":[{\"id\":\"cap_support\",\"name\":\"Support Agent\",\"description\":\"Handle incoming support requests.\",\"agent\":{\"name\":\"{{productName}} Agent\",\"description\":\"Handle support requests for {{companyName}}.\",\"model\":\"claude-sonnet-4-5\"}}],\"tools\":[],\"surfaces\":[{\"id\":\"surface_chat\",\"name\":\"{{productName}} Chat\",\"type\":\"chat\",\"config\":{},\"routes\":[{\"capabilityId\":\"cap_support\"}]}],\"_meta\":{\"schemaVersion\":\"1.0\",\"catalogVersion\":\"1.0\",\"generatedAt\":\"2026-03-07T00:00:00.000Z\",\"generatorVersion\":\"1.0.0\",\"planHash\":\"import-json-example\"}},\"template\":{\"variables\":[{\"key\":\"productName\",\"label\":\"Product Name\",\"inputType\":\"text\",\"required\":true,\"defaultValue\":\"Acme Support Copilot\"},{\"key\":\"companyName\",\"label\":\"Company Name\",\"inputType\":\"text\",\"required\":true}]}}"
>   }
> }
$ EOF

TypeScript

1 const templateDocument = await fetch('/customer-support-template.json').then((response) =>
2   response.text()
3 )
4 
5 const previewResponse = await fetch('https://api.runtype.com/v1/quick-start/imports/preview', {
6   method: 'POST',
7   headers: {
8     'Content-Type': 'application/json',
9   },
10   body: JSON.stringify({
11     source: {
12       kind: 'json',
13       label: 'Customer Support Template',
14       content: templateDocument,
15     },
16   }),
17 })
18 
19 const preview = await previewResponse.json()
20 console.log(preview.sourceType) // "fpo-template"
21 console.log(preview.template?.variables)

Step 2: Reload a Preview Session

Preview responses return an importToken. Use it to restore the same preview after an auth redirect or page refresh.

cURL

$ curl https://api.runtype.com/v1/quick-start/imports/qsi_example_token

TypeScript

1 const session = await fetch(
2   'https://api.runtype.com/v1/quick-start/imports/qsi_example_token'
3 ).then((response) => response.json())
4 
5 console.log(session.importToken)
6 console.log(session.architecture)

Preview sessions currently expire after 30 minutes. If the token is missing or expired, the API returns SESSION_NOT_FOUND.

Step 3: Create the Product

Use the import token to create the product after the preview is accepted.

For raw FPO imports:

cURL

$ curl https://api.runtype.com/v1/quick-start/create \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "importToken": "qsi_example_token"
>   }'

TypeScript

1 const createResponse = await fetch('https://api.runtype.com/v1/quick-start/create', {
2   method: 'POST',
3   headers: {
4     Authorization: 'Bearer YOUR_API_KEY',
5     'Content-Type': 'application/json',
6   },
7   body: JSON.stringify({
8     importToken: 'qsi_example_token',
9   }),
10 })
11 
12 const created = await createResponse.json()
13 console.log(created.redirectUrl)

For FPO template imports, pass the variable values collected from your UI:

cURL

$ curl https://api.runtype.com/v1/quick-start/create \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "importToken": "qsi_template_token",
>     "variables": {
>       "companyName": "Acme",
>       "knowledgeBaseUrl": "https://docs.acme.com",
>       "searchApiKey": "fc_live_123"
>     }
>   }'

TypeScript

1 const created = await fetch('https://api.runtype.com/v1/quick-start/create', {
2   method: 'POST',
3   headers: {
4     Authorization: 'Bearer YOUR_API_KEY',
5     'Content-Type': 'application/json',
6   },
7   body: JSON.stringify({
8     importToken: 'qsi_template_token',
9     variables: {
10       companyName: 'Acme',
11       knowledgeBaseUrl: 'https://docs.acme.com',
12       searchApiKey: process.env.FIRECRAWL_API_KEY,
13     },
14   }),
15 }).then((response) => response.json())
16 
17 console.log(created.product.id)
18 console.log(created.redirectUrl)

Secret template values are used to resolve the final product object, but they are not stored in preview payloads, quick-start provenance metadata, or the create response.

Deploy to Runtype Buttons

For repository buttons, link directly to a hosted JSON document:

1 [![Deploy to Runtype](https://runtype.com/badge.svg)](https://use.runtype.com/now?from=https%3A%2F%2Fraw.githubusercontent.com%2Fruntypelabs%2Fcore%2Fmain%2Fdocs%2Ftemplates%2Fquick-start%2Fcustomer-support-fpo.json)

The hosted example files used in this guide live at:

docs/templates/quick-start/customer-support-fpo.json
docs/templates/quick-start/customer-support-fpo-template.json
docs/templates/quick-start/deploy-to-runtype.md

$	curl https://api.runtype.com/v1/quick-start/imports/preview \
>	-H "Content-Type: application/json" \
>	-d '{
>	"source": {
>	"kind": "url",
>	"url": "https://raw.githubusercontent.com/runtypelabs/core/main/docs/templates/quick-start/customer-support-fpo.json"
>	}
>	}'

1	const previewResponse = await fetch('https://api.runtype.com/v1/quick-start/imports/preview', {
2	method: 'POST',
3	headers: {
4	'Content-Type': 'application/json',
5	},
6	body: JSON.stringify({
7	source: {
8	kind: 'url',
9	url: 'https://raw.githubusercontent.com/runtypelabs/core/main/docs/templates/quick-start/customer-support-fpo.json',
10	},
11	}),
12	})
13
14	const preview = await previewResponse.json()
15	console.log(preview.importToken)
16	console.log(preview.sourceType) // "fpo"
17	console.log(preview.preview.productName)

$	curl https://api.runtype.com/v1/quick-start/imports/preview \
>	-H "Content-Type: application/json" \
>	-d @- <<'EOF'
$	{
>	"source": {
>	"kind": "json",
>	"label": "Customer Support Template",
>	"content": "{\"version\":\"1.0\",\"productObject\":{\"version\":\"1.0\",\"product\":{\"name\":\"{{productName}}\",\"description\":\"Support automation for {{companyName}}\"},\"capabilities\":[{\"id\":\"cap_support\",\"name\":\"Support Agent\",\"description\":\"Handle incoming support requests.\",\"agent\":{\"name\":\"{{productName}} Agent\",\"description\":\"Handle support requests for {{companyName}}.\",\"model\":\"claude-sonnet-4-5\"}}],\"tools\":[],\"surfaces\":[{\"id\":\"surface_chat\",\"name\":\"{{productName}} Chat\",\"type\":\"chat\",\"config\":{},\"routes\":[{\"capabilityId\":\"cap_support\"}]}],\"_meta\":{\"schemaVersion\":\"1.0\",\"catalogVersion\":\"1.0\",\"generatedAt\":\"2026-03-07T00:00:00.000Z\",\"generatorVersion\":\"1.0.0\",\"planHash\":\"import-json-example\"}},\"template\":{\"variables\":[{\"key\":\"productName\",\"label\":\"Product Name\",\"inputType\":\"text\",\"required\":true,\"defaultValue\":\"Acme Support Copilot\"},{\"key\":\"companyName\",\"label\":\"Company Name\",\"inputType\":\"text\",\"required\":true}]}}"
>	}
>	}
$	EOF

1	const templateDocument = await fetch('/customer-support-template.json').then((response) =>
2	response.text()
3	)
4
5	const previewResponse = await fetch('https://api.runtype.com/v1/quick-start/imports/preview', {
6	method: 'POST',
7	headers: {
8	'Content-Type': 'application/json',
9	},
10	body: JSON.stringify({
11	source: {
12	kind: 'json',
13	label: 'Customer Support Template',
14	content: templateDocument,
15	},
16	}),
17	})
18
19	const preview = await previewResponse.json()
20	console.log(preview.sourceType) // "fpo-template"
21	console.log(preview.template?.variables)

1	const session = await fetch(
2	'https://api.runtype.com/v1/quick-start/imports/qsi_example_token'
3	).then((response) => response.json())
4
5	console.log(session.importToken)
6	console.log(session.architecture)

$	curl https://api.runtype.com/v1/quick-start/create \
>	-H "Authorization: Bearer YOUR_API_KEY" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"importToken": "qsi_example_token"
>	}'

1	const createResponse = await fetch('https://api.runtype.com/v1/quick-start/create', {
2	method: 'POST',
3	headers: {
4	Authorization: 'Bearer YOUR_API_KEY',
5	'Content-Type': 'application/json',
6	},
7	body: JSON.stringify({
8	importToken: 'qsi_example_token',
9	}),
10	})
11
12	const created = await createResponse.json()
13	console.log(created.redirectUrl)

1	const created = await fetch('https://api.runtype.com/v1/quick-start/create', {
2	method: 'POST',
3	headers: {
4	Authorization: 'Bearer YOUR_API_KEY',
5	'Content-Type': 'application/json',
6	},
7	body: JSON.stringify({
8	importToken: 'qsi_template_token',
9	variables: {
10	companyName: 'Acme',
11	knowledgeBaseUrl: 'https://docs.acme.com',
12	searchApiKey: process.env.FIRECRAWL_API_KEY,
13	},
14	}),
15	}).then((response) => response.json())
16
17	console.log(created.product.id)
18	console.log(created.redirectUrl)

Importing Products

Supported Sources

Import Flow

Step 1: Preview a Hosted JSON Document

Step 1b: Preview Pasted JSON

Step 2: Reload a Preview Session

Step 3: Create the Product

Deploy to Runtype Buttons

Related Guides

Importing Products

Supported Sources

Import Flow

Step 1: Preview a Hosted JSON Document

Step 1b: Preview Pasted JSON

Step 2: Reload a Preview Session

Step 3: Create the Product

Deploy to Runtype Buttons

Related Guides