Skip to content
Canopy

Replace the tenant's consent for an install

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", "inferences": [ "example" ], "policies": [ { "allow": true, "items": [ { "arg": "example", "effect": "allow", "op": "is", "operand": { "value": "example" } } ], "posture": "permissive", "project": [ "example" ], "tool": "example" } ] }'

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

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. The consented presets are a set with a default a dial that names none runs on; a config written before the set existed consents to its default alone. 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

The default preset: what a session runs on when its dial names none.

string
inferences

Every preset a session may name, the default among them.

Array<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. The install reads it with the presets it may open sessions on.

object
inferences
Array<object> | null

A preset the install may name on dial, as the install reads it: what it runs, never where its secret is.

object
compact_at
required
integer format: int64
default
required

Whether a dial that names no preset runs on this one.

boolean
id
required
string
model
required
string
name
required
string
provider
required

Which kind of provider, without where it is or what it dials with.

string
Allowed values: simulated openrouter
install
One of:
null
tenant
required

What the tenant lands at consent. The consented presets are a set with a default a dial that names none runs on; a config written before the set existed consents to its default alone. 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

The default preset: what a session runs on when its dial names none.

string
inferences

Every preset a session may name, the default among them.

Array<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
{
  "inferences": [
    {
      "provider": "simulated"
    }
  ],
  "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.