FPO templates

An FPO template wraps a full product object (FPO). Use it to share a reusable product definition and collect values from each person who imports it.

Use an FPO template when you need to:

• Keep the product structure stable.
• Collect names, URLs, or environment-specific values during import.
• Ask for the credentials that the product’s tools need.
• Preview the product on the dashboard import page (use.runtype.com/now) before you create it.

Template shape

An FPO template uses these top-level keys:

• version sets the template document format version. Use 1.0 or 1.1.
• productObject contains the FPO.
• template.variables contains metadata for each variable that the FPO references.

Set productObject.version to 1.0, 1.1, or 2.0. Use 2.0 for new templates. In 2.0, place inline agent runtime fields under agent.config. In 1.0 and 1.1, place those fields directly on the agent object.

The following table lists the top-level keys of productObject:

The _meta object needs five non-empty strings: schemaVersion, catalogVersion, generatedAt, generatorVersion, and planHash. When you write a template by hand, fill them with descriptive values, as the example template does.

Each capability sets exactly one of flow, agent, existingFlowId, or existingAgentId.

Use variable references in string values within the FPO:

{
  "name": "{{productName}}"
}

Variable manifest

Declare each variable in template.variables with the following fields:

A template can declare up to 50 variables.

Resolution rules

Runtype resolves a template with these rules:

• Every {{variableName}} reference must be declared in the manifest.
• Inline defaults such as {{apiKey|default}} are not allowed. Define defaults with template.variables[].defaultValue.
• A template must declare at least one variable, or at least one tool with auth.setupRequired: true and one or more auth.secrets entries.
• References to {{secret:NAME}} and to system variables, such as {{_now.iso}} or {{userMessage}}, don’t need a declaration. Runtype leaves them for run time.
• Every other {{...}} token counts as a template variable, including a runtime token in a step prompt or a Liquid template. To keep a runtime token, declare a template variable whose defaultValue is the token, and reference that variable in its place.
• A value supplied for a number variable is converted to a number. A non-numeric value counts as missing.
• A value supplied for a boolean variable is converted from the strings true and false. Any other value counts as missing.
• When a field value is exactly {{variableName}} and the variable is a number or boolean, the field keeps that scalar type.
• Every other substitution resolves to a string.

Collect credentials

To ask the importer for an API key or token, declare it as a pending secret on the tool that uses it. Reference the secret in the tool configuration with {{secret:KEY}}. Runtype stores the value in your secrets, not in the product object.

The following fields define a tool’s auth object:

Use the following structure to reference a pending secret in a tool:

{
  "id": "tool_search",
  "type": "integration",
  "provider": "firecrawl",
  "name": "Knowledge Search",
  "config": {
    "headers": {
      "Authorization": "Bearer {{secret:SEARCH_API_KEY}}"
    }
  },
  "auth": {
    "type": "api_key",
    "setupRequired": true,
    "secrets": [
      {
        "key": "SEARCH_API_KEY",
        "required": true,
        "description": "API key for knowledge searches."
      }
    ],
    "setupInstructions": {
      "summary": "Add your search provider API key.",
      "steps": ["Create an API key with your search provider.", "Add it as a secret after import."],
      "docsUrl": "https://example.com/docs/api-keys"
    }
  }
}

The import preview returns these entries in pendingSecrets. The dashboard import page lists them under Secrets to configure after import, with each secret’s key, tool name, description, and a Get key link to docsUrl. When you create the product, Runtype adds each secret to your account without a value. If your account already has a secret with the same key, the product uses that secret instead. Validation doesn’t check the key format, and the import skips any secret whose key breaks the format rule in the preceding table. To set a value, see Managing secrets.

Example template

Use this complete template as a starting point:

