Update a plugin

PATCH https://runix.chat/api/v1/armada/plugins/{install_id}

Change a plugin's settings, replace its secrets, turn it off or on, or change where it shows and which of its tools the agent may use.

Settings are saved whole: a setting not given takes its default. A change its process must see restarts it, and lifts a failure.

Guests and bots cannot use this endpoint.

Changes: New in Zulip 13.0 (feature level ZF-0be29a).

Usage examples

curl -sSX PATCH https://runix.chat/api/v1/armada/plugins/1 \
    -u EMAIL_ADDRESS:API_KEY \
    --data-urlencode 'settings={"manage_prefix": "nlscale-"}' \
    --data-urlencode 'secrets={"prime_api_key": "pit_0123456789abcdef"}' \
    --data-urlencode disabled=false \
    --data-urlencode 'widget_defaults={"gpus": {"nav": "offered"}}' \
    --data-urlencode 'disabled_tools=["pod_create"]'

Parameters

Response

Return values

• plugin: object

  A plugin installed in the organization, as a member sees it. Its secrets are never included.

  • id: integer

    The ID of the install.

  • plugin: string

    The plugin's ID, from its manifest.

  • name: string

    The plugin's name, which its bot is named after.

  • version: string

    The plugin's version at the pinned commit.

  • source_kind: string

    Where its code comes from: a repository on GitHub, a repository on this server (the team's plugins repository), or nowhere here, for a plugin its author runs as a service.

  • source: string

    For github, its repository, as github.com/<owner>/<repository>; for remote, its service's address; otherwise empty.

  • source_repository_id: integer | null

    For local, the ID of this server's repository it comes from.

  • source_path: string

    Its directory in its repository, such as plugins/eval-queue, or empty for the repository's root.

  • sha: string

    The commit it is pinned at; empty for remote.

  • manifest: object

    The plugin's manifest at that commit.

  • state: string

    Waiting while a required setting or secret is missing; starting until its process answers; running; failed after five failures in a row; removed for a week, while the removal can be undone; a draft while the agent makes it, seen only by the person it is made for.

  • detail: string

    While waiting, the required settings and secrets that are missing; when failed, the last lines its process wrote.

  • bot_user_id: integer

    The ID of the plugin's own bot.

  • installed_by: integer | null

    The ID of the user it was installed for, by hand or by the agent.

  • made_by: integer | null

    The ID of the user who asked the agent to make it, or null for a plugin from the store.

  • made_by_run_id: integer | null

    The ID of the agent run that made it.

  • made_in_stream_id: integer | null

    The ID of the channel where it was asked for.

  • made_in_topic: string | null

    The topic where it was asked for.

  • made_in_message_id: integer | null

    The ID of the message that asked for it.

  • settings: object

    Its settings, whole, as its manifest's form describes them.

  • secrets: (object)[]

    The secrets its manifest asks for, and whether each is set.

    • name: string

      The secret's name in the manifest.

    • title: string

      What the manifest calls it.

    • required: boolean

      Whether the plugin waits until it is set.

    • set: boolean

      Whether it is set.

    • hint: string

      The last four characters of a secret of 16 characters or more; otherwise empty.

    • set_by: integer | null

      The ID of the user who set it.

    • date_set: integer | null

      When it was set, as a UNIX timestamp in UTC seconds.

  • links: (object)[]

    Where it is linked.

    • id: integer

      The ID of the link.

    • kind: string

      The kind of link, as the manifest names it.

    • value: string

      The value linked, such as a project.

    • stream_id: integer

      The ID of the channel.

    • topic: string | null

      The topic, or null for the whole channel.

  • disabled: boolean

    Whether it is turned off.

  • widget_defaults: object

    The team's default for each of its widgets, by the widget's key. A person may still show, hide or move a widget for themselves.

    • One widget's default.

      • nav: string

        Shown in everyone's nav, offered in its "+" menu, or not in the nav.

      • column: boolean

        Whether its list shows in the column of linked places.

  • disabled_tools: (string)[]

    Its tools the agent may not use.

  • date_installed: integer

    When it was installed, as a UNIX timestamp in UTC seconds.

  • date_removed: integer | null

    When it was removed, or null.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "msg": "",
    "plugin": {
        "bot_user_id": 31,
        "date_installed": 1760605200,
        "date_removed": null,
        "detail": "",
        "disabled": false,
        "disabled_tools": [],
        "id": 1,
        "installed_by": 11,
        "links": [
            {
                "id": 3,
                "kind": "pool",
                "stream_id": 7,
                "topic": "lr-sweep",
                "value": "nlscale-a"
            }
        ],
        "made_by": null,
        "made_by_run_id": null,
        "made_in_message_id": null,
        "made_in_stream_id": null,
        "made_in_topic": null,
        "manifest": {
            "description": "Free GPUs, and the jobs on them.",
            "glyph": "gpu",
            "id": "gpus",
            "name": "GPUs",
            "provides": {},
            "requires": {
                "armada": ">=1"
            },
            "run": {
                "command": [
                    "uv",
                    "run",
                    "armada-gpus"
                ]
            },
            "version": "0.1.0"
        },
        "name": "GPUs",
        "plugin": "gpus",
        "secrets": [
            {
                "date_set": 1760605200,
                "hint": "cdef",
                "name": "prime_api_key",
                "required": false,
                "set": true,
                "set_by": 11,
                "title": "Prime Intellect API key"
            }
        ],
        "settings": {
            "manage_prefix": "nlscale-"
        },
        "sha": "4e1d2c3b4a5968778695a4b3c2d1e0f9a8b7c6d5",
        "source": "github.com/plugyawn/armada-gpus",
        "source_kind": "github",
        "source_path": "",
        "source_repository_id": null,
        "state": "starting",
        "version": "0.1.0",
        "widget_defaults": {
            "gpus": {
                "column": true,
                "nav": "shown"
            }
        }
    },
    "result": "success"
}