# Integrations

## List integrations

> List integrations for a workspace with pagination. Optionally filter by enabled status. Requires \`Integration.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SearchString":{"type":"string","maxLength":200,"minLength":1},"PaginatedResponse_IntegrationResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/IntegrationResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[IntegrationResponse]"},"IntegrationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Integration ID"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace ID"},"name":{"type":"string","title":"Name","description":"Slug-like identifier"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name"},"protocol":{"type":"string","enum":["rest","desktop"],"title":"Protocol","description":"Communication protocol"},"base_url":{"type":"string","title":"Base Url","description":"Base URL for REST integrations","default":""},"auth":{"anyOf":[{"$ref":"#/components/schemas/AuthConfig"},{"type":"null"}],"description":"Authentication configuration"},"endpoints":{"items":{"$ref":"#/components/schemas/EndpointConfig"},"type":"array","title":"Endpoints","description":"Configured endpoints"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active"},"builtin":{"type":"boolean","title":"Builtin","description":"Whether this is a system-provided integration","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the integration was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the integration was last updated"}},"type":"object","required":["id","workspace_id","name","display_name","protocol","enabled","created_at","updated_at"],"title":"IntegrationResponse"},"AuthConfig":{"properties":{"type":{"type":"string","enum":["api_key_header","bearer_token","oauth2_client_credentials","json_token_exchange","oauth2_jwt_bearer","bearer_token_exchange"],"title":"Type"},"header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header Name"},"token_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Url"},"client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"token_request_client_id_field":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Token Request Client Id Field"},"token_request_client_secret_field":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Token Request Client Secret Field"},"token_response_path":{"anyOf":[{"type":"string","maxLength":512,"minLength":1},{"type":"null"}],"title":"Token Response Path"},"assertion_issuer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Issuer"},"assertion_subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Subject"},"assertion_audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Audience"},"token_lifetime_seconds":{"type":"integer","title":"Token Lifetime Seconds","default":3600},"assertion_scopes_in_jwt":{"type":"boolean","title":"Assertion Scopes In Jwt","default":false},"exchange_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Exchange Url"},"exchange_secret_header":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Exchange Secret Header","default":"X-API-KEY"},"exchange_secret_format":{"type":"string","maxLength":128,"minLength":8,"pattern":"^[^{}]*\\{secret\\}[^{}]*$","title":"Exchange Secret Format","default":"{secret}"},"exchange_param_headers":{"items":{"$ref":"#/components/schemas/ExchangeHeaderMapping"},"type":"array","maxItems":20,"title":"Exchange Param Headers"},"exchange_token_field":{"type":"string","maxLength":256,"minLength":1,"title":"Exchange Token Field","default":"token"},"exchange_expires_in_field":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Exchange Expires In Field"},"exchange_default_ttl_seconds":{"type":"integer","minimum":120,"title":"Exchange Default Ttl Seconds","default":3600}},"type":"object","required":["type"],"title":"AuthConfig","description":"Authentication configuration for an integration.\n\nSupports api_key_header, bearer_token, oauth2_client_credentials,\njson_token_exchange, oauth2_jwt_bearer, and bearer_token_exchange."},"ExchangeHeaderMapping":{"properties":{"header_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Header Name"},"param_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9_\\-]+$","title":"Param Name"},"consume":{"type":"boolean","title":"Consume","default":true},"required":{"type":"boolean","title":"Required","default":true}},"type":"object","required":["header_name","param_name"],"title":"ExchangeHeaderMapping","description":"One header on a token-exchange request, sourced from a request param.\n\nUsed by ``bearer_token_exchange`` auth type. Each mapping declares which\nrequest param feeds which exchange-call header. The same param values\nalso form the per-call cache key, so distinct (e.g.) user_ids yield\ndistinct cached tokens.\n\nExamples:\n    ``ExchangeHeaderMapping(header_name=\"X-USER-ID\", param_name=\"user_id\")``\n    ``ExchangeHeaderMapping(header_name=\"X-Org-ID\", param_name=\"org_id\")``"},"EndpointConfig":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","default":"POST"},"path":{"type":"string","title":"Path"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","default":{}},"response_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Response Mapping"},"response_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Response Filter"},"result_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Template"},"result_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Key"},"max_result_length":{"type":"integer","title":"Max Result Length","default":0},"retry_config":{"$ref":"#/components/schemas/RetryConfig","default":{"max_retries":2,"retry_on_status":[429,502,503,504]}},"result_delivery":{"type":"string","enum":["interrupt","queue"],"title":"Result Delivery","default":"interrupt"},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","default":{}},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","default":"json"},"request_transform":{"anyOf":[{"$ref":"#/components/schemas/RequestTransform"},{"type":"null"}]}},"type":"object","required":["name","description","path"],"title":"EndpointConfig","description":"Configuration for a single integration endpoint."},"RetryConfig":{"properties":{"max_retries":{"type":"integer","title":"Max Retries","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","title":"Retry On Status","default":[429,502,503,504]}},"type":"object","title":"RetryConfig","description":"Retry configuration for an endpoint."},"RequestTransform":{"properties":{"inject":{"additionalProperties":{"type":"string"},"type":"object","maxProperties":20,"title":"Inject"},"wrap_params_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Wrap Params Key"}},"type":"object","title":"RequestTransform","description":"Transforms outbound request body before sending to the integration endpoint.\n\nApplied after path-param substitution and auth-header resolution, right\nbefore the HTTP call.  Mirror of the response-side pipeline\n(``response_filter`` / ``result_key`` / ``result_template``).\n\nInject targets the **outermost** dict: when combined with\n``wrap_params_key``, injected fields sit alongside the wrapper key,\nnever inside the wrapped sub-dict."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/v1/{workspace_id}/integrations":{"get":{"tags":["Integrations"],"summary":"List integrations","description":"List integrations for a workspace with pagination. Optionally filter by enabled status. 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"}],"title":"Enabled"}},{"name":"protocol","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Protocol"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/SearchString"},{"type":"null"}],"title":"Search"}},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort By"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_IntegrationResponse_"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create an integration

> Create a new external API integration in a workspace. Requires \`Integration.create\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateIntegrationRequest":{"properties":{"name":{"type":"string","maxLength":128,"minLength":2,"title":"Name","description":"Slug-like identifier, lowercase alphanumeric + hyphens/underscores."},"display_name":{"$ref":"#/components/schemas/NameString"},"protocol":{"type":"string","const":"rest","title":"Protocol","default":"rest"},"base_url":{"type":"string","maxLength":2048,"title":"Base Url","default":""},"auth":{"anyOf":[{"$ref":"#/components/schemas/AuthConfigWithSecrets"},{"type":"null"}]},"endpoints":{"items":{"$ref":"#/components/schemas/EndpointConfig"},"type":"array","maxItems":50,"title":"Endpoints","default":[]},"enabled":{"type":"boolean","title":"Enabled","default":true}},"type":"object","required":["name","display_name"],"title":"CreateIntegrationRequest"},"NameString":{"type":"string","maxLength":256,"minLength":1},"AuthConfigWithSecrets":{"properties":{"type":{"type":"string","enum":["api_key_header","bearer_token","oauth2_client_credentials","json_token_exchange","oauth2_jwt_bearer","bearer_token_exchange"],"title":"Type"},"header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header Name"},"token_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Url"},"client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"token_request_client_id_field":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Token Request Client Id Field"},"token_request_client_secret_field":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Token Request Client Secret Field"},"token_response_path":{"anyOf":[{"type":"string","maxLength":512,"minLength":1},{"type":"null"}],"title":"Token Response Path"},"assertion_issuer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Issuer"},"assertion_subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Subject"},"assertion_audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Audience"},"token_lifetime_seconds":{"type":"integer","title":"Token Lifetime Seconds","default":3600},"assertion_scopes_in_jwt":{"type":"boolean","title":"Assertion Scopes In Jwt","default":false},"exchange_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Exchange Url"},"exchange_secret_header":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Exchange Secret Header","default":"X-API-KEY"},"exchange_secret_format":{"type":"string","maxLength":128,"minLength":8,"pattern":"^[^{}]*\\{secret\\}[^{}]*$","title":"Exchange Secret Format","default":"{secret}"},"exchange_param_headers":{"items":{"$ref":"#/components/schemas/ExchangeHeaderMapping"},"type":"array","maxItems":20,"title":"Exchange Param Headers"},"exchange_token_field":{"type":"string","maxLength":256,"minLength":1,"title":"Exchange Token Field","default":"token"},"exchange_expires_in_field":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Exchange Expires In Field"},"exchange_default_ttl_seconds":{"type":"integer","minimum":120,"title":"Exchange Default Ttl Seconds","default":3600},"api_key_value":{"anyOf":[{"$ref":"#/components/schemas/SecretInput"},{"type":"null"}]},"bearer_token_value":{"anyOf":[{"$ref":"#/components/schemas/SecretInput"},{"type":"null"}]},"client_secret_value":{"anyOf":[{"$ref":"#/components/schemas/SecretInput"},{"type":"null"}]},"private_key_value":{"anyOf":[{"$ref":"#/components/schemas/SecretInput"},{"type":"null"}]},"exchange_secret_value":{"anyOf":[{"$ref":"#/components/schemas/SecretInput"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["type"],"title":"AuthConfigWithSecrets","description":"AuthConfig that accepts inline secret values for auto-provisioning.\n\nPlatform-api writes the supplied value to SSM at the canonical\n``/{env}/integration-secrets/{workspace_id}/{integration_id}/{suffix}``\npath. Callers MUST NOT submit ``*_ssm_param_path`` fields — those\nare computed by the resolver, not stored on the model. ``extra='forbid'``\ncatches any drift so we surface 422 instead of silently dropping."},"ExchangeHeaderMapping":{"properties":{"header_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Header Name"},"param_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9_\\-]+$","title":"Param Name"},"consume":{"type":"boolean","title":"Consume","default":true},"required":{"type":"boolean","title":"Required","default":true}},"type":"object","required":["header_name","param_name"],"title":"ExchangeHeaderMapping","description":"One header on a token-exchange request, sourced from a request param.\n\nUsed by ``bearer_token_exchange`` auth type. Each mapping declares which\nrequest param feeds which exchange-call header. The same param values\nalso form the per-call cache key, so distinct (e.g.) user_ids yield\ndistinct cached tokens.\n\nExamples:\n    ``ExchangeHeaderMapping(header_name=\"X-USER-ID\", param_name=\"user_id\")``\n    ``ExchangeHeaderMapping(header_name=\"X-Org-ID\", param_name=\"org_id\")``"},"SecretInput":{"properties":{"value":{"type":"string","maxLength":8192,"minLength":1,"title":"Value"}},"type":"object","required":["value"],"title":"SecretInput","description":"Inline secret value — auto-provisioned to SSM on create/update.\n\nBounded to 8192 chars: large enough for a PEM RSA-4096 private key\nplus a short cert chain, small enough that an adversary cannot\npush a 100 MB \"secret\" through to SSM."},"EndpointConfig":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","default":"POST"},"path":{"type":"string","title":"Path"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","default":{}},"response_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Response Mapping"},"response_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Response Filter"},"result_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Template"},"result_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Key"},"max_result_length":{"type":"integer","title":"Max Result Length","default":0},"retry_config":{"$ref":"#/components/schemas/RetryConfig","default":{"max_retries":2,"retry_on_status":[429,502,503,504]}},"result_delivery":{"type":"string","enum":["interrupt","queue"],"title":"Result Delivery","default":"interrupt"},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","default":{}},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","default":"json"},"request_transform":{"anyOf":[{"$ref":"#/components/schemas/RequestTransform"},{"type":"null"}]}},"type":"object","required":["name","description","path"],"title":"EndpointConfig","description":"Configuration for a single integration endpoint."},"RetryConfig":{"properties":{"max_retries":{"type":"integer","title":"Max Retries","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","title":"Retry On Status","default":[429,502,503,504]}},"type":"object","title":"RetryConfig","description":"Retry configuration for an endpoint."},"RequestTransform":{"properties":{"inject":{"additionalProperties":{"type":"string"},"type":"object","maxProperties":20,"title":"Inject"},"wrap_params_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Wrap Params Key"}},"type":"object","title":"RequestTransform","description":"Transforms outbound request body before sending to the integration endpoint.\n\nApplied after path-param substitution and auth-header resolution, right\nbefore the HTTP call.  Mirror of the response-side pipeline\n(``response_filter`` / ``result_key`` / ``result_template``).\n\nInject targets the **outermost** dict: when combined with\n``wrap_params_key``, injected fields sit alongside the wrapper key,\nnever inside the wrapped sub-dict."},"IntegrationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Integration ID"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace ID"},"name":{"type":"string","title":"Name","description":"Slug-like identifier"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name"},"protocol":{"type":"string","enum":["rest","desktop"],"title":"Protocol","description":"Communication protocol"},"base_url":{"type":"string","title":"Base Url","description":"Base URL for REST integrations","default":""},"auth":{"anyOf":[{"$ref":"#/components/schemas/AuthConfig"},{"type":"null"}],"description":"Authentication configuration"},"endpoints":{"items":{"$ref":"#/components/schemas/EndpointConfig"},"type":"array","title":"Endpoints","description":"Configured endpoints"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active"},"builtin":{"type":"boolean","title":"Builtin","description":"Whether this is a system-provided integration","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the integration was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the integration was last updated"}},"type":"object","required":["id","workspace_id","name","display_name","protocol","enabled","created_at","updated_at"],"title":"IntegrationResponse"},"AuthConfig":{"properties":{"type":{"type":"string","enum":["api_key_header","bearer_token","oauth2_client_credentials","json_token_exchange","oauth2_jwt_bearer","bearer_token_exchange"],"title":"Type"},"header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header Name"},"token_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Url"},"client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"token_request_client_id_field":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Token Request Client Id Field"},"token_request_client_secret_field":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Token Request Client Secret Field"},"token_response_path":{"anyOf":[{"type":"string","maxLength":512,"minLength":1},{"type":"null"}],"title":"Token Response Path"},"assertion_issuer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Issuer"},"assertion_subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Subject"},"assertion_audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Audience"},"token_lifetime_seconds":{"type":"integer","title":"Token Lifetime Seconds","default":3600},"assertion_scopes_in_jwt":{"type":"boolean","title":"Assertion Scopes In Jwt","default":false},"exchange_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Exchange Url"},"exchange_secret_header":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Exchange Secret Header","default":"X-API-KEY"},"exchange_secret_format":{"type":"string","maxLength":128,"minLength":8,"pattern":"^[^{}]*\\{secret\\}[^{}]*$","title":"Exchange Secret Format","default":"{secret}"},"exchange_param_headers":{"items":{"$ref":"#/components/schemas/ExchangeHeaderMapping"},"type":"array","maxItems":20,"title":"Exchange Param Headers"},"exchange_token_field":{"type":"string","maxLength":256,"minLength":1,"title":"Exchange Token Field","default":"token"},"exchange_expires_in_field":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Exchange Expires In Field"},"exchange_default_ttl_seconds":{"type":"integer","minimum":120,"title":"Exchange Default Ttl Seconds","default":3600}},"type":"object","required":["type"],"title":"AuthConfig","description":"Authentication configuration for an integration.\n\nSupports api_key_header, bearer_token, oauth2_client_credentials,\njson_token_exchange, oauth2_jwt_bearer, and bearer_token_exchange."}}},"paths":{"/v1/{workspace_id}/integrations":{"post":{"tags":["Integrations"],"summary":"Create an integration","description":"Create a new external API integration in a workspace. Requires `Integration.create` permission.","operationId":"create-integration","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateIntegrationRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Workspace not found."},"409":{"description":"Integration name already taken in this workspace."},"422":{"description":"Invalid request body."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Get an integration

> Retrieve an integration by ID. Requires \`Integration.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"IntegrationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Integration ID"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace ID"},"name":{"type":"string","title":"Name","description":"Slug-like identifier"},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name"},"protocol":{"type":"string","enum":["rest","desktop"],"title":"Protocol","description":"Communication protocol"},"base_url":{"type":"string","title":"Base Url","description":"Base URL for REST integrations","default":""},"auth":{"anyOf":[{"$ref":"#/components/schemas/AuthConfig"},{"type":"null"}],"description":"Authentication configuration"},"endpoints":{"items":{"$ref":"#/components/schemas/EndpointConfig"},"type":"array","title":"Endpoints","description":"Configured endpoints"},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active"},"builtin":{"type":"boolean","title":"Builtin","description":"Whether this is a system-provided integration","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the integration was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the integration was last updated"}},"type":"object","required":["id","workspace_id","name","display_name","protocol","enabled","created_at","updated_at"],"title":"IntegrationResponse"},"AuthConfig":{"properties":{"type":{"type":"string","enum":["api_key_header","bearer_token","oauth2_client_credentials","json_token_exchange","oauth2_jwt_bearer","bearer_token_exchange"],"title":"Type"},"header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Header Name"},"token_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token Url"},"client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"token_request_client_id_field":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Token Request Client Id Field"},"token_request_client_secret_field":{"anyOf":[{"type":"string","maxLength":256,"minLength":1},{"type":"null"}],"title":"Token Request Client Secret Field"},"token_response_path":{"anyOf":[{"type":"string","maxLength":512,"minLength":1},{"type":"null"}],"title":"Token Response Path"},"assertion_issuer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Issuer"},"assertion_subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Subject"},"assertion_audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assertion Audience"},"token_lifetime_seconds":{"type":"integer","title":"Token Lifetime Seconds","default":3600},"assertion_scopes_in_jwt":{"type":"boolean","title":"Assertion Scopes In Jwt","default":false},"exchange_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Exchange Url"},"exchange_secret_header":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Exchange Secret Header","default":"X-API-KEY"},"exchange_secret_format":{"type":"string","maxLength":128,"minLength":8,"pattern":"^[^{}]*\\{secret\\}[^{}]*$","title":"Exchange Secret Format","default":"{secret}"},"exchange_param_headers":{"items":{"$ref":"#/components/schemas/ExchangeHeaderMapping"},"type":"array","maxItems":20,"title":"Exchange Param Headers"},"exchange_token_field":{"type":"string","maxLength":256,"minLength":1,"title":"Exchange Token Field","default":"token"},"exchange_expires_in_field":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Exchange Expires In Field"},"exchange_default_ttl_seconds":{"type":"integer","minimum":120,"title":"Exchange Default Ttl Seconds","default":3600}},"type":"object","required":["type"],"title":"AuthConfig","description":"Authentication configuration for an integration.\n\nSupports api_key_header, bearer_token, oauth2_client_credentials,\njson_token_exchange, oauth2_jwt_bearer, and bearer_token_exchange."},"ExchangeHeaderMapping":{"properties":{"header_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Header Name"},"param_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9_\\-]+$","title":"Param Name"},"consume":{"type":"boolean","title":"Consume","default":true},"required":{"type":"boolean","title":"Required","default":true}},"type":"object","required":["header_name","param_name"],"title":"ExchangeHeaderMapping","description":"One header on a token-exchange request, sourced from a request param.\n\nUsed by ``bearer_token_exchange`` auth type. Each mapping declares which\nrequest param feeds which exchange-call header. The same param values\nalso form the per-call cache key, so distinct (e.g.) user_ids yield\ndistinct cached tokens.\n\nExamples:\n    ``ExchangeHeaderMapping(header_name=\"X-USER-ID\", param_name=\"user_id\")``\n    ``ExchangeHeaderMapping(header_name=\"X-Org-ID\", param_name=\"org_id\")``"},"EndpointConfig":{"properties":{"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","default":"POST"},"path":{"type":"string","title":"Path"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","default":{}},"response_mapping":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Response Mapping"},"response_filter":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Response Filter"},"result_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Template"},"result_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Key"},"max_result_length":{"type":"integer","title":"Max Result Length","default":0},"retry_config":{"$ref":"#/components/schemas/RetryConfig","default":{"max_retries":2,"retry_on_status":[429,502,503,504]}},"result_delivery":{"type":"string","enum":["interrupt","queue"],"title":"Result Delivery","default":"interrupt"},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","default":{}},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","default":"json"},"request_transform":{"anyOf":[{"$ref":"#/components/schemas/RequestTransform"},{"type":"null"}]}},"type":"object","required":["name","description","path"],"title":"EndpointConfig","description":"Configuration for a single integration endpoint."},"RetryConfig":{"properties":{"max_retries":{"type":"integer","title":"Max Retries","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","title":"Retry On Status","default":[429,502,503,504]}},"type":"object","title":"RetryConfig","description":"Retry configuration for an endpoint."},"RequestTransform":{"properties":{"inject":{"additionalProperties":{"type":"string"},"type":"object","maxProperties":20,"title":"Inject"},"wrap_params_key":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Wrap Params Key"}},"type":"object","title":"RequestTransform","description":"Transforms outbound request body before sending to the integration endpoint.\n\nApplied after path-param substitution and auth-header resolution, right\nbefore the HTTP call.  Mirror of the response-side pipeline\n(``response_filter`` / ``result_key`` / ``result_template``).\n\nInject targets the **outermost** dict: when combined with\n``wrap_params_key``, injected fields sit alongside the wrapper key,\nnever inside the wrapped sub-dict."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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/IntegrationResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Integration not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete an integration

> Delete an integration. Requires \`Integration.delete\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/v1/{workspace_id}/integrations/{integration_id}":{"delete":{"tags":["Integrations"],"summary":"Delete an integration","description":"Delete an 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"},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Integration not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Test an integration endpoint

> Execute an integration endpoint with test parameters and return the full response pipeline breakdown. Requires \`Integration.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"TestEndpointRequest":{"properties":{"params":{"additionalProperties":true,"type":"object","title":"Params","default":{}}},"type":"object","title":"TestEndpointRequest"},"TestEndpointResponse":{"properties":{"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"HTTP status code from the endpoint"},"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 endpoint"},"after_filter":{"title":"After Filter","description":"Response after filter transformations"},"after_mapping":{"title":"After Mapping","description":"Response after field mapping"},"final_result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Final Result","description":"Final processed result"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the request failed"}},"type":"object","title":"TestEndpointResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_name}/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_name","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Name"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestEndpointRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestEndpointResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Integration not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/integrations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.