{
  "version": "1.0",
  "productObject": {
    "version": "2.0",
    "product": {
      "name": "{{productName}}",
      "description": "Support automation for {{companyName}}",
      "metadata": {
        "requireEscalationApproval": "{{requireEscalationApproval}}",
        "responseTimeoutMinutes": "{{responseTimeoutMinutes}}"
      }
    },
    "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",
            "systemPrompt": "Use a {{brandVoice}} tone when responding."
          }
        }
      }
    ],
    "tools": [
      {
        "id": "tool_search",
        "type": "integration",
        "provider": "{{searchProvider}}",
        "name": "Knowledge Search",
        "config": {
          "baseUrl": "{{knowledgeBaseUrl}}",
          "headers": {
            "Authorization": "Bearer {{secret:SEARCH_API_KEY}}"
          }
        },
        "auth": {
          "type": "api_key",
          "setupRequired": true,
          "secrets": [
            {
              "key": "SEARCH_API_KEY",
              "required": true,
              "description": "API key for knowledge searches."
            }
          ],
          "setupInstructions": {
            "summary": "Add your search provider API key.",
            "steps": ["Create an API key with your search provider.", "Add it as a secret after import."]
          }
        }
      }
    ],
    "surfaces": [
      {
        "id": "surface_chat",
        "name": "{{productName}} Chat",
        "type": "chat",
        "config": {},
        "routes": [
          {
            "capabilityId": "cap_support"
          }
        ]
      }
    ],
    "_meta": {
      "schemaVersion": "2.0",
      "catalogVersion": "1.0",
      "generatedAt": "2026-03-07T00:00:00.000Z",
      "generatorVersion": "1.0.0",
      "planHash": "template-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
      },
      {
        "key": "knowledgeBaseUrl",
        "label": "Knowledge Base URL",
        "inputType": "url",
        "required": true
      },
      {
        "key": "searchProvider",
        "label": "Search Provider",
        "inputType": "select",
        "required": true,
        "defaultValue": "firecrawl",
        "options": [
          { "label": "Firecrawl", "value": "firecrawl" },
          { "label": "Exa", "value": "exa" }
        ]
      },
      {
        "key": "requireEscalationApproval",
        "label": "Require Escalation Approval",
        "inputType": "boolean",
        "required": true,
        "defaultValue": true
      },
      {
        "key": "responseTimeoutMinutes",
        "label": "Response Timeout Minutes",
        "inputType": "number",
        "required": true,
        "defaultValue": 15
      },
      {
        "key": "brandVoice",
        "label": "Brand Voice",
        "inputType": "textarea",
        "required": false,
        "defaultValue": "Calm and direct."
      }
    ]
  }
}

Add scheduled jobs

Use the top-level productObject.schedules[] array for cron or one-time automation. Each schedule targets a capability through capabilityId. Importing the FPO creates the schedule.

A capability that a schedule targets doesn’t need a surface route. Don’t add a type: "schedule" surface to trigger the schedule. Add a schedule surface only when users or operators need a dedicated surface to inspect and manage schedule behavior.

The following fields define a schedule in an FPO:

Use the following structure to define a scheduled capability:

{
  "productObject": {
    "capabilities": [
      {
        "id": "cap_support",
        "name": "Support Agent",
        "description": "Answer user questions.",
        "agent": {
          "name": "Support Agent",
          "description": "Answer user questions.",
          "config": { "model": "claude-sonnet-5" }
        }
      },
      {
        "id": "cap_weekly_digest",
        "name": "Weekly Digest",
        "description": "Summarize new records each Monday.",
        "agent": {
          "name": "Weekly Digest",
          "description": "Summarize new records.",
          "config": { "model": "claude-sonnet-5" }
        }
      }
    ],
    "surfaces": [
      {
        "id": "surface_chat",
        "name": "Support Chat",
        "type": "chat",
        "config": {},
        "routes": [{ "capabilityId": "cap_support" }]
      }
    ],
    "schedules": [
      {
        "id": "weekly-digest",
        "capabilityId": "cap_weekly_digest",
        "triggerType": "cron",
        "cron": "0 9 * * MON",
        "timezone": "UTC",
        "enabled": true
      }
    ]
  }
}

Add eval suites

Use the optional top-level productObject.evals[] array to include eval suites in a product. Each suite targets a capability through capabilityId. Importing the FPO creates the suite, its graders, and its example cases with the capability’s flow or agent.

The following fields define an eval suite in an FPO:

Use the following structure to add an eval suite:

