> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Export agent for runtime

GET https://api.runtype.com/v1/agents/{id}/export-runtime

Export a fully-resolved, self-contained agent definition that the @runtypelabs/runtime package can consume directly at boot. Capabilities, flows, and nested sub-agents are inlined recursively (up to 3 levels). Skills bound to the agent are snapshotted into `skills`, each with the skill version it resolved to, and the runtime loads them with no host wiring. MCP credential values and external-agent auth credentials are replaced with secret-name references. A configured `decision_judge` tool carries its published question set (questions, model, version, input mapping and current calibration) at `config.questionSet`, resolved once at export so a self-hosted runtime never looks the question set up; a question set that is missing, unpublished, owned by another account, or pinned to an unpublished version is reported in `warnings` with reason `question_set_unresolved` instead of failing the export. An export that would carry a literal credential typed into a tool config or MCP server is refused with `422` and code `raw_credential_in_export`. Requires the `RUNTIME:EXPORT` scope and an Enterprise plan (the `byoc` entitlement); an unentitled account receives `403` with code `BYOC_PLAN_REQUIRED` in every environment.

The response carries `hostDependencies`: the runtime seams the exported artifact needs a host to wire before it can run everything it describes. A durable-class step (`wait-until` or `crawl`) anywhere in the agent's executable closure declares a `durable-pause-host` dependency; a detached-capable dynamic subagent pool or a detached inline subagent tool declares a `background-run-coordinator` dependency. The array is empty when nothing needs wiring.

The response also carries `warnings`: each referenced sub-agent or flow the export could not embed, with the reason (`not_found`, `claude_managed_unsupported`, `max_depth_exceeded` for nesting deeper than 3 levels, `invalid_flow_config`, `unresolved_tool_ref`, or `unsupported_mcp_auth`), and each configured decision tool whose question set could not be resolved (`question_set_unresolved`). The export still returns `200` and leaves the referencing capability or tool out of the artifact; a decision tool stays in, without `config.questionSet`. The array is empty when every child was embedded.

Pass at most one release selector. `versionId` exports that published version; `alias` exports the version a release alias (for example `staging`, `live` or `pr-42`) currently points at, resolved exactly as the execution selector `agent: { agentId, alias }` resolves it. With neither, the export follows the agent's default target: the version its `live` alias names when the org runs on release aliases, otherwise the agent's current definition. A version-backed export carries `release` with the resolved `versionId`, plus `alias` and `aliasRevision` when an alias selected it. An unknown version or alias, or an archived or expired alias, answers `404`.

Reference: https://docs.runtype.com/api-reference/runtype-api/agents/export-agent-for-runtime

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Path parameters

- `id` (string, required)

### Query parameters

- `versionId` (string, optional) — Export this published agent version. Mutually exclusive with `alias`.
- `alias` (string, optional) — Export the version this release alias currently points at. Mutually exclusive with `versionId`.
- `format` (enum, optional) — `json` (the default) returns the exported definition. `bundle` returns a vendorable `application/zip` with `agent.json` (the same definition), `runtime/` (the prebuilt `@runtypelabs/runtime` ESM package for the platform runtime version, installable as `file:./runtime`), `manifest.json`, and `LICENSE` (the runtime ships under FSL-1.1-ALv2).
  - Allowed values: `json`, `bundle`

## Response

### 200

Exported agent definition, or with `format=bundle` a zip archive. Two bundle exports of the same version are byte-identical. The bundle `manifest.json` records the runtime version and source commit, the agent `versionId`/alias, the entrypoints, `hostDependencies`, `warnings`, and `contentHash`: sha256 over the `sha256sum` listing (`<sha256> <path>` lines sorted by path) of every file except `manifest.json`. The same hash is sent in the `X-Runtype-Bundle-Content-Hash` header.

- `agentType` (enum, required)
  - Allowed values: `runtype`, `external`
- `config` (map from string to any, required)
- `description` (string, required, nullable)
- `hostDependencies` (list of RuntimeHostDependency, required)
- `id` (string, required)
- `name` (string, required)
- `warnings` (list of RuntimeExportWarning, required) — Referenced sub-agents, flows and question sets the export could not embed, each with the reason. The export still returns `200`; a tool or capability that names a dropped child is absent from the artifact. Empty when every child was embedded.
- `capabilities` (list of map from string to any, optional)
- `externalConfig` (map from string to any, optional)
- `release` (V1AgentsIdExportRuntimeGetResponsesContentApplicationJsonSchemaRelease, optional) — The published version this export contains. `alias` and `aliasRevision` are present when a release alias selected it. Absent when the export read the agent's current definition.
- `skills` (list of RuntimeExportedSkill, optional) — Skills bound to the agent, snapshotted with the skill version each resolved to. `executeAgent` loads them with no host wiring. Absent when the agent has no bound skills.

## Errors

### 400 Bad Request Error

Invalid agent ID, or both `versionId` and `alias` were supplied

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 401 Unauthorized Error

Unauthorized

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 403 Forbidden Error

Insufficient permissions, or the account plan does not include runtime extraction (code `BYOC_PLAN_REQUIRED`, Enterprise plans only)

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 404 Not Found Error

Agent not found, or the selected version or alias does not exist, is archived, or has expired

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 422 Unprocessable Entity Error

The agent type cannot export a selected version (code `selector_unsupported_agent_type`), or the export would carry a literal credential (code `raw_credential_in_export`; `details` names each tool or MCP server field without echoing the value)

