Skip to content
Canopy

Replace the tenant's consent. Open sessions keep their landed config; sessions opened afterward use the updated consent.

PUT
/installs/{id}
curl --request PUT \
  --url https://api.canopyhq.dev/installs/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "extra_tools": [ { "connection": "example", "tool": "example" } ], "inference": "example", "policies": [ { "allow": true, "items": [ { "arg": "example", "effect": "allow", "op": "is", "operand": { "value": "example" } } ], "posture": "permissive", "project": [ "example" ], "tool": "example" } ] }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required

Opaque; never the key, never anything the vendor chose.

string

The install whose consent changes.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

What the tenant lands at consent. Inference must be selected; an empty policy list allows every tool and an empty extra-tools list adds nothing. The policies name tools as the model sees them and compile in policy, against the surface the resolved connections give, which is not this type’s to know.

object
extra_tools
Array<object>

A tool the tenant brings that the vendor did not state: a pre-registered remote, such as an MCP server the tenant already links to.

object
connection
required
string
tool
required

The name by which an MCP server identifies and invokes a tool.

string
inference
required
string
policies
Array<object>

The tenant’s rules for one tool, named by the name the model sees.

object
allow

The tool enable. Off, nothing else here matters.

boolean
items
Array<object>

One condition: <allow|deny> if <arg> <op> <operand>.

object
arg
required
string
effect
required
string
Allowed values: allow deny
op
required
string
Allowed values: is is_not in not_in lt gt
operand
required
One of:
object
value
required
posture

What a tool’s allow items do: nothing under Permissive, where only deny items bind; bind under Restrictive, where a conditioned arg must satisfy one of them.

string
Allowed values: permissive restrictive
project

Args projected for evidence alone, conditioned or not.

Array<string>
tool
required
string

Responses

Section titled “Responses”

200

Section titled “200”

The updated document. The vendor config is unchanged. Open sessions keep the config they landed at open; sessions opened after the change use the new config.

Media typeapplication/json

The composed document served to an install or the console.

object
install
One of:
null
tenant
required

What the tenant lands at consent. Inference must be selected; an empty policy list allows every tool and an empty extra-tools list adds nothing. The policies name tools as the model sees them and compile in policy, against the surface the resolved connections give, which is not this type’s to know.

object
extra_tools
Array<object>

A tool the tenant brings that the vendor did not state: a pre-registered remote, such as an MCP server the tenant already links to.

object
connection
required
string
tool
required

The name by which an MCP server identifies and invokes a tool.

string
inference
required
string
policies
Array<object>

The tenant’s rules for one tool, named by the name the model sees.

object
allow

The tool enable. Off, nothing else here matters.

boolean
items
Array<object>

One condition: <allow|deny> if <arg> <op> <operand>.

object
arg
required
string
effect
required
string
Allowed values: allow deny
op
required
string
Allowed values: is is_not in not_in lt gt
operand
required
One of:
object
value
required
posture

What a tool’s allow items do: nothing under Permissive, where only deny items bind; bind under Restrictive, where a conditioned arg must satisfy one of them.

string
Allowed values: permissive restrictive
project

Args projected for evidence alone, conditioned or not.

Array<string>
tool
required
string
vendor
required

A vendor document with its wire version beside the vendor fields.

object
description
required
string
name
required
string
tools
required
Array<object>
object
description
required
string
input_schema
required
name
required
string
output_schema
required
result_limit
One of:
null
timeout
string | null
appdoc
required

The vendor document version, read through the same shape chain as storage.

integer format: int32
Example
{
  "tenant": {
    "policies": [
      {
        "items": [
          {
            "effect": "allow",
            "op": "is"
          }
        ],
        "posture": "permissive"
      }
    ]
  }
}

400

Section titled “400”

Parse errors identify the field and reason when available. The tenant config may not fit the vendor’s or resolve under the tenant. An invalid policy returns its reason in the error body.

401

Section titled “401”

No console token, or one that did not verify.

403

Section titled “403”

Only an owner of the tenant may change consent.

404

Section titled “404”

The tenant has no such install.