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

# Update an agent's catalog metadata. Owner-or-superuser only.



## OpenAPI

````yaml /api-reference/openapi.json put /api/agents/{id}
openapi: 3.1.0
info:
  title: Nasiko API
  description: >-
    HTTP API for the Nasiko OpenRuntime: agents, coding harnesses, TokenOps,
    routing, MCP, and secrets. Spec is generated from annotated routes; some
    surfaces are documented on the hand-written pages alongside this file.
  license:
    name: ''
  version: 0.1.0
servers:
  - url: https://free.app.nasiko.com
    description: Nasiko Cloud Free
  - url: https://{workspace}.app.nasiko.com
    description: Nasiko Cloud paid workspace
    variables:
      workspace:
        default: your-workspace
        description: >-
          Your workspace's subdomain, as shown in the connect command on the
          dashboard's Nasiko CLI page
security:
  - bearer_auth: []
tags:
  - name: secrets
    description: Encrypted per-user agent secrets
  - name: catalog
    description: >-
      Agent catalog: registration, discovery, versions, per-agent secrets, and
      source import
  - name: agents
    description: >-
      Agent lifecycle: deployments, LLM routing config, update/rollback,
      upload-and-deploy
  - name: orchestrator
    description: >-
      A2A dispatch: routing-engine/ReAct orchestrator and direct agent chat,
      plus routing stats
  - name: users
    description: >-
      User management: CRUD, roles, credentials, accessible agents
      (superuser-only)
  - name: usage
    description: Per-user token usage and cost reporting
  - name: observability
    description: Sessions, traces, spans, agent logs, and FinOps reporting
  - name: llm-router
    description: LLM routing presets, provider/model catalog, and tier→model registry
  - name: context-selection
    description: >-
      Per-user chat-history selection preferences: strategy, PACMS budget tier,
      the on/off switch, a dry-run preview, and settings-change history
  - name: coding-agents
    description: >-
      The progress local clients report while they bring in the caller's coding
      agents
  - name: settings
    description: >-
      Workspace-wide settings, including the Optimization tiers a user's PACMS
      budget level resolves against
  - name: mcp
    description: >-
      MCP gateway: agent-facing JSON-RPC tool calls, connector
      registration/upload/sharing, credentials & OAuth, and per-agent tool
      permissions
paths:
  /api/agents/{id}:
    put:
      tags:
        - catalog
      summary: Update an agent's catalog metadata. Owner-or-superuser only.
      operationId: update
      parameters:
        - name: id
          in: path
          description: Agent id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgent'
        required: true
      responses:
        '200':
          description: Updated agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '403':
          description: Caller cannot manage this agent
        '404':
          description: No agent with this id
components:
  schemas:
    UpdateAgent:
      type: object
      properties:
        activate_version:
          type: boolean
          description: |-
            `true` (the default) for a real deploy — the new version becomes
            active, archiving whatever was running before. `nasiko push` sets
            this `false`: it only makes an image available in the registry
            without deploying it, so it must not claim the new version is now
            active or archive the version that's genuinely still running.
        capabilities: {}
        compress_enabled:
          type:
            - boolean
            - 'null'
          description: Toggle payload compression for this agent. Omitted = leave as-is.
        description:
          type:
            - string
            - 'null'
        display_name:
          type:
            - string
            - 'null'
        documentation_url:
          type:
            - string
            - 'null'
        hitl_enabled:
          type:
            - boolean
            - 'null'
          description: |-
            Toggle human-in-the-loop approval for this coding agent.
            Omitted = leave as-is, so an ordinary metadata edit never flips it.
        icon_url:
          type:
            - string
            - 'null'
        image:
          type:
            - string
            - 'null'
        metadata: {}
        minimal_code_enabled:
          type:
            - boolean
            - 'null'
        parking_policy:
          type:
            - string
            - 'null'
          description: >-
            `auto` (the platform may park the agent when idle) or `resident`
            (always running).

            Omitted = leave as-is. A `parked` agent flipped to `resident` is
            woken by its next call and

            then stays up. A running `resident` agent flipped to `auto` is
            parked once idle; its workload

            becomes one that can be parked at its next deploy.
        skills:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Skill'
        status:
          type:
            - string
            - 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
        url:
          type:
            - string
            - 'null'
        version:
          type:
            - string
            - 'null'
        workload_kind:
          type:
            - string
            - 'null'
          description: >-
            Workload kind: `agent`, `mcp_connector`, or `acp_coding_agent`.
            Omitted =

            leave as-is (so an ordinary metadata edit never clears it); present
            =

            overwrite, which is how `nasiko deploy --coding-agent` promotes an

            already-registered agent to a coding agent.
    Agent:
      type: object
      required:
        - id
        - name
        - owner_id
        - version
        - protocol_version
        - preferred_transport
        - capabilities
        - security_schemes
        - default_input_modes
        - default_output_modes
        - skills
        - tags
        - metadata
        - status
        - minimal_code_enabled
        - created_at
        - updated_at
      properties:
        capabilities: {}
        compress_enabled:
          type: boolean
          description: >-
            Per-agent opt-in for compression on this agent's traffic: payload
            compression on its LLM calls, brevity, and session-history
            compression in direct chats. Off unless enabled.
        created_at:
          type: string
          format: date-time
        default_input_modes:
          type: array
          items:
            type: string
        default_output_modes:
          type: array
          items:
            type: string
        description:
          type:
            - string
            - 'null'
        display_name:
          type:
            - string
            - 'null'
        documentation_url:
          type:
            - string
            - 'null'
        hitl_enabled:
          type: boolean
          description: >-
            Whether this coding agent gates its tool use behind human approval.
            Off unless explicitly enabled; only meaningful for

            `workload_kind = acp_coding_agent`.
        icon_url:
          type:
            - string
            - 'null'
        id:
          type: string
          format: uuid
        image:
          type:
            - string
            - 'null'
        metadata: {}
        minimal_code_enabled:
          type: boolean
          description: >-
            Whether minimal-code guidance is injected into messages sent to this
            agent. Shown as a switch on the agent's **Settings** tab.
        name:
          type: string
        owner_id:
          type: string
          format: uuid
        preferred_transport:
          type: string
        protocol_version:
          type: string
        security_schemes: {}
        skills:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
        status:
          type: string
        tags:
          type: array
          items:
            type: string
        transport_path:
          type:
            - string
            - 'null'
          description: |-
            Path of the agent's advertised JSON-RPC transport (e.g. "/jsonrpc"),
            extracted from its AgentCard `supportedInterfaces` at deploy time.
            Clients chat via `{base}/api/agents/{id}{transport_path}`.
        updated_at:
          type: string
          format: date-time
        url:
          type:
            - string
            - 'null'
        version:
          type: string
        workload_kind:
          type: string
          description: >-
            Workload kind: `agent` (default), `mcp_connector`, or
            `acp_coding_agent`.

            Exposed so clients can tell a coding agent apart from a normal one
            (e.g.

            `nasiko chat` labels it, and `--coding-agent` asserts on it).
    Skill:
      type: object
      required:
        - id
        - name
        - description
      properties:
        description:
          type: string
        examples:
          type: array
          items: {}
        id:
          type: string
        name:
          type: string
        tags:
          type: array
          items:
            type: string
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Session JWT. After `nasiko auth login`, print it with `jq -r
        '.clusters[.active].token' ~/.nasiko/config.json`. API keys aren't
        supported.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.