- `error` (string, required)
- `code` (string, optional) — Stable refusal code: `raw_credential_in_export` or `selector_unsupported_agent_type`.
- `details` (list of RuntimeExportErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 500 Internal Server Error

Internal server error

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 503 Service Unavailable Error

With `format=bundle`: the prebuilt runtime artifact for this platform version is not available (code `RUNTIME_ARTIFACT_UNAVAILABLE`, with a `reason` such as `artifact_missing`)

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

## Types

### RuntimeHostDependency

- RuntimeHostDependency0
- RuntimeHostDependency1
- RuntimeHostDependency2

### RuntimeExportWarning

- `childKind` (enum, required) — What kind of child the warning is about. `question_set` names the question set id in `childId`.
  - Allowed values: `agent`, `flow`, `question_set`
- `code` (enum, required) — `child_dropped`: the child is absent from the artifact. `child_stubbed`: the artifact carries a stub the runtime cannot run, or a configured decision tool without its question set.
  - Allowed values: `child_dropped`, `child_stubbed`
- `message` (string, required)
- `reason` (enum, required) — Why the export could not embed the child. `question_set_unresolved`: a configured `decision_judge` tool references a question set that is missing, unpublished, owned by another account, or pinned to a version that is not published; the tool stays in the artifact without `config.questionSet`, so a self-hosted runtime in own-key mode refuses its calls (platform and hybrid modes resolve it through Runtype).
  - Allowed values: `not_found`, `claude_managed_unsupported`, `max_depth_exceeded`, `invalid_flow_config`, `unresolved_tool_ref`, `unsupported_mcp_auth`, `question_set_unresolved`
- `childId` (string, optional)
- `parentId` (string, optional) — The agent whose capability referenced the child, when the child came from one.
- `toolName` (string, optional) — The capability or tool name that referenced the child.

### V1AgentsIdExportRuntimeGetResponsesContentApplicationJsonSchemaRelease

The published version this export contains. `alias` and `aliasRevision` are present when a release alias selected it. Absent when the export read the agent's current definition.

- `versionId` (string, required)
- `alias` (string, optional)
- `aliasRevision` (integer, optional)

### RuntimeExportedSkill

- `approvalDelta` (list of string, required)
- `body` (string, required)
- `description` (string, required)
- `resolvedTools` (list of map from string to any, required)
- `slug` (string, required) — Skill slug; the agent loads it as `skill:<slug>`.
- `skillId` (string, optional)
- `skillVersionId` (string, optional) — The skill version this snapshot was resolved from.

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### RuntimeExportErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### RuntimeHostDependency0

- `interface` (string, required)
- `kind` (enum, required)
  - Allowed values: `durable-pause-host`
- `reason` (string, required)
- `steps` (list of RuntimeHostDependencyOneOf0StepsItems, required)

### RuntimeHostDependency1

- `agents` (list of RuntimeHostDependencyOneOf1AgentsItems, required)
- `interface` (string, required)
- `kind` (enum, required)
  - Allowed values: `background-run-coordinator`
- `reason` (string, required)

### RuntimeHostDependency2

Forward-compatibility member: a host dependency whose `kind` this API version does not define. Render `interface` and `reason`; kind-specific evidence arrives as additional properties.

- `interface` (string, required)
- `kind` (string, required)
- `reason` (string, required)

### RuntimeHostDependencyOneOf0StepsItems

- `ownerKind` (enum, required)
  - Allowed values: `flow`, `agent`, `capability`, `inline-tool`
- `stepId` (string, required)
- `stepType` (string, required)
- `ownerId` (string, optional)
- `ownerName` (string, optional)

### RuntimeHostDependencyOneOf1AgentsItems

- `ownerKind` (enum, required)
  - Allowed values: `flow`, `agent`, `capability`, `inline-tool`
- `ownerId` (string, optional)
- `ownerName` (string, optional)
- `stepId` (string, optional)

## Examples

**Response**

```json
{
  "agentType": "runtype",
  "config": {},
  "description": "string",
  "hostDependencies": [
    {
      "interface": "string",
      "kind": "durable-pause-host",
      "reason": "string",
      "steps": [
        {
          "ownerId": "string",
          "ownerKind": "flow",
          "ownerName": "string",
          "stepId": "string",
          "stepType": "string"
        }
      ]
    }
  ],
  "id": "string",
  "name": "string",
  "warnings": [
    {
      "childKind": "agent",
      "code": "child_dropped",
      "message": "string",
      "reason": "not_found",
      "childId": "string",
      "parentId": "string",
      "toolName": "string"
    }
  ],
  "capabilities": [
    {}
  ],
  "externalConfig": {},
  "release": {
    "versionId": "string",
    "alias": "string",
    "aliasRevision": 1
  },
  "skills": [
    {
      "approvalDelta": [
        "string"
      ],
      "body": "string",
      "description": "string",
      "resolvedTools": [
        {}
      ],
      "slug": "string",
      "skillId": "string",
      "skillVersionId": "string"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.runtype.com/v1/agents/id/export-runtime"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.runtype.com/v1/agents/id/export-runtime';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/agents/id/export-runtime"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/agents/id/export-runtime")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.runtype.com/v1/agents/id/export-runtime")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.runtype.com/v1/agents/id/export-runtime', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/agents/id/export-runtime");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/agents/id/export-runtime")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```