Read an install's app document

GET

/installs/{id}

const url = 'https://api.canopyhq.dev/installs/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.canopyhq.dev/installs/example \
  --header 'Authorization: Bearer <token>'

Authorizations

console_token

Parameters

Path Parameters

required

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

string

The install, as consent named it.

Responses

200

The document the install runs under.

application/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

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
string

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

required

string

Allowed values: is is_not in not_in lt gt

operand

required

One of:

object
object

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
string

null

A byte count written with an optional binary unit, such as 16KiB.

string

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"
      }
    ]
  }
}

401

No console token, or one that did not verify.

404

The tenant has no such install.