Guides

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 accept version: "1.0", "1.1", or "2.0" ("2.0" is the current default, which nests each inline agent’s runtime fields under agent.config; "1.0" and "1.1" remain valid for legacy flat-agent documents). FPO templates require productObject.version to be one of these same values.

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:

  1. Preview the source with POST /v1/quick-start/imports/preview
  2. Reload the preview later with GET /v1/quick-start/imports/:token
  3. 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
1const 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
14const preview = await previewResponse.json()
15console.log(preview.importToken)
16console.log(preview.sourceType) // "fpo"
17console.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
1const templateDocument = await fetch('/customer-support-template.json').then((response) =>
2  response.text()
3)
4
5const 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
19const preview = await previewResponse.json()
20console.log(preview.sourceType) // "fpo-template"
21console.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
1const session = await fetch(
2  'https://api.runtype.com/v1/quick-start/imports/qsi_example_token'
3).then((response) => response.json())
4
5console.log(session.importToken)
6console.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
1const 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
12const created = await createResponse.json()
13console.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
1const 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
17console.log(created.product.id)
18console.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