Connections
6 operations.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/projects/{projectId}/environments/{environmentId}/connections | List Connections for an Environment |
| POST | /api/v1/projects/{projectId}/environments/{environmentId}/connections | Create an Environment Connection |
| GET | /api/v1/projects/{projectId}/environments/{environmentId}/connections/{connectionId} | Get a single Connection by id |
| PATCH | /api/v1/projects/{projectId}/environments/{environmentId}/connections/{connectionId} | Update an Environment Connection |
| DELETE | /api/v1/projects/{projectId}/environments/{environmentId}/connections/{connectionId} | Delete a Connection |
| GET | /api/v1/projects/{projectId}/environments/{environmentId}/connections/health | Read Environment connection health |
List Connections for an Environment
GET /api/v1/projects/{projectId}/environments/{environmentId}/connections
List metadata-only Connections owned by the given Project Environment. The response is cursor-paginated; pass pagination.nextCursor unchanged to read the next page. Credential material and provider-specific OAuth identity remain internal.
Returns 404 if the Project does not exist in the caller's organization.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List Connections for an Environment. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to List Connections for an Environment. |
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List Connections for an Environment. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List Connections for an Environment. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required); pagination: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Create an Environment Connection
POST /api/v1/projects/{projectId}/environments/{environmentId}/connections
Creates a metadata-only Connection in the resolved Project Environment. An optional provider credential ID and version pin an existing credential version, which must be an active, unexpired api_key credential whose provider matches settings.provider on an http Connection; the response shows the pinned id and version number, never credential material. An optional Agent binding records the exact Connection version and requires a credential pin. Unknown or foreign coordinates return 404; an unbindable pin, a binding without a pin, and malformed binding input return 422.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create an Environment Connection. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Create an Environment Connection. |
Request body
Required — Request body for: Create an Environment Connection.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
name | string | required | |
kind | "http" | "database" | "object_storage" | "messaging" | "custom" | required | |
providerCredentialId | string | null | optional | |
providerCredentialVersion | integer | null | optional | |
settings | object | required | |
agentId | string | optional | |
bindingKey | string | optional |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get a single Connection by id
GET /api/v1/projects/{projectId}/environments/{environmentId}/connections/{connectionId}
Fetch a Connection's metadata and current immutable version reference. Credential values are never returned; they are used only to perform the configured integration action.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get a single Connection by id. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Get a single Connection by id. |
connectionId | string | required | Identifies the stored external connection. Applies to Get a single Connection by id. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Update an Environment Connection
PATCH /api/v1/projects/{projectId}/environments/{environmentId}/connections/{connectionId}
Updates safe Connection metadata or creates a new immutable Connection version. A version with settings alone carries the exact provider credential version the current version pins, so after a credential rotation it keeps the old version until a caller pins the new one; a version with providerCredentialId and providerCredentialVersion pins that version. Every carried or explicit pin must name an active, unexpired api_key credential whose provider matches settings.provider on an http Connection; otherwise, or when the current version has no pin to carry, the request returns 422. OAuth Connection versions are written only by the OAuth flow, so any version write to them returns 422. A binding requires a credential-bearing Connection version. The response shows the pinned credential id and version number; credential material is never returned.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Update an Environment Connection. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Update an Environment Connection. |
connectionId | string | required | Identifies the stored external connection. Applies to Update an Environment Connection. |
Request body
Required — Request body for: Update an Environment Connection.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
name | string | optional | |
status | "active" | "disabled" | "deleting" | optional | |
version | one of 2 types | optional | New immutable version. Settings alone carry the exact provider credential version the current version pins, even after the credential rotated; settings with providerCredentialId and providerCredentialVersion pin that version instead. |
agentId | string | optional | |
bindingKey | string | optional |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Delete a Connection
DELETE /api/v1/projects/{projectId}/environments/{environmentId}/connections/{connectionId}
Deletes the Connection from the resolved Project Environment. Existing retained audit or pinned execution records are not rewritten; a Connection retained by an immutable configuration snapshot returns 409, and a foreign or unknown Connection returns 404.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Delete a Connection. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Delete a Connection. |
connectionId | string | required | Identifies the stored external connection. Applies to Delete a Connection. |
Responses
| Status | Description | Body |
|---|---|---|
204 | Response for status 204 | none — none |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Read Environment connection health
GET /api/v1/projects/{projectId}/environments/{environmentId}/connections/health
Reads metadata-only health for the active Deployment's declared Environment connection bindings, including missing configured bindings. Requires connections:list; it is not an execution-readiness guarantee and does not refresh tokens or contact providers.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Read Environment connection health. |
environmentId | string | required | Identifies the Project environment addressed by the operation. Applies to Read Environment connection health. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — data: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |