---
title: "Analyze Bundle"
method: POST
path: "/v1/bundles/analyze"
tags: ["v1", "protected", "bundles"]
---

# Analyze Bundle

`POST /v1/bundles/analyze`

Parse and analyze a bundle source, returning a non-destructive preview.

## Request body

- AnalyzeRequest — Analyze a bundle into an import preview. Provide exactly one of ``source`` (pasted text) or ``source_url`` (a URL the server fetches behind the SSRF guard). ``source_url`` is what a landing-page deep-link (`/bundles/import?src=<url>`) uses for one-click installs.
  - `source` string, nullable — Raw bundle source text (YAML or JSON).
  - `source_url` string, nullable — URL to fetch raw bundle source from (YAML or JSON).

## Response `200`

Successful Response

- ImportPreview — What the wizard renders before the user commits to installing.
  - `bundle` BundleOutput, required — The canonical, fully-inlined package object.
    - `agents` BundleAgent[]
      - `instruction` string
      - `key` string, required
      - `mcps` string[] — BundleMcp keys to attach as tools.
      - `model` string, nullable
      - `name` string, required
      - `skills` string[] — BundleSkill keys to attach.
    - `automations` BundleAutomation[]
      - `agent` string, required — BundleAgent key to invoke.
      - `cron` string, required — 5- or 6-field cron expression.
      - `enabled` boolean
      - `key` string, required
      - `prompt` string, required — Task query passed to the agent on each run.
      - `timezone` string
      - `type` 'cron'
    - `channels` BundleChannel[]
      - `agent` string, required — BundleAgent key that handles inbound messages.
      - `bindings` object — Maps a credential the channel needs to a ${setup.x} reference, e.g. {'bot_token': '${setup.telegram_bot_token}'}.
      - `enabled` boolean
      - `key` string, required
      - `name` string, required — Display name for the created channel trigger.
      - `prompt` string — Task query template used for each inbound message.
      - `type` 'telegram' — Channel provider. Only Telegram in v0.1.0.
    - `description` string
    - `display_name` string, nullable
    - `mcps` BundleMcp[]
      - `bindings` object — Maps an env var / header name the server needs to a ${setup.x} reference, e.g. {'GITHUB_TOKEN': '${setup.github_token}'}.
      - `json_spec` object, required — Native MCP runtime spec. Must include 'type' (command|docker|url).
      - `key` string, required — In-package reference key (agents point at this).
      - `name` string, required — Instance display name created in the workspace.
    - `metadata` BundleMetadata — Marketplace presentation metadata (parity with plugin/app listings).
      - `capabilities` string[] — e.g. ["interactive", "write"].
      - `category` string, nullable
      - `developer` string, nullable — Publisher name.
      - `icon` string, nullable — Icon URL or asset reference.
      - `privacy_url` string, nullable
      - `terms_url` string, nullable
      - `website` string, nullable
    - `name` string, required — Stable package identifier (idempotency key).
    - `policies` BundlePolicy[]
      - `condition` string, nullable — Optional CEL condition.
      - `effect` 'allow' | 'deny' | 'cap' | 'approval' | 'safety', required
      - `enabled` boolean
      - `key` string, required
      - `message` string, nullable — Human-readable reason.
      - `params` object — Effect-specific params, e.g. {amount_usd, period} for cap.
      - `priority` integer
      - `subject` string — "workspace" or a BundleAgent key the rule binds to.
      - `target` string, required — Selector, e.g. "tool:send_email", "spend", "content", "*".
    - `schema_version` string
    - `setup` SetupField[]
      - `default` unknown
      - `help` string, nullable — Help text shown beneath the field.
      - `key` string, required — Stable identifier referenced via ${setup.key}.
      - `label` string, required — Human-readable label rendered in the form.
      - `max` number, nullable — Upper bound for type='number'.
      - `min` number, nullable — Lower bound for type='number'.
      - `options` string[], nullable — Choices for type='select'.
      - `required` boolean
      - `type` 'secret' | 'string' | 'number' | 'boolean' | 'select' — Input widget / storage hint for a setup field.
    - `skills` BundleSkill[]
      - `content` string, nullable — SKILL.md markdown for source_type=content.
      - `key` string, required
      - `name` string, required
      - `source_type` 'content' | 'github'
      - `source_url` string, nullable — Repo URL for source_type=github.
  - `entities` PreviewEntity[]
    - `detail` string, nullable
    - `key` string, required
    - `kind` 'mcp' | 'skill' | 'agent' | 'channel' | 'automation' | 'policy', required
    - `name` string, required
    - `status` 'will_create' | 'already_exists' | 'unsupported', required
  - `installable` boolean, required — True when there are no blocking issues (setup may still be required).
  - `issues` PreviewIssue[]
    - `entity_key` string, nullable
    - `message` string, required
    - `severity` 'block' | 'warn', required
  - `setup` SetupField[]
    - `default` unknown
    - `help` string, nullable — Help text shown beneath the field.
    - `key` string, required — Stable identifier referenced via ${setup.key}.
    - `label` string, required — Human-readable label rendered in the form.
    - `max` number, nullable — Upper bound for type='number'.
    - `min` number, nullable — Lower bound for type='number'.
    - `options` string[], nullable — Choices for type='select'.
    - `required` boolean
    - `type` 'secret' | 'string' | 'number' | 'boolean' | 'select' — Input widget / storage hint for a setup field.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/agentarea/apis/agentarea-api.md) · [All operations](https://skmtc.net/agentarea/apis/agentarea-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentarea/agentarea-api/versions/e3650e48373b/schema)