> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentarea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Bundle

> Install a canonical bundle: MCP instances, skills, agents and automations.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/bundles/install
openapi: 3.1.0
info:
  description: >-
    Modular and extensible framework for building AI agents. This API requires
    JWT Bearer token authentication for most endpoints. Include your JWT token
    in the Authorization header. Public endpoints include /, /health, /docs,
    /redoc, and /openapi.json.
  title: AgentArea API
  version: 0.1.0
servers: []
security:
  - bearer: []
paths:
  /v1/bundles/install:
    post:
      tags:
        - v1
        - protected
        - bundles
      summary: Install Bundle
      description: >-
        Install a canonical bundle: MCP instances, skills, agents and
        automations.
      operationId: install_bundle_v1_bundles_install_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstallRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstallResult'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - HTTPBearer: []
components:
  schemas:
    InstallRequest:
      description: Install a (previously analyzed, possibly edited) canonical bundle.
      properties:
        bundle:
          $ref: '#/components/schemas/Bundle-Input'
        setup_values:
          additionalProperties: true
          description: Values for the bundle's setup fields, keyed by setup field key.
          title: Setup Values
          type: object
      required:
        - bundle
      title: InstallRequest
      type: object
    InstallResult:
      additionalProperties: false
      properties:
        bundle_name:
          title: Bundle Name
          type: string
        entities:
          items:
            $ref: '#/components/schemas/InstalledEntity'
          title: Entities
          type: array
        installed_bundle_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Installed Bundle Id
      required:
        - bundle_name
      title: InstallResult
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    Bundle-Input:
      additionalProperties: false
      description: The canonical, fully-inlined package object.
      properties:
        agents:
          items:
            $ref: '#/components/schemas/BundleAgent'
          title: Agents
          type: array
        automations:
          items:
            $ref: '#/components/schemas/BundleAutomation'
          title: Automations
          type: array
        channels:
          items:
            $ref: '#/components/schemas/BundleChannel'
          title: Channels
          type: array
        description:
          default: ''
          title: Description
          type: string
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Display Name
        mcps:
          items:
            $ref: '#/components/schemas/BundleMcp'
          title: Mcps
          type: array
        metadata:
          $ref: '#/components/schemas/BundleMetadata'
        name:
          description: Stable package identifier (idempotency key).
          minLength: 1
          title: Name
          type: string
        policies:
          items:
            $ref: '#/components/schemas/BundlePolicy'
          title: Policies
          type: array
        schema_version:
          default: 0.1.0
          title: Schema Version
          type: string
        setup:
          items:
            $ref: '#/components/schemas/SetupField'
          title: Setup
          type: array
        skills:
          items:
            $ref: '#/components/schemas/BundleSkill'
          title: Skills
          type: array
      required:
        - name
      title: Bundle
      type: object
    InstalledEntity:
      additionalProperties: false
      properties:
        action:
          $ref: '#/components/schemas/InstallAction'
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
        id:
          anyOf:
            - type: string
            - type: 'null'
          description: Created/reused entity id, when applicable.
          title: Id
        key:
          title: Key
          type: string
        kind:
          $ref: '#/components/schemas/EntityKind'
        name:
          title: Name
          type: string
      required:
        - kind
        - key
        - name
        - action
      title: InstalledEntity
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    BundleAgent:
      additionalProperties: false
      description: An agent to create for the package.
      properties:
        instruction:
          default: ''
          maxLength: 20000
          title: Instruction
          type: string
        key:
          minLength: 1
          title: Key
          type: string
        mcps:
          description: BundleMcp keys to attach as tools.
          items:
            type: string
          title: Mcps
          type: array
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        name:
          minLength: 1
          title: Name
          type: string
        skills:
          description: BundleSkill keys to attach.
          items:
            type: string
          title: Skills
          type: array
      required:
        - key
        - name
      title: BundleAgent
      type: object
    BundleAutomation:
      additionalProperties: false
      description: >-
        A scheduled run of one of the package's agents (maps to a CronTrigger).


        Automations are imported disabled by default; the user enables them
        after

        verifying connections, mirroring the Zapier/Make "connect then activate"

        flow.
      properties:
        agent:
          description: BundleAgent key to invoke.
          minLength: 1
          title: Agent
          type: string
        cron:
          description: 5- or 6-field cron expression.
          minLength: 1
          title: Cron
          type: string
        enabled:
          default: false
          title: Enabled
          type: boolean
        key:
          minLength: 1
          title: Key
          type: string
        prompt:
          description: Task query passed to the agent on each run.
          minLength: 1
          title: Prompt
          type: string
        timezone:
          default: UTC
          title: Timezone
          type: string
        type:
          const: cron
          default: cron
          title: Type
          type: string
      required:
        - key
        - cron
        - agent
        - prompt
      title: BundleAutomation
      type: object
    BundleChannel:
      additionalProperties: false
      description: >-
        A messaging channel that lets an agent receive and reply to messages.


        Installs as an inbound trigger (e.g. a Telegram webhook): a message to
        the

        bot becomes a task for ``agent``, and the reply is delivered back on the
        same

        channel. Credentials (a bot token) enter via ``bindings`` →
        ``${setup.x}``,

        exactly like an MCP's secret bindings, so the token is never inlined.
      properties:
        agent:
          description: BundleAgent key that handles inbound messages.
          minLength: 1
          title: Agent
          type: string
        bindings:
          additionalProperties:
            type: string
          description: >-
            Maps a credential the channel needs to a ${setup.x} reference, e.g.
            {'bot_token': '${setup.telegram_bot_token}'}.
          title: Bindings
          type: object
        enabled:
          default: false
          title: Enabled
          type: boolean
        key:
          minLength: 1
          title: Key
          type: string
        name:
          description: Display name for the created channel trigger.
          minLength: 1
          title: Name
          type: string
        prompt:
          default: 'Handle the incoming message: {{ message_text }}'
          description: Task query template used for each inbound message.
          minLength: 1
          title: Prompt
          type: string
        type:
          const: telegram
          default: telegram
          description: Channel provider. Only Telegram in v0.1.0.
          title: Type
          type: string
      required:
        - key
        - name
        - agent
      title: BundleChannel
      type: object
    BundleMcp:
      additionalProperties: false
      description: An MCP server to provision for the package.
      properties:
        bindings:
          additionalProperties:
            type: string
          description: >-
            Maps an env var / header name the server needs to a ${setup.x}
            reference, e.g. {'GITHUB_TOKEN': '${setup.github_token}'}.
          title: Bindings
          type: object
        json_spec:
          additionalProperties: true
          description: Native MCP runtime spec. Must include 'type' (command|docker|url).
          title: Json Spec
          type: object
        key:
          description: In-package reference key (agents point at this).
          minLength: 1
          title: Key
          type: string
        name:
          description: Instance display name created in the workspace.
          minLength: 1
          title: Name
          type: string
      required:
        - key
        - name
        - json_spec
      title: BundleMcp
      type: object
    BundleMetadata:
      additionalProperties: false
      description: Marketplace presentation metadata (parity with plugin/app listings).
      properties:
        capabilities:
          description: e.g. ["interactive", "write"].
          items:
            type: string
          title: Capabilities
          type: array
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
        developer:
          anyOf:
            - type: string
            - type: 'null'
          description: Publisher name.
          title: Developer
        icon:
          anyOf:
            - type: string
            - type: 'null'
          description: Icon URL or asset reference.
          title: Icon
        privacy_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Privacy Url
        terms_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Terms Url
        website:
          anyOf:
            - type: string
            - type: 'null'
          title: Website
      title: BundleMetadata
      type: object
    BundlePolicy:
      additionalProperties: false
      description: >-
        A governance rule the package installs (maps to a PolicyRule).


        Portable like everything else: ``subject`` is the literal "workspace" or
        a

        BundleAgent ``key`` (never a DB id); the installer resolves it to a real

        subject id. ``target``/``effect``/``params`` mirror the unified
        governance

        rule model, so this is "our policy format" — not a new one.
      properties:
        condition:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional CEL condition.
          title: Condition
        effect:
          enum:
            - allow
            - deny
            - cap
            - approval
            - safety
          title: Effect
          type: string
        enabled:
          default: true
          title: Enabled
          type: boolean
        key:
          minLength: 1
          title: Key
          type: string
        message:
          anyOf:
            - type: string
            - type: 'null'
          description: Human-readable reason.
          title: Message
        params:
          additionalProperties: true
          description: Effect-specific params, e.g. {amount_usd, period} for cap.
          title: Params
          type: object
        priority:
          default: 0
          title: Priority
          type: integer
        subject:
          default: workspace
          description: '"workspace" or a BundleAgent key the rule binds to.'
          title: Subject
          type: string
        target:
          description: Selector, e.g. "tool:send_email", "spend", "content", "*".
          minLength: 1
          title: Target
          type: string
      required:
        - key
        - target
        - effect
      title: BundlePolicy
      type: object
    SetupField:
      additionalProperties: false
      description: |-
        A single value the user must provide before the package can run.

        This is the generalized analogue of a Claude plugin ``userConfig`` entry
        and mirrors the existing MCP ``env_schema`` (KeyValueInput) shape.
      properties:
        default:
          anyOf:
            - {}
            - type: 'null'
          title: Default
        help:
          anyOf:
            - type: string
            - type: 'null'
          description: Help text shown beneath the field.
          title: Help
        key:
          description: Stable identifier referenced via ${setup.key}.
          minLength: 1
          title: Key
          type: string
        label:
          description: Human-readable label rendered in the form.
          minLength: 1
          title: Label
          type: string
        max:
          anyOf:
            - type: number
            - type: 'null'
          description: Upper bound for type='number'.
          title: Max
        min:
          anyOf:
            - type: number
            - type: 'null'
          description: Lower bound for type='number'.
          title: Min
        options:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: Choices for type='select'.
          title: Options
        required:
          default: false
          title: Required
          type: boolean
        type:
          $ref: '#/components/schemas/SetupFieldType'
          default: string
      required:
        - key
        - label
      title: SetupField
      type: object
    BundleSkill:
      additionalProperties: false
      description: A skill to create for the package.
      properties:
        content:
          anyOf:
            - type: string
            - type: 'null'
          description: SKILL.md markdown for source_type=content.
          title: Content
        key:
          minLength: 1
          title: Key
          type: string
        name:
          minLength: 1
          title: Name
          type: string
        source_type:
          default: content
          enum:
            - content
            - github
          title: Source Type
          type: string
        source_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Repo URL for source_type=github.
          title: Source Url
      required:
        - key
        - name
      title: BundleSkill
      type: object
    InstallAction:
      enum:
        - created
        - reused
        - skipped
      title: InstallAction
      type: string
    EntityKind:
      enum:
        - mcp
        - skill
        - agent
        - channel
        - automation
        - policy
      title: EntityKind
      type: string
    SetupFieldType:
      description: Input widget / storage hint for a setup field.
      enum:
        - secret
        - string
        - number
        - boolean
        - select
      title: SetupFieldType
      type: string
  securitySchemes:
    bearer:
      bearerFormat: JWT
      description: JWT Bearer token for authentication
      scheme: bearer
      type: http
    HTTPBearer:
      scheme: bearer
      type: http

````