Amigo Integrations API
The Integrations API from Amigo — 7 operation(s) for integrations.
The Integrations API from Amigo — 7 operation(s) for integrations.
openapi: 3.1.0
info:
title: Amigo Account Integrations API
version: 0.1.0
servers:
- url: https://api.amigo.ai
- url: https://internal-api.amigo.ai
- url: https://api-eu-central-1.amigo.ai
- url: https://api-ap-southeast-2.amigo.ai
- url: https://api-ca-central-1.amigo.ai
security:
- Bearer-Authorization: []
Bearer-Authorization-Organization: []
Basic: []
tags:
- name: Integrations
paths:
/v1/{workspace_id}/integrations:
post:
tags:
- Integrations
summary: Create a REST integration
description: Create a new REST integration in a workspace. Endpoints are added separately via `POST /integrations/{integration_id}/endpoints`. Requires `Integration.create` permission.
operationId: create-integration
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__routes__integrations__create_integration__Request'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RestIntegrationResponse'
'404':
description: Workspace not found.
'409':
description: Integration name already taken in this workspace.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Invalid request body.
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
get:
tags:
- Integrations
summary: List integrations
description: '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.'
operationId: list-integrations
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: enabled
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
description: Filter to integrations with this enabled flag. None matches both.
title: Enabled
description: Filter to integrations with this enabled flag. None matches both.
- name: search
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/SearchString'
- type: 'null'
description: Substring match against name, display_name, or id (case-insensitive).
title: Search
description: Substring match against name, display_name, or id (case-insensitive).
- name: sort_by
in: query
required: false
schema:
type: array
items:
type: string
description: '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.'
default: []
title: Sort By
description: '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.'
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
exclusiveMinimum: 0
description: The maximum number of integrations to return.
default: 50
title: Limit
description: The maximum number of integrations to return.
- name: continuation_token
in: query
required: false
schema:
description: Opaque token from a prior response. Pass back unchanged with the same `sort_by` to advance.
title: Continuation Token
description: Opaque token from a prior response. Pass back unchanged with the same `sort_by` to advance.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/src__routes__integrations__list_integrations__Response'
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Query parameter failed validation or continuation_token is unparseable.
/v1/{workspace_id}/integrations/approvals/{conversation_id}/approve:
post:
tags:
- Integrations
summary: Approve a pending integration-write approval
description: 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.
operationId: approve-integration-write
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationApprovalResponse'
'404':
description: Conversation not found in this workspace.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'429':
description: Rate limited.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/integrations/approvals/{conversation_id}/reject:
post:
tags:
- Integrations
summary: Reject a pending integration-write approval
description: 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.
operationId: reject-integration-write
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: conversation_id
in: path
required: true
schema:
type: string
format: uuid
title: Conversation Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationRejectRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationApprovalResponse'
'404':
description: Conversation not found in this workspace.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'429':
description: Rate limited.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/integrations/{integration_id}:
get:
tags:
- Integrations
summary: Get an integration
description: Retrieve an integration by ID. Requires `Integration.view` permission.
operationId: get-integration
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
title: Integration Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RestIntegrationResponse'
'404':
description: Integration not found.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Integrations
summary: Update a REST integration
description: '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.'
operationId: update-integration
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
title: Integration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__routes__integrations__update_integration__Request'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RestIntegrationResponse'
'404':
description: Integration not found.
'409':
description: Managed integration mutation blocked.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Invalid request body, NOT NULL field set to null, or no fields to update.
delete:
tags:
- Integrations
summary: Delete a REST integration
description: Delete a REST integration. Requires `Integration.delete` permission.
operationId: delete-integration
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
title: Integration Id
responses:
'204':
description: Successful Response
'404':
description: Integration not found.
'409':
description: Integration is managed or referenced by one or more skills.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/integrations/{integration_id}/endpoints:
post:
tags:
- Integrations
summary: Add an endpoint
description: Add a new endpoint to a REST integration. Requires `Integration.update` permission.
operationId: create-integration-endpoint
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
title: Integration Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__routes__integrations__create_endpoint__Request'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointResponse'
'404':
description: Integration not found.
'409':
description: Integration is managed or endpoint name already exists.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Invalid request body.
get:
tags:
- Integrations
summary: List endpoints
description: '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.'
operationId: list-integration-endpoints
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
title: Integration Id
- name: search
in: query
required: false
schema:
anyOf:
- $ref: '#/components/schemas/SearchString'
- type: 'null'
description: Substring match against name or description (case-insensitive).
title: Search
description: Substring match against name or description (case-insensitive).
- name: sort_by
in: query
required: false
schema:
type: array
items:
type: string
description: '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.'
default: []
title: Sort By
description: '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.'
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
exclusiveMinimum: 0
description: The maximum number of endpoints to return.
default: 50
title: Limit
description: The maximum number of endpoints to return.
- name: continuation_token
in: query
required: false
schema:
description: Opaque token from a prior response. Pass back unchanged with the same `sort_by` to advance.
title: Continuation Token
description: Opaque token from a prior response. Pass back unchanged with the same `sort_by` to advance.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/src__routes__integrations__list_endpoints__Response'
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Query parameter failed validation or continuation_token is unparseable.
/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}:
get:
tags:
- Integrations
summary: Get an endpoint
description: Get a single endpoint on a REST integration. Requires `Integration.view` permission.
operationId: get-integration-endpoint
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
title: Integration Id
- name: endpoint_id
in: path
required: true
schema:
type: string
format: uuid
title: Endpoint Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointResponse'
'404':
description: Endpoint not found.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- Integrations
summary: Update an endpoint
description: 'Patch an endpoint on a REST integration. The endpoint `name` is immutable. Pass `response_template: null` to clear the Jinja template (the only DB-nullable column). Every other field rejects explicit null at validation time. Requires `Integration.update` permission.'
operationId: update-integration-endpoint
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
title: Integration Id
- name: endpoint_id
in: path
required: true
schema:
type: string
format: uuid
title: Endpoint Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__routes__integrations__update_endpoint__Request'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EndpointResponse'
'404':
description: Endpoint not found.
'409':
description: Managed integration endpoint mutation blocked.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Invalid request body, NOT NULL field set to null, or no fields to update.
delete:
tags:
- Integrations
summary: Delete an endpoint
description: Delete an endpoint from a REST integration. Requires `Integration.update` permission.
operationId: delete-integration-endpoint
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
title: Integration Id
- name: endpoint_id
in: path
required: true
schema:
type: string
format: uuid
title: Endpoint Id
responses:
'204':
description: Successful Response
'404':
description: Endpoint not found.
'409':
description: Managed integration endpoint mutation blocked.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}/test:
post:
tags:
- Integrations
summary: Test an integration endpoint
description: Execute an integration endpoint with test parameters and return the full response pipeline breakdown. Requires `Integration.view` permission.
operationId: test-integration-endpoint
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: integration_id
in: path
required: true
schema:
type: string
format: uuid
title: Integration Id
- name: endpoint_id
in: path
required: true
schema:
type: string
format: uuid
title: Endpoint Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/src__routes__integrations__test_endpoint__Request'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/src__routes__integrations__test_endpoint__Response'
'404':
description: Integration or endpoint not found.
'403':
description: Insufficient permissions.
'401':
description: Missing or invalid API key.
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
src__routes__integrations__create_integration__Request:
properties:
name:
type: string
maxLength: 128
minLength: 2
pattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$
title: Name
description: Slug-like identifier, lowercase alphanumeric + hyphens/underscores. Immutable post-create.
display_name:
$ref: '#/components/schemas/NameString'
description: Human-readable name.
base_url:
type: string
maxLength: 2083
minLength: 1
format: uri
title: Base Url
description: Base URL for the upstream REST API.
auth:
anyOf:
- oneOf:
- $ref: '#/components/schemas/StaticHeaderAuthRequest'
- $ref: '#/components/schemas/OAuth2ClientCredentialsAuthRequest'
- $ref: '#/components/schemas/OAuth2JwtBearerAuthRequest'
- $ref: '#/components/schemas/CustomTokenExchangeAuthRequest'
discriminator:
propertyName: type
mapping:
custom_token_exchange: '#/components/schemas/CustomTokenExchangeAuthRequest'
oauth2_client_credentials: '#/components/schemas/OAuth2ClientCredentialsAuthRequest'
oauth2_jwt_bearer: '#/components/schemas/OAuth2JwtBearerAuthRequest'
static_header: '#/components/schemas/StaticHeaderAuthRequest'
- type: 'null'
title: Auth
description: Auth configuration. When set, ``secret_value`` is required.
secret_value:
anyOf:
- type: string
maxLength: 8192
minLength: 1
- type: 'null'
title: Secret Value
description: '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.'
enabled:
type: boolean
title: Enabled
description: Whether the integration is active on create.
default: true
managed:
type: boolean
title: Managed
description: Whether this is a system-managed integration protected from workspace CRUD.
default: false
approval_policy:
type: string
enum:
- none
- writes
- all
title: Approval Policy
description: 'Human-in-the-loop approval gate. ``none`` (default) = no approval
required; ``writes`` = approval required for write-classified endpoints;
``all`` = approval required for every endpoint.'
default: none
type: object
required:
- name
- display_name
- base_url
title: Request
description: Create body — REST only.
CustomTokenExchangeAuthRequest:
properties:
type:
type: string
const: custom_token_exchange
title: Type
default: custom_token_exchange
exchange_url:
type: string
maxLength: 2083
minLength: 1
format: uri
title: Exchange Url
body_encoding:
type: string
enum:
- json
- form
title: Body Encoding
description: '``json`` (default) sends static_body_fields + param_body_fields as JSON; ``form`` sends as application/x-www-form-urlencoded.'
default: json
static_headers:
patternProperties:
^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$:
type: string
propertyNames:
maxLength: 256
minLength: 1
type: object
title: Static Headers
description: Workspace-level headers on the exchange request (keys are RFC 7230 tchar). Values may contain ``{secret}`` placeholder.
default: {}
static_body_fields:
additionalProperties:
type: string
type: object
title: Static Body Fields
description: 'Workspace-level body fields keyed by RFC 6901 JSON Pointer (e.g. ``/meta/tool_name``
for nested fields, or ``/foo`` for a root-level field). Values may contain ``{secret}``
placeholder.'
default: {}
param_headers:
patternProperties:
^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$:
$ref: '#/components/schemas/ParamValueRequest'
propertyNames:
maxLength: 256
minLength: 1
type: object
title: Param Headers
description: Per-request params routed to headers on the exchange request, keyed by wire-name.
default: {}
param_body_fields:
additionalProperties:
$ref: '#/components/schemas/ParamValueRequest'
type: object
title: Param Body Fields
description: Per-request params routed to body fields on the exchange request, keyed by RFC 6901 JSON Pointer.
default: {}
identity_bindings:
additionalProperties:
type: string
enum:
- principal.subject_key
- principal.subject_id
- external_user.subject_key
type: object
maxProperties: 50
title: Identity Bindings
description: 'Maps a declared ``param_name`` to the verified identity attribute that supplies it
at dispatch. A bound param is dropped from the LLM-facing tool schema and injected from the
verified session context (never model-supplied), closing the per-user-identity impersonation hole.
Keys MUST reference a ``param_name`` declared on ``param_headers`` / ``param_body_fields``.'
default: {}
identity_binding_test_values:
additionalProperties:
type: string
type: object
title: Identity Binding Test Values
description: 'Author-configured test values for identity-bound params.
Only ``external_user.subject_key`` bindings may carry test values. Runtime
dispatch uses them only when a backend execution path explicitly opts in.'
default: {}
response_token_path:
type: string
title: Response Token Path
description: 'RFC 6901 JSON Pointer into the exchange response body that extracts the bearer token
(e.g. ``/access_token`` or ``/data/bearer``). NO default — every config commits explicitly.'
type: object
required:
- exchange_url
- response_token_path
title: CustomTokenExchangeAuthRequest
description: 'Pre-flight exchange that mints a downstream bearer.
Replaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.
Path-shaped fields (``response_token_path``, ``static_body_fields`` keys,
``param_body_fields`` keys) MUST be valid RFC 6901 JSON Pointer — one
syntax throughout.'
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
src__routes__integrations__test_endpoint__Response:
properties:
status_code:
anyOf:
- type: integer
- type: 'null'
title: Status Code
description: HTTP status code from the upstream call.
duration_ms:
type: number
title: Duration Ms
description: Request duration in milliseconds.
default: 0
retries:
type: integer
title: Retries
description: Number of retry attempts.
default: 0
raw_response:
title: Raw Response
description: Raw response body from the upstream call.
rendered:
anyOf:
- type: string
- type: 'null'
title: Rendered
description: Response after Jinja `response_template` rendering, pre-truncation.
final_result:
anyOf:
- type: string
- type: 'null'
title: Final Result
description: Final processed result (rendered + truncated to max_response_length).
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: Error message if the request failed.
type: object
title: Response
description: Full breadcrumb returned by the test handler.
src__routes__integrations__update_endpoint__Request:
properties:
description:
type: string
maxLength: 2048
minLength: 1
title: Description
method:
type: string
enum:
- GET
- POST
- PUT
- PATCH
- DELETE
title: Method
path:
type: string
maxLength: 2048
minLength: 1
pattern: ^[^/]
title: Path
description: URL path appended to the integration's base_url. Must NOT start with `/`.
input_schema:
additionalProperties: true
type: object
title: Input Schema
headers:
additionalProperties:
type: string
type: object
title: Headers
static_body_fields:
additionalProperties:
type: string
type: object
title: Static Body Fields
body_format:
type: string
enum:
- json
- form
title: Body Fo
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-integrations-api-openapi.yml