Skip to content
Canopy

A vendor holding an install key proposes a replacement document for it.

POST
/installs/{id}/proposals
curl --request POST \
  --url https://api.canopyhq.dev/installs/example/proposals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "appdoc": 1, "description": "example", "name": "example", "tools": [ { "description": "example", "input_schema": "example", "name": "example", "output_schema": "example", "result_limit": "example", "timeout": "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 the current key must name.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A proposed document with bounds checked before it is stored.

object
appdoc
required

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

integer format: int32
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
One of:
null
Examplegenerated
{
  "appdoc": 1,
  "description": "example",
  "name": "example",
  "tools": [
    {
      "description": "example",
      "input_schema": "example",
      "name": "example",
      "output_schema": "example",
      "result_limit": "example",
      "timeout": "example"
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

The update proposal, consent URL, and poll secret. Grant keeps this install and its key; its committed poll receipt remains for the proposal’s ten-minute lifetime.

Media typeapplication/json

What a vendor gets back: the proposal plus where to send the human.

object
expires
required
integer format: int64
interval
required
integer format: int64
poll_secret
required

What the vendor polls with. Issued once with the proposal; stored hashed.

string
request
required

One proposal. Minted per POST, so two proposals of one document are two requests, each with its own secret and its own key.

string
vendor
required

The vendor config’s content hash: 64 hex chars.

string
consent_url
required
string
Examplegenerated
{
  "expires": 1,
  "interval": 1,
  "poll_secret": "example",
  "request": "example",
  "vendor": "example",
  "consent_url": "example"
}

400

Section titled “400”

The response body names the invalid field and reason in the proposed vendor config.

404

Section titled “404”

The key does not name this install.