Declaring Integration Operations
An operation is a named HTTP request that functions may make with an integration's credential, for example list_open_pull_requests = GET /repos/{owner}/{repo}/pulls. Once an integration declares operations, you can create brokered functions from them with Wrap an integration operation, and grant them to hand-written functions under Allowed Operations. See Integrations for why this matters.
The app lists operations and lets you use them, but doesn't yet have an editor for declaring them. Declare operations through the Integration API (see Platform API), or install an integration from a template that already includes them.
Before you start
The integration needs Allowed URLs. Each must be https, include a host, and have no query string or fragment. An integration can list at most 16.
Declare an operation
Send POST /integrations/{integration_id}/operations to the Integration API:
{
"name": "list_open_pull_requests",
"description": "List open pull requests in a repository.",
"method": "GET",
"path_template": "/repos/{owner}/{repo}/pulls",
"path_params": ["owner", "repo"],
"fixed_query": {"state": "open"},
"query_params": ["per_page", "page"]
}
| Field | Required | Description |
|---|---|---|
name | Yes | Unique per integration. Lowercase letters, digits, _, - and ., starting with a letter or digit, up to 63 characters. |
description | No | Shown to people authoring functions, and used as the default tool description. |
method | No | GET (default), POST, PUT, PATCH, DELETE or HEAD. |
base_url | Sometimes | Which of the integration's allowed URLs to use. Optional when there's only one. |
path_template | Yes | Path relative to the base URL, starting with /. {name} placeholders are filled from parameters. |
path_params | No | Placeholder names the caller must supply. |
path_segment_params | No | Path parameters whose values may contain /. Path traversal is still rejected. |
fixed_query | No | Query parameters the operation always sends. Callers can't override them. |
query_params | No | Query parameters a caller may supply. Anything else is dropped. |
headers | No | Static headers. Authorization isn't allowed: the credential is added at call time. |
fixed_body | No | JSON body fields the operation always sends. Callers can't override them. |
body_params | No | JSON body fields a caller may supply. Anything else is dropped. |
There's no host field: the host always comes from the integration. Each list or object field can declare up to 32 entries. Writes are rate-limited (60 per minute by default).
Other calls on the same path:
| Call | Purpose |
|---|---|
GET /integrations/{id}/operations | List operations. |
GET /integrations/{id}/operations/{name} | Read one operation. |
PUT /integrations/{id}/operations/{name} | Replace an operation. |
DELETE /integrations/{id}/operations/{name} | Delete an operation. Functions that still grant it are refused at runtime, and the app marks the stale grant with a warning icon. |
Choose how the credential is sent
By default the broker sends the secret named in the call (api_key unless the function names another) as Authorization: Bearer <secret>. For other APIs, set the integration's auth field with PATCH /integrations/{id}:
{"auth": {"scheme": "basic", "secrets": ["JIRA_EMAIL", "JIRA_API_TOKEN"]}}
| Scheme | Fields |
|---|---|
bearer | secrets: one secret name. |
basic | secrets: two secret names, combined as base64(first:second). |
header | secrets: one secret name; header: the header name (default Authorization); prefix: optional literal such as ApiKey . |
Use the operation
- In Resources → Functions, click + and choose Wrap an integration operation.
- Pick the integration and the operation, check the name and description, and click Create function.
Or, in a Local Python function, call capabilities.call("list_open_pull_requests", integration=<id>, owner=..., repo=...) and add the operation under Allowed Operations. See Creating Custom Functions.