{
  "productObject": {
    "capabilities": [
      {
        "id": "cap_support",
        "name": "Support Agent",
        "description": "Answer user questions.",
        "agent": {
          "name": "Support Agent",
          "description": "Answer user questions.",
          "config": { "model": "claude-sonnet-5" }
        }
      }
    ],
    "evals": [
      {
        "id": "eval_support_basics",
        "name": "Support basics",
        "capabilityId": "cap_support",
        "graders": [
          {
            "kind": "ai",
            "criteria": "The response directly addresses what the user asked, without dodging or answering a different question."
          }
        ],
        "cases": [
          {
            "name": "Refund policy question",
            "input": {
              "messages": [{ "role": "user", "content": "What is your refund policy?" }]
            },
            "expected": { "facts": ["Refunds are available within 30 days"] },
            "enabled": true
          }
        ]
      }
    ]
  }
}

For grader and case concepts, see What are Evals?. Use Managing eval suites to edit imported suites in the dashboard.

Add skills

Use the optional top-level productObject.skills[] array to include agent skills in a product. A skill is a loadable context bundle with a markdown body and optional capabilities that it activates when loaded. Importing the FPO publishes each skill and binds it to the agent-backed capabilities listed in bindTo.

The following fields define a skill in an FPO:

Do not declare mcpServers in a skill’s capabilities. The validator rejects the key with an explicit error. Bind MCP tools with a saved tool ID or an inline tool.

Use the following structure to add a skill:

{
  "productObject": {
    "capabilities": [
      {
        "id": "cap_support",
        "name": "Support Agent",
        "description": "Answer user questions.",
        "agent": {
          "name": "Support Agent",
          "description": "Answer user questions.",
          "config": { "model": "claude-sonnet-5" }
        }
      }
    ],
    "skills": [
      {
        "id": "skill_refund_policy",
        "name": "Refund policy",
        "slug": "refund-policy",
        "description": "Load when the user asks about refunds, returns, or exchanges.",
        "content": "# Refund policy\n\nRefunds are available within 30 days of purchase. Always confirm the order number before promising a refund.",
        "bindTo": ["cap_support"]
      }
    ]
  }
}

Pin a skill version

Each bindTo entry is either an FPO capability ID or an object with capability and version. A capability ID binds the skill so that the agent follows the skill’s published version. An object pins the binding to the skill version with that version number:

"bindTo": ["cap_support", { "capability": "cap_escalations", "version": 2 }]

Importing the FPO publishes the skill content as a new version, so an agent that follows the published version starts using the new content. A pinned agent keeps the version it names until you change the pin. If the skill has no version with that number, product ensure reports the skill as failed and doesn’t write that binding. Pulling a product returns each pinned binding in the object form.

Validate a template

Validate a template before you share it. The runtype CLI validates locally without an API call. The API endpoint is POST /v1/public/products/validate-template.

Save the example template as customer-support-fpo-template.json, then validate it with one of the following samples.

runtype validate-product ./customer-support-fpo-template.json --template --json

The endpoint returns 400 with the code INVALID_JSON when the request body isn’t valid JSON. Otherwise, it returns the following fields:

A variable without a default leaves valid set to true. It sets defaultsSufficient to false and adds a MISSING_TEMPLATE_VARIABLE entry to defaultsValidation.errors. The importer supplies that value during import.

The following table lists the template-specific issue codes:

Share a template

To let other people import your template, follow these steps:

1. Host the template JSON file at a public HTTPS URL, such as a raw GitHub file URL.
2. URL-encode the file URL.
3. Share the import link https://use.runtype.com/now?from=ENCODED_TEMPLATE_URL. The link opens the dashboard import page with a preview of the template.
4. Optional: Add a Deploy to Runtype button to your repository. For the Markdown snippet, see Create a repository button.

Replace ENCODED_TEMPLATE_URL with the URL-encoded address of your template file.

Create a product from a template

To create a product from a template with the API, follow these steps:

1. Preview the template with POST /v1/quick-start/imports/preview. Send the template as a hosted file with source.kind: "url" or inline with source.kind: "json".
2. Collect values for the variables that the preview response lists without defaults.
3. Create the product with POST /v1/quick-start/create. Send the values in variables, with the importToken from the preview response.

An API key must hold a scope for everything that the template creates, such as SECRETS:WRITE for a template that declares secrets. A Test key can’t hold SECRETS:WRITE, so it can’t create a template product that declares secrets. For the full scope list, see Required API key scopes in the importing guide, which also has request and response examples.

Next steps

Continue with these guides:

• Quickstart: Make your first call to the Runtype API.
• Agent Skills: Bind loadable context bundles to agents.