Integrations
List every integration for a workspace. Optionally filter by enabled or search (name/display_name/id ilike). Sort via repeated sort_by query params; each entry is +field or -field (allowed fields: name, created_at, updated_at). Default: -created_at. Cursor opaque — round-trip continuation_token unchanged with the same sort_by. Requires Integration.view permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Filter to integrations with this enabled flag. None matches both.
Substring match against name, display_name, or id (case-insensitive).
Sort axes. Repeated query param stacks left-to-right. Each entry is +field or -field
(direction prefix REQUIRED). Allowed fields: name, created_at, updated_at.
Default: -created_at. id is always appended as the final tiebreaker.
[]The maximum number of integrations to return.
50Opaque token from a prior response. Pass back unchanged with the same sort_by to advance.
Successful Response
Whether there are more integrations to retrieve.
Opaque token for the next page. Null when there are no more results.
Missing or invalid API key.
Insufficient permissions.
Query parameter failed validation or continuation_token is unparseable.
GET /v1/{workspace_id}/integrations HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"display_name": "text",
"enabled": true,
"managed": false,
"approval_policy": "none",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"kind": "rest",
"base_url": "text",
"auth": {
"type": "text",
"header_name": "text"
},
"endpoint_count": 1
}
],
"has_more": true,
"continuation_token": null
}Create a new REST integration in a workspace. Endpoints are added separately via POST /integrations/{integration_id}/endpoints. Requires Integration.create permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Create body — REST only.
Slug-like identifier, lowercase alphanumeric + hyphens/underscores. Immutable post-create.
^[a-z0-9][a-z0-9_-]*[a-z0-9]$Human-readable name.
Base URL for the upstream REST API.
Auth configuration. When set, secret_value is required.
Inline secret literal — auto-provisioned to the per-integration SSM path.
Required when auth is set. Bounded to fit a PEM RSA-4096 key + cert chain.
Whether the integration is active on create.
trueWhether this is a system-managed integration protected from workspace CRUD.
falseHuman-in-the-loop approval gate. none (default) = no approval
required; writes = approval required for write-classified endpoints;
all = approval required for every endpoint.
nonePossible values: Successful Response
REST variant — base URL, auth config, endpoint count.
Integration ID.
Workspace ID.
Slug-like identifier, immutable post-create.
Human-readable name.
Whether the integration is active.
Whether the integration is system-managed and protected from workspace CRUD.
falseHuman-in-the-loop approval gate. none = no approval required;
writes = approval required for write-classified endpoints;
all = approval required for every endpoint.
nonePossible values: When the integration was created.
When the integration was last updated.
Discriminator.
restBase URL for REST integrations.
Authentication configuration (lib TypedDict union).
Number of configured endpoints. Fetch the full list via GET /endpoints.
Missing or invalid API key.
Insufficient permissions.
Workspace not found.
Integration name already taken in this workspace.
Invalid request body.
POST /v1/{workspace_id}/integrations HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 201
{
"name": "text",
"display_name": "text",
"base_url": "https://example.com",
"auth": {
"type": "static_header",
"header_name": "text"
},
"secret_value": "text",
"enabled": true,
"managed": false,
"approval_policy": "none"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"display_name": "text",
"enabled": true,
"managed": false,
"approval_policy": "none",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"kind": "rest",
"base_url": "text",
"auth": {
"type": "text",
"header_name": "text"
},
"endpoint_count": 1
}Approve a pending human-in-the-loop integration-write approval for a conversation. Publishes integration.approval_granted to the workspace event channel; the subscribed text session fires the gated write. Requires ReviewQueue.review permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Resolution outcome for a pending integration-write approval.
Missing or invalid API key.
Insufficient permissions.
Conversation not found in this workspace.
Validation Error
Rate limited.
POST /v1/{workspace_id}/integrations/approvals/{conversation_id}/approve HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "granted",
"conversation_id": "text"
}Reject a pending human-in-the-loop integration-write approval for a conversation. Publishes integration.approval_rejected to the workspace event channel; the subscribed text session declines the gated write. Requires ReviewQueue.review permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Reject body — optional free-text reason surfaced to the agent.
Successful Response
Resolution outcome for a pending integration-write approval.
Missing or invalid API key.
Insufficient permissions.
Conversation not found in this workspace.
Validation Error
Rate limited.
POST /v1/{workspace_id}/integrations/approvals/{conversation_id}/reject HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"reason": "text"
}{
"status": "granted",
"conversation_id": "text"
}Retrieve an integration by ID. Requires Integration.view permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
REST variant — base URL, auth config, endpoint count.
Integration ID.
Workspace ID.
Slug-like identifier, immutable post-create.
Human-readable name.
Whether the integration is active.
Whether the integration is system-managed and protected from workspace CRUD.
falseHuman-in-the-loop approval gate. none = no approval required;
writes = approval required for write-classified endpoints;
all = approval required for every endpoint.
nonePossible values: When the integration was created.
When the integration was last updated.
Discriminator.
restBase URL for REST integrations.
Authentication configuration (lib TypedDict union).
Number of configured endpoints. Fetch the full list via GET /endpoints.
Missing or invalid API key.
Insufficient permissions.
Integration not found.
Validation Error
GET /v1/{workspace_id}/integrations/{integration_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"display_name": "text",
"enabled": true,
"managed": false,
"approval_policy": "none",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"kind": "rest",
"base_url": "text",
"auth": {
"type": "text",
"header_name": "text"
},
"endpoint_count": 1
}Delete a REST integration. Requires Integration.delete permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
No content
Missing or invalid API key.
Insufficient permissions.
Integration not found.
Integration is managed or referenced by one or more skills.
Validation Error
DELETE /v1/{workspace_id}/integrations/{integration_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Patch a REST integration. NOT NULL fields reject null at validation time; pass auth: null to clear the auth config. auth and secret_value are independent — update either alone to swap auth shape (reusing the existing secret) or rotate the secret (keeping the existing auth shape). Requires Integration.update permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
PATCH body — each field is sentinel-defaulted; absent ≠ explicit-null.
New display name.
New base URL.
New auth config. Absent ⇒ untouched; null ⇒ clear; value ⇒ replace.
Independent of secret_value — updating auth alone reuses the
existing SSM secret.
Rotate the per-integration SSM secret. Absent ⇒ existing secret
untouched; value ⇒ overwrite SSM at the canonical path. Explicit
null is rejected at validation — there is no "clear the secret"
operation (clearing auth makes the secret unreachable; that's the
intended clear path).
Toggle the integration on/off.
Mark/unmark the integration as system-managed. Requires platform:admin scope.
Change the human-in-the-loop approval gate. none = no approval
required; writes = approval required for write-classified endpoints;
all = approval required for every endpoint. Absent ⇒ untouched.
Successful Response
REST variant — base URL, auth config, endpoint count.
Integration ID.
Workspace ID.
Slug-like identifier, immutable post-create.
Human-readable name.
Whether the integration is active.
Whether the integration is system-managed and protected from workspace CRUD.
falseHuman-in-the-loop approval gate. none = no approval required;
writes = approval required for write-classified endpoints;
all = approval required for every endpoint.
nonePossible values: When the integration was created.
When the integration was last updated.
Discriminator.
restBase URL for REST integrations.
Authentication configuration (lib TypedDict union).
Number of configured endpoints. Fetch the full list via GET /endpoints.
Missing or invalid API key.
Insufficient permissions.
Integration not found.
Managed integration mutation blocked.
Invalid request body, NOT NULL field set to null, or no fields to update.
PATCH /v1/{workspace_id}/integrations/{integration_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 186
{
"display_name": "text",
"base_url": "https://example.com",
"auth": {
"type": "static_header",
"header_name": "text"
},
"secret_value": "text",
"enabled": true,
"managed": true,
"approval_policy": "none"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"display_name": "text",
"enabled": true,
"managed": false,
"approval_policy": "none",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"kind": "rest",
"base_url": "text",
"auth": {
"type": "text",
"header_name": "text"
},
"endpoint_count": 1
}List endpoints on a REST integration. Optionally search by name/description. Sort via repeated sort_by query params; each entry is +field or -field (allowed fields: name, created_at, updated_at). Default: -created_at. Cursor opaque — round-trip continuation_token unchanged with the same sort_by. Requires Integration.view permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Substring match against name or description (case-insensitive).
Sort axes. Repeated query param stacks left-to-right. Each entry is +field or -field
(direction prefix REQUIRED). Allowed fields: name, created_at, updated_at.
Default: -created_at. id is always appended as the final tiebreaker.
[]The maximum number of endpoints to return.
50Opaque token from a prior response. Pass back unchanged with the same sort_by to advance.
Successful Response
Whether there are more endpoints to retrieve.
Opaque token for the next page. Null when there are no more results.
Missing or invalid API key.
Insufficient permissions.
Query parameter failed validation or continuation_token is unparseable.
GET /v1/{workspace_id}/integrations/{integration_id}/endpoints HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"description": "text",
"method": "GET",
"path": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"static_body_fields": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"body_format": "json",
"response_template": "text",
"client_output": {
"type": "text",
"schema_version": "text",
"json_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"max_bytes": 262144,
"external_user_enabled": false
},
"declarations": {
"writes": {
"kind": "booking",
"success": {
"reported_by": "text"
}
}
},
"max_response_length": 0,
"timeout_seconds": 30,
"max_retries": 2,
"retry_on_status": [
1
]
}
],
"has_more": true,
"continuation_token": null
}Add a new endpoint to a REST integration. Requires Integration.update permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Add a new endpoint to a REST integration (V186 flat shape).
Slug-like identifier, immutable post-create.
^[a-z0-9][a-z0-9_-]*[a-z0-9]$LLM-facing description shown in the tool definition.
HTTP method.
POSTPossible values: URL path appended to the integration's base_url. Must NOT start with / — the path is
joined onto the base URL (which already carries the leading slash). Supports {param} substitution.
^[^/]Outbound body encoding for write methods.
jsonPossible values: Jinja template (sandboxed, StrictUndefined) rendered against the parsed JSON response.
Truncate the rendered string to this many chars. 0 = no truncation.
0Per-request timeout.
30Retry attempts on transient failures.
2HTTP status codes that trigger a retry.
Successful Response
Per-endpoint response (V186 flat shape).
Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs.
Slug-like identifier. Unique per integration; immutable post-create.
LLM-facing description.
HTTP method.
URL path appended to the integration's base_url.
Outbound body encoding.
jsonPossible values: Jinja template rendered against the parsed JSON response.
Truncate the final rendered string to this many chars.
0Per-request timeout.
30Retry attempts on transient failures.
2HTTP status codes that trigger a retry.
Missing or invalid API key.
Insufficient permissions.
Integration not found.
Integration is managed or endpoint name already exists.
Invalid request body.
POST /v1/{workspace_id}/integrations/{integration_id}/endpoints HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 588
{
"name": "text",
"description": "text",
"method": "POST",
"path": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"static_body_fields": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"body_format": "json",
"response_template": "text",
"client_output": {
"type": "text",
"schema_version": "text",
"json_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"max_bytes": 262144,
"external_user_enabled": false
},
"declarations": {
"writes": {
"kind": "booking",
"success": {
"reported_by": "text"
}
}
},
"max_response_length": 0,
"timeout_seconds": 30,
"max_retries": 2,
"retry_on_status": [
1
]
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"description": "text",
"method": "GET",
"path": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"static_body_fields": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"body_format": "json",
"response_template": "text",
"client_output": {
"type": "text",
"schema_version": "text",
"json_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"max_bytes": 262144,
"external_user_enabled": false
},
"declarations": {
"writes": {
"kind": "booking",
"success": {
"reported_by": "text"
}
}
},
"max_response_length": 0,
"timeout_seconds": 30,
"max_retries": 2,
"retry_on_status": [
1
]
}Get a single endpoint on a REST integration. Requires Integration.view permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Per-endpoint response (V186 flat shape).
Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs.
Slug-like identifier. Unique per integration; immutable post-create.
LLM-facing description.
HTTP method.
URL path appended to the integration's base_url.
Outbound body encoding.
jsonPossible values: Jinja template rendered against the parsed JSON response.
Truncate the final rendered string to this many chars.
0Per-request timeout.
30Retry attempts on transient failures.
2HTTP status codes that trigger a retry.
Missing or invalid API key.
Insufficient permissions.
Endpoint not found.
Validation Error
GET /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"description": "text",
"method": "GET",
"path": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"static_body_fields": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"body_format": "json",
"response_template": "text",
"client_output": {
"type": "text",
"schema_version": "text",
"json_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"max_bytes": 262144,
"external_user_enabled": false
},
"declarations": {
"writes": {
"kind": "booking",
"success": {
"reported_by": "text"
}
}
},
"max_response_length": 0,
"timeout_seconds": 30,
"max_retries": 2,
"retry_on_status": [
1
]
}Delete an endpoint from a REST integration. Requires Integration.update permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
No content
Missing or invalid API key.
Insufficient permissions.
Endpoint not found.
Managed integration endpoint mutation blocked.
Validation Error
DELETE /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Patch an endpoint on a REST integration. The endpoint name is immutable. Pass null for response_template or client_output to clear it. declarations changes only the declarations it names; pass one as null to undeclare it. Every other field rejects explicit null at validation time. Requires Integration.update permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Patch an existing endpoint (V186 flat shape). name is immutable.
URL path appended to the integration's base_url. Must NOT start with /.
^[^/]Jinja template; pass null to clear (the only DB-nullable column on this row).
Successful Response
Per-endpoint response (V186 flat shape).
Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs.
Slug-like identifier. Unique per integration; immutable post-create.
LLM-facing description.
HTTP method.
URL path appended to the integration's base_url.
Outbound body encoding.
jsonPossible values: Jinja template rendered against the parsed JSON response.
Truncate the final rendered string to this many chars.
0Per-request timeout.
30Retry attempts on transient failures.
2HTTP status codes that trigger a retry.
Missing or invalid API key.
Insufficient permissions.
Endpoint not found.
Managed integration endpoint mutation blocked.
Invalid request body, NOT NULL field set to null, or no fields to update.
PATCH /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 572
{
"description": "text",
"method": "GET",
"path": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"static_body_fields": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"body_format": "json",
"response_template": "text",
"client_output": {
"type": "text",
"schema_version": "text",
"json_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"max_bytes": 262144,
"external_user_enabled": false
},
"declarations": {
"writes": {
"kind": "booking",
"success": {
"reported_by": "text"
}
}
},
"max_response_length": 1,
"timeout_seconds": 1,
"max_retries": 1,
"retry_on_status": [
1
]
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"description": "text",
"method": "GET",
"path": "text",
"input_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"headers": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"static_body_fields": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"body_format": "json",
"response_template": "text",
"client_output": {
"type": "text",
"schema_version": "text",
"json_schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"max_bytes": 262144,
"external_user_enabled": false
},
"declarations": {
"writes": {
"kind": "booking",
"success": {
"reported_by": "text"
}
}
},
"max_response_length": 0,
"timeout_seconds": 30,
"max_retries": 2,
"retry_on_status": [
1
]
}Execute an integration endpoint with test parameters and return the full response pipeline breakdown. Requires Integration.view permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Inputs to POST /{integration_id}/endpoints/{endpoint_id}/test.
Successful Response
Full breadcrumb returned by the test handler.
HTTP status code from the upstream call.
Request duration in milliseconds.
0Number of retry attempts.
0Raw response body from the upstream call.
Response after Jinja response_template rendering, pre-truncation.
Final processed result (rendered + truncated to max_response_length).
Error message if the request failed.
Safe validation summary when client output is enabled but cannot be emitted.
Whether the endpoint's declared write happened, as its declarations.writes.success reads
this response. Null when the endpoint declares no write, or the call failed.
Missing or invalid API key.
Insufficient permissions.
Integration or endpoint not found.
Validation Error
POST /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}/test HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 102
{
"params": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"auth_params": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}{
"status_code": 1,
"duration_ms": 0,
"retries": 0,
"raw_response": null,
"rendered": "text",
"final_result": "text",
"error": "text",
"artifact": {
"type": "text",
"schema_version": "text",
"payload": {
"ANY_ADDITIONAL_PROPERTY": true
}
},
"artifact_error": "text",
"wrote": true
}Last updated
Was this helpful?