Importing products

Preview a product from a JSON document, then create it in your account. The dashboard import page uses the same endpoints that this guide describes.

Before you begin

• To create a product, you need a Runtype API key. For more information, see Authentication.
• The preview endpoints don’t require authentication.

Supported sources

The import APIs accept these JSON sources:

• Agent-to-Agent (A2A) agent cards.
• Raw Full Product Object (FPO) JSON.
• FPO template JSON.

The import APIs reject these sources:

• GitHub repository homepages.
• README and Markdown URLs.
• Raw JSON passed through query parameters.
• Generic website or repository crawling.

Use GitHub URLs only for specific JSON files. The import service converts GitHub blob URLs to raw file URLs before it fetches them. It accepts raw GitHub file URLs as they are. For a gist, use a raw gist file URL that points to one JSON file.

A source URL must use https and respond with a Content-Type of application/json or text/plain, and the document must be 256 KB or smaller. The same size limit applies to pasted JSON.

Supported versions

The following table lists the version values that each source type accepts:

At 1.0 and 1.1, an inline agent keeps its runtime fields, such as model, directly on the agent object.

Import flow

To import a product, follow these steps:

1. Preview the source with POST /v1/quick-start/imports/preview.
2. Optional: Reload the preview with GET /v1/quick-start/imports/:token.
3. Create the product with POST /v1/quick-start/create.
4. Finish setup in the dashboard.

Step 1: Preview an import source

Choose a hosted URL or paste the JSON document into the request body.

Preview a hosted JSON document

To preview a public JSON file, send a URL source. The following TypeScript example sends the request:

const previewResponse = await fetch('https://api.runtype.com/v1/quick-start/imports/preview', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: {
      kind: 'url',
      url: 'https://example.com/YOUR_PRODUCT.json',
    },
  }),
})
const preview = await previewResponse.json()
console.log(preview.importToken)
console.log(preview.sourceType) // "fpo"
console.log(preview.preview.productName)

Replace https://example.com/YOUR_PRODUCT.json with the public URL of your FPO, FPO template, or agent card.

The following cURL command sends the same request:

curl https://api.runtype.com/v1/quick-start/imports/preview \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "kind": "url",
      "url": "https://example.com/YOUR_PRODUCT.json"
    }
  }'

Preview pasted JSON

To preview a document that you already have in memory, send a JSON source with its contents in content. The following TypeScript example reads a template file from your app and submits it:

const templateDocument = await fetch('/YOUR_TEMPLATE_FILENAME.json').then((response) =>
  response.text()
)
const previewResponse = await fetch('https://api.runtype.com/v1/quick-start/imports/preview', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: {
      kind: 'json',
      label: 'Customer Support Template',
      content: templateDocument,
    },
  }),
})
const preview = await previewResponse.json()
console.log(preview.sourceType) // "fpo-template"
console.log(preview.template?.variables)

Replace YOUR_TEMPLATE_FILENAME with the filename that your app serves.

The following cURL command sends a template as a JSON string in content:

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.1\",\"productObject\":{\"version\":\"2.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}}.\",\"config\":{\"model\":\"claude-sonnet-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\":\"Example Organization Support Copilot\"},{\"key\":\"companyName\",\"label\":\"Company Name\",\"inputType\":\"text\",\"required\":true}]}}"
  }
}
EOF

The content string declares two template variables, productName and companyName. Only productName has a default value.

Preview an A2A agent card

An A2A agent card is a JSON document with a top-level name and optional fields such as description, url, and skills. Send it as a URL or pasted JSON source, the same way as an FPO. The preview response returns sourceType: "a2a-agent".

Preview response

The preview response describes the product before anything is created. The following table lists the fields to check:

If template.defaultsSufficient is true, you can create the product without a variables object. If pendingSecrets is present, have those credentials ready before you finish setup.

Step 2: Reload a preview session

Use the importToken from the preview response to restore the preview after an authentication redirect or page refresh.

The following TypeScript example restores the preview session:

const session = await fetch(
  'https://api.runtype.com/v1/quick-start/imports/qsi_YOUR_IMPORT_TOKEN'
).then((response) => response.json())
console.log(session.importToken)
console.log(session.architecture)

Replace qsi_YOUR_IMPORT_TOKEN with the token returned by the preview request.

The following cURL command restores the same preview session:

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

The response has the same shape as the preview response. Preview sessions expire after 30 minutes. When the token doesn’t identify a stored session, the API returns 404 with the code SESSION_NOT_FOUND.

Step 3: Create the product

Use the import token to create the product after you accept the preview.

Create a product from a raw FPO

To create a raw FPO import, send the importToken in a request that includes your API key. The following TypeScript example creates the product:

const createResponse = await fetch('https://api.runtype.com/v1/quick-start/create', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    importToken: 'qsi_YOUR_IMPORT_TOKEN',
  }),
})
const created = await createResponse.json()
console.log(created.redirectUrl)

Replace YOUR_API_KEY with your Runtype API key and qsi_YOUR_IMPORT_TOKEN with the preview token.

The following cURL command creates the same raw FPO import:

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

Create a product from an FPO template

To create an FPO template import, send values for required template variables that don’t have defaults. The following TypeScript example sends the required values:

const created = await fetch('https://api.runtype.com/v1/quick-start/create', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    importToken: 'qsi_YOUR_TEMPLATE_IMPORT_TOKEN',
    variables: {
      companyName: 'Example Organization',
    },
  }),
}).then((response) => response.json())
console.log(created.product.id)
console.log(created.redirectUrl)

Replace YOUR_API_KEY with your Runtype API key and qsi_YOUR_TEMPLATE_IMPORT_TOKEN with the preview token. If your template declares more variables, include their values under variables.

The following cURL command creates the same FPO template import:

curl https://api.runtype.com/v1/quick-start/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "importToken": "qsi_YOUR_TEMPLATE_IMPORT_TOKEN",
    "variables": {
      "companyName": "Example Organization"
    }
  }'

Variables with inputType: "secret" can’t have default values. Runtype substitutes a secret variable’s value into the product and stores it in the product record. To keep a credential in your secrets instead, declare it as a pending secret on the tool that uses it. For more information, see Collect credentials.

Create a product from an A2A agent card

An A2A import accepts an optional productName field that overrides the name from the agent card. The name must be 1 to 255 characters. The following cURL command creates an A2A import with a custom name:

curl https://api.runtype.com/v1/quick-start/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "importToken": "qsi_YOUR_A2A_IMPORT_TOKEN",
    "productName": "Research Assistant"
  }'

For an FPO or FPO template import, productName returns a 400 error. Set the product name in the document instead.

Create response

A successful create returns 201. The following table lists the response fields:

Each successful create issues a new test API key. The key allows 20 executions a day and 200 in total. Store the key value if you plan to call the product with it.

Step 4: Finish setup

The redirectUrl value is a path in the dashboard, not a full URL. To finish setup, open https://use.runtype.com followed by the path.

If a tool in the product needs credentials that you haven’t set up yet, the path opens the secrets configuration page instead of the product. Enter the listed secrets before you test the product. For more information, see Managing secrets.

Required API key scopes

A dashboard session can create any import. An API key must hold the scopes for everything the product creates:

Entities with createPolicy: "skip" do not need their scope. Test keys (rt_test_ prefix) cannot hold SECRETS:WRITE, so a test key cannot create a product that declares secrets. Use a live key with SECRETS:WRITE, or create the product from the dashboard.

Errors

If the request has no valid credential, the API returns HTTP 401 with the UNAUTHORIZED code:

{
  "success": false,
  "error": "Authentication required",
  "code": "UNAUTHORIZED"
}

If the API key does not hold a required scope, the API returns HTTP 403 with the FORBIDDEN code. The error field names the missing scopes, and details.missingScopes lists them. Each inner list holds scopes of which the key needs one:

{
  "success": false,
  "error": "Insufficient permissions. This FPO requires: FLOWS:WRITE, SCHEDULES:WRITE",
  "code": "FORBIDDEN",
  "details": { "missingScopes": [["FLOWS:WRITE"], ["SCHEDULES:WRITE"]] }
}

The API creates nothing when it returns 403.

Create a repository button

To add a Deploy to Runtype link to a repository README, link to the import page with your document’s URL in the from query parameter. URL-encode the document URL. The following Markdown snippet creates the link:

[Deploy to Runtype](https://use.runtype.com/now?from=https%3A%2F%2Fexample.com%2FYOUR_PRODUCT.json)

To prefill a template variable, add a templateParam:VARIABLE_KEY query parameter for each value. URL-encode the colon as %3A. The following link prefills companyName:

[Deploy to Runtype](https://use.runtype.com/now?from=https%3A%2F%2Fexample.com%2FYOUR_TEMPLATE.json&templateParam%3AcompanyName=Acme)

The import page ignores prefilled values for secret variables.

Troubleshooting

Error responses carry a code field, an error message, and, when relevant, a details array. The following table lists the preview errors:

The following table lists the create errors:

Next steps

• FPO templates: define reusable product templates with user-provided values.
• Runtype MCP server: import a product from an AI agent with the create_product_from_example tool and its url and variables inputs.
• Quickstart: make your first Runtype API call.