> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/api-reference/readme/platform/integrations.md).

# Integrations

## List 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.

```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},"src__routes__integrations__list_integrations__Response":{"properties":{"items":{"items":{"$ref":"#/components/schemas/RestIntegrationResponse"},"type":"array","title":"Items","description":"The integrations matching the request filters."},"has_more":{"type":"boolean","title":"Has More","description":"Whether there are more integrations to retrieve."},"continuation_token":{"title":"Continuation Token","description":"Opaque token for the next page. Null when there are no more results."}},"type":"object","required":["items","has_more"],"title":"Response"},"RestIntegrationResponse":{"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, immutable post-create."},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active."},"managed":{"type":"boolean","title":"Managed","description":"Whether the integration is system-managed and 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`` = no approval required;\n``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint.","default":"none"},"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."},"kind":{"type":"string","const":"rest","title":"Kind","description":"Discriminator.","default":"rest"},"base_url":{"type":"string","title":"Base Url","description":"Base URL for REST integrations."},"auth":{"anyOf":[{"$ref":"#/components/schemas/StaticHeaderAuthDict"},{"$ref":"#/components/schemas/OAuth2ClientCredentialsAuthDict"},{"$ref":"#/components/schemas/OAuth2JwtBearerAuthDict"},{"$ref":"#/components/schemas/CustomTokenExchangeAuthDict"},{"type":"null"}],"title":"Auth","description":"Authentication configuration (lib TypedDict union)."},"endpoint_count":{"type":"integer","title":"Endpoint Count","description":"Number of configured endpoints. Fetch the full list via GET /endpoints."}},"type":"object","required":["id","workspace_id","name","display_name","enabled","created_at","updated_at","base_url","endpoint_count"],"title":"RestIntegrationResponse","description":"REST variant — base URL, auth config, endpoint count."},"StaticHeaderAuthDict":{"properties":{"type":{"type":"string","const":"static_header","title":"Type"},"header_name":{"type":"string","title":"Header Name"}},"type":"object","required":["type","header_name"],"title":"StaticHeaderAuthDict","description":"Static workspace-level secret used verbatim as a single header value.\n\nReplaces legacy ``api_key_header`` and ``bearer_token`` — bearer is just\n``header_name=\"Authorization\"`` with the SSM secret holding ``\"Bearer <token>\"``."},"OAuth2ClientCredentialsAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method"}},"type":"object","required":["type","token_url","client_id","scopes","client_auth_method"],"title":"OAuth2ClientCredentialsAuthDict","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4."},"OAuth2JwtBearerAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer"},"assertion_audience":{"type":"string","title":"Assertion Audience"},"assertion_subject":{"type":"string","title":"Assertion Subject"},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds"},"include_iat":{"type":"boolean","title":"Include Iat"},"include_jti":{"type":"boolean","title":"Include Jti"},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims"}},"type":"object","required":["type","token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_lifetime_seconds","include_iat","include_jti","assertion_algorithm","assertion_usage","scopes","extra_claims"],"title":"OAuth2JwtBearerAuthDict","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` selects the flow: § 2.1 (JWT as authorization grant) or\n§ 2.2 (JWT as client authentication / private_key_jwt)."},"CustomTokenExchangeAuthDict":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type"},"exchange_url":{"type":"string","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding"},"static_headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Headers"},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields"},"param_headers":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Headers"},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Body Fields"},"response_token_path":{"type":"string","title":"Response Token Path"},"identity_bindings":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Bindings"},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values"}},"type":"object","required":["type","exchange_url","body_encoding","static_headers","static_body_fields","param_headers","param_body_fields","response_token_path","identity_bindings"],"title":"CustomTokenExchangeAuthDict","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nDownstream call always receives ``Authorization: Bearer {token}``. No\nin-process caching — every call mints fresh."},"ParamValueDict":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueDict","description":"Routing target for one per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthDict.param_headers`` / ``param_body_fields``."}}},"paths":{"/v1/{workspace_id}/integrations":{"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`\n(direction prefix REQUIRED). Allowed fields: ``name``, ``created_at``, ``updated_at``.\nDefault: ``-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`\n(direction prefix REQUIRED). Allowed fields: ``name``, ``created_at``, ``updated_at``.\nDefault: ``-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"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"422":{"description":"Query parameter failed validation or continuation_token is unparseable."}}}}}}
```

## Create a REST integration

> Create a new REST integration in a workspace. Endpoints are added separately via \`POST /integrations/{integration\_id}/endpoints\`. 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":{"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.\nRequired 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\nrequired; ``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint.","default":"none"}},"type":"object","required":["name","display_name","base_url"],"title":"Request","description":"Create body — REST only."},"NameString":{"type":"string","maxLength":256,"minLength":1},"StaticHeaderAuthRequest":{"properties":{"type":{"type":"string","const":"static_header","title":"Type","default":"static_header"},"header_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Header Name","description":"Outbound header name (RFC 7230 tchar)."}},"type":"object","required":["header_name"],"title":"StaticHeaderAuthRequest","description":"Static workspace-level secret used verbatim as a single header value."},"OAuth2ClientCredentialsAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type","default":"oauth2_client_credentials"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method","description":"RFC 6749 § 2.3.1: ``basic`` sends client_id+secret as HTTP Basic auth; ``body`` sends them in the form body.","default":"basic"}},"type":"object","required":["token_url","client_id"],"title":"OAuth2ClientCredentialsAuthRequest","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4.\n\nStrict RFC 6749 § 4.4.2 access token request: ``grant_type`` + optional\n``scope``. Client authentication (RFC 6749 § 2.3.1) is orthogonal —\n``client_auth_method`` picks between HTTP Basic auth and form-body\ncredentials. RFC 8707 ``resource`` and non-standard ``audience`` extensions\nare NOT supported here — add them back when a vendor needs one."},"OAuth2JwtBearerAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type","default":"oauth2_jwt_bearer"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer","description":"RFC 7523 ``iss`` claim — typically the service-account email or client_id."},"assertion_audience":{"type":"string","title":"Assertion Audience","description":"RFC 7523 ``aud`` claim — typically the token_url."},"assertion_subject":{"type":"string","title":"Assertion Subject","description":"RFC 7523 § 3 ``sub`` claim — MUST be present. For service-account flows\nwhere the client is its own subject, set to the same value as ``assertion_issuer``.\nUse a different value only for delegation / impersonation grants."},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds","default":3600},"include_iat":{"type":"boolean","title":"Include Iat","description":"RFC 7523 § 3 item 6 — ``iat`` claim set to mint time. Most IdPs (Google, Azure)\nrequire it for anti-replay; leave True unless a specific vendor rejects it.","default":true},"include_jti":{"type":"boolean","title":"Include Jti","description":"When True, generate a fresh ``jti`` (anti-replay) on every mint.","default":true},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm","default":"RS256"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage","description":"RFC 7523 flow selector — required; the caller must pick a flow.\n``authorization_grant`` (§ 2.1) sends the JWT as ``assertion`` under\n``grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer``.\n``client_authentication`` (§ 2.2, the ``private_key_jwt`` method) sends it as\n``client_assertion`` + ``client_assertion_type`` under ``grant_type=client_credentials``\n— required by Epic / SMART Backend Services."},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes","description":"RFC 7523 § 2.1 ``scope`` form-body parameter. Vendors that put scopes inside\nthe JWT instead (Google service accounts) use ``extra_claims = {\"scope\": \"...\"}``\nand leave this empty."},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims","description":"RFC 7523 § 3 item 8 — arbitrary additional JWT claims (e.g. Google's\n``scope`` claim, Azure's tenant claim). Merged BEFORE the required claims so\nIdP-specific extensions can't override ``iss`` / ``sub`` / ``aud`` / ``exp`` /\n``iat`` / ``nbf`` / ``jti``.","default":{}}},"type":"object","required":["token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_usage"],"title":"OAuth2JwtBearerAuthRequest","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` (required) selects the flow: § 2.1 (JWT as authorization\ngrant) or § 2.2 (JWT as client authentication / private_key_jwt)."},"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``\nfor nested fields, or ``/foo`` for a root-level field). Values may contain ``{secret}``\nplaceholder.","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\nat dispatch. A bound param is dropped from the LLM-facing tool schema and injected from the\nverified session context (never model-supplied), closing the per-user-identity impersonation hole.\nKeys 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.\n\nOnly ``external_user.subject_key`` bindings may carry test values. Runtime\ndispatch 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\n(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.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nPath-shaped fields (``response_token_path``, ``static_body_fields`` keys,\n``param_body_fields`` keys) MUST be valid RFC 6901 JSON Pointer — one\nsyntax throughout."},"ParamValueRequest":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueRequest","description":"Routing target for a single per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthRequest.param_headers`` / ``param_body_fields``."},"RestIntegrationResponse":{"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, immutable post-create."},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active."},"managed":{"type":"boolean","title":"Managed","description":"Whether the integration is system-managed and 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`` = no approval required;\n``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint.","default":"none"},"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."},"kind":{"type":"string","const":"rest","title":"Kind","description":"Discriminator.","default":"rest"},"base_url":{"type":"string","title":"Base Url","description":"Base URL for REST integrations."},"auth":{"anyOf":[{"$ref":"#/components/schemas/StaticHeaderAuthDict"},{"$ref":"#/components/schemas/OAuth2ClientCredentialsAuthDict"},{"$ref":"#/components/schemas/OAuth2JwtBearerAuthDict"},{"$ref":"#/components/schemas/CustomTokenExchangeAuthDict"},{"type":"null"}],"title":"Auth","description":"Authentication configuration (lib TypedDict union)."},"endpoint_count":{"type":"integer","title":"Endpoint Count","description":"Number of configured endpoints. Fetch the full list via GET /endpoints."}},"type":"object","required":["id","workspace_id","name","display_name","enabled","created_at","updated_at","base_url","endpoint_count"],"title":"RestIntegrationResponse","description":"REST variant — base URL, auth config, endpoint count."},"StaticHeaderAuthDict":{"properties":{"type":{"type":"string","const":"static_header","title":"Type"},"header_name":{"type":"string","title":"Header Name"}},"type":"object","required":["type","header_name"],"title":"StaticHeaderAuthDict","description":"Static workspace-level secret used verbatim as a single header value.\n\nReplaces legacy ``api_key_header`` and ``bearer_token`` — bearer is just\n``header_name=\"Authorization\"`` with the SSM secret holding ``\"Bearer <token>\"``."},"OAuth2ClientCredentialsAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method"}},"type":"object","required":["type","token_url","client_id","scopes","client_auth_method"],"title":"OAuth2ClientCredentialsAuthDict","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4."},"OAuth2JwtBearerAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer"},"assertion_audience":{"type":"string","title":"Assertion Audience"},"assertion_subject":{"type":"string","title":"Assertion Subject"},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds"},"include_iat":{"type":"boolean","title":"Include Iat"},"include_jti":{"type":"boolean","title":"Include Jti"},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims"}},"type":"object","required":["type","token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_lifetime_seconds","include_iat","include_jti","assertion_algorithm","assertion_usage","scopes","extra_claims"],"title":"OAuth2JwtBearerAuthDict","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` selects the flow: § 2.1 (JWT as authorization grant) or\n§ 2.2 (JWT as client authentication / private_key_jwt)."},"CustomTokenExchangeAuthDict":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type"},"exchange_url":{"type":"string","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding"},"static_headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Headers"},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields"},"param_headers":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Headers"},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Body Fields"},"response_token_path":{"type":"string","title":"Response Token Path"},"identity_bindings":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Bindings"},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values"}},"type":"object","required":["type","exchange_url","body_encoding","static_headers","static_body_fields","param_headers","param_body_fields","response_token_path","identity_bindings"],"title":"CustomTokenExchangeAuthDict","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nDownstream call always receives ``Authorization: Bearer {token}``. No\nin-process caching — every call mints fresh."},"ParamValueDict":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueDict","description":"Routing target for one per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthDict.param_headers`` / ``param_body_fields``."}}},"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"}}}},"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"}}]}}}}
```

## Approve a pending integration-write approval

> 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.

```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":{"IntegrationApprovalResponse":{"properties":{"status":{"type":"string","enum":["granted","rejected"],"title":"Status"},"conversation_id":{"type":"string","maxLength":256,"minLength":1,"title":"Conversation Id"}},"type":"object","required":["status","conversation_id"],"title":"IntegrationApprovalResponse","description":"Resolution outcome for a pending integration-write approval."},"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/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"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Conversation not found in this workspace."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited."}}}}}}
```

## Reject a pending integration-write approval

> 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.

```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":{"IntegrationRejectRequest":{"properties":{"reason":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Reason"}},"type":"object","title":"IntegrationRejectRequest","description":"Reject body — optional free-text reason surfaced to the agent."},"IntegrationApprovalResponse":{"properties":{"status":{"type":"string","enum":["granted","rejected"],"title":"Status"},"conversation_id":{"type":"string","maxLength":256,"minLength":1,"title":"Conversation Id"}},"type":"object","required":["status","conversation_id"],"title":"IntegrationApprovalResponse","description":"Resolution outcome for a pending integration-write approval."},"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/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"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Conversation not found in this workspace."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited."}}}}}}
```

## 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":{"RestIntegrationResponse":{"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, immutable post-create."},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active."},"managed":{"type":"boolean","title":"Managed","description":"Whether the integration is system-managed and 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`` = no approval required;\n``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint.","default":"none"},"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."},"kind":{"type":"string","const":"rest","title":"Kind","description":"Discriminator.","default":"rest"},"base_url":{"type":"string","title":"Base Url","description":"Base URL for REST integrations."},"auth":{"anyOf":[{"$ref":"#/components/schemas/StaticHeaderAuthDict"},{"$ref":"#/components/schemas/OAuth2ClientCredentialsAuthDict"},{"$ref":"#/components/schemas/OAuth2JwtBearerAuthDict"},{"$ref":"#/components/schemas/CustomTokenExchangeAuthDict"},{"type":"null"}],"title":"Auth","description":"Authentication configuration (lib TypedDict union)."},"endpoint_count":{"type":"integer","title":"Endpoint Count","description":"Number of configured endpoints. Fetch the full list via GET /endpoints."}},"type":"object","required":["id","workspace_id","name","display_name","enabled","created_at","updated_at","base_url","endpoint_count"],"title":"RestIntegrationResponse","description":"REST variant — base URL, auth config, endpoint count."},"StaticHeaderAuthDict":{"properties":{"type":{"type":"string","const":"static_header","title":"Type"},"header_name":{"type":"string","title":"Header Name"}},"type":"object","required":["type","header_name"],"title":"StaticHeaderAuthDict","description":"Static workspace-level secret used verbatim as a single header value.\n\nReplaces legacy ``api_key_header`` and ``bearer_token`` — bearer is just\n``header_name=\"Authorization\"`` with the SSM secret holding ``\"Bearer <token>\"``."},"OAuth2ClientCredentialsAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method"}},"type":"object","required":["type","token_url","client_id","scopes","client_auth_method"],"title":"OAuth2ClientCredentialsAuthDict","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4."},"OAuth2JwtBearerAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer"},"assertion_audience":{"type":"string","title":"Assertion Audience"},"assertion_subject":{"type":"string","title":"Assertion Subject"},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds"},"include_iat":{"type":"boolean","title":"Include Iat"},"include_jti":{"type":"boolean","title":"Include Jti"},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims"}},"type":"object","required":["type","token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_lifetime_seconds","include_iat","include_jti","assertion_algorithm","assertion_usage","scopes","extra_claims"],"title":"OAuth2JwtBearerAuthDict","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` selects the flow: § 2.1 (JWT as authorization grant) or\n§ 2.2 (JWT as client authentication / private_key_jwt)."},"CustomTokenExchangeAuthDict":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type"},"exchange_url":{"type":"string","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding"},"static_headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Headers"},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields"},"param_headers":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Headers"},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Body Fields"},"response_token_path":{"type":"string","title":"Response Token Path"},"identity_bindings":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Bindings"},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values"}},"type":"object","required":["type","exchange_url","body_encoding","static_headers","static_body_fields","param_headers","param_body_fields","response_token_path","identity_bindings"],"title":"CustomTokenExchangeAuthDict","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nDownstream call always receives ``Authorization: Bearer {token}``. No\nin-process caching — every call mints fresh."},"ParamValueDict":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueDict","description":"Routing target for one per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthDict.param_headers`` / ``param_body_fields``."},"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/RestIntegrationResponse"}}}},"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 a REST integration

> Delete a REST 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 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"},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Integration not found."},"409":{"description":"Integration is managed or referenced by one or more skills."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update a REST integration

> 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.

```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":{"src__routes__integrations__update_integration__Request":{"properties":{"display_name":{"$ref":"#/components/schemas/NameString","title":"Display Name","description":"New display name."},"base_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Base Url","description":"New base URL."},"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":"New auth config. Absent ⇒ untouched; null ⇒ clear; value ⇒ replace.\nIndependent of ``secret_value`` — updating ``auth`` alone reuses the\nexisting SSM secret."},"secret_value":{"type":"string","maxLength":8192,"minLength":1,"title":"Secret Value","description":"Rotate the per-integration SSM secret. Absent ⇒ existing secret\nuntouched; value ⇒ overwrite SSM at the canonical path. Explicit\n``null`` is rejected at validation — there is no \"clear the secret\"\noperation (clearing ``auth`` makes the secret unreachable; that's the\nintended clear path)."},"enabled":{"type":"boolean","title":"Enabled","description":"Toggle the integration on/off."},"managed":{"type":"boolean","title":"Managed","description":"Mark/unmark the integration as system-managed. Requires ``platform:admin`` scope."},"approval_policy":{"type":"string","enum":["none","writes","all"],"title":"Approval Policy","description":"Change the human-in-the-loop approval gate. ``none`` = no approval\nrequired; ``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint. Absent ⇒ untouched."}},"type":"object","title":"Request","description":"PATCH body — each field is sentinel-defaulted; absent ≠ explicit-null."},"NameString":{"type":"string","maxLength":256,"minLength":1},"StaticHeaderAuthRequest":{"properties":{"type":{"type":"string","const":"static_header","title":"Type","default":"static_header"},"header_name":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9!#$%&'*+\\-.^_`|~]+$","title":"Header Name","description":"Outbound header name (RFC 7230 tchar)."}},"type":"object","required":["header_name"],"title":"StaticHeaderAuthRequest","description":"Static workspace-level secret used verbatim as a single header value."},"OAuth2ClientCredentialsAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type","default":"oauth2_client_credentials"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method","description":"RFC 6749 § 2.3.1: ``basic`` sends client_id+secret as HTTP Basic auth; ``body`` sends them in the form body.","default":"basic"}},"type":"object","required":["token_url","client_id"],"title":"OAuth2ClientCredentialsAuthRequest","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4.\n\nStrict RFC 6749 § 4.4.2 access token request: ``grant_type`` + optional\n``scope``. Client authentication (RFC 6749 § 2.3.1) is orthogonal —\n``client_auth_method`` picks between HTTP Basic auth and form-body\ncredentials. RFC 8707 ``resource`` and non-standard ``audience`` extensions\nare NOT supported here — add them back when a vendor needs one."},"OAuth2JwtBearerAuthRequest":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type","default":"oauth2_jwt_bearer"},"token_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer","description":"RFC 7523 ``iss`` claim — typically the service-account email or client_id."},"assertion_audience":{"type":"string","title":"Assertion Audience","description":"RFC 7523 ``aud`` claim — typically the token_url."},"assertion_subject":{"type":"string","title":"Assertion Subject","description":"RFC 7523 § 3 ``sub`` claim — MUST be present. For service-account flows\nwhere the client is its own subject, set to the same value as ``assertion_issuer``.\nUse a different value only for delegation / impersonation grants."},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds","default":3600},"include_iat":{"type":"boolean","title":"Include Iat","description":"RFC 7523 § 3 item 6 — ``iat`` claim set to mint time. Most IdPs (Google, Azure)\nrequire it for anti-replay; leave True unless a specific vendor rejects it.","default":true},"include_jti":{"type":"boolean","title":"Include Jti","description":"When True, generate a fresh ``jti`` (anti-replay) on every mint.","default":true},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm","default":"RS256"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage","description":"RFC 7523 flow selector — required; the caller must pick a flow.\n``authorization_grant`` (§ 2.1) sends the JWT as ``assertion`` under\n``grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer``.\n``client_authentication`` (§ 2.2, the ``private_key_jwt`` method) sends it as\n``client_assertion`` + ``client_assertion_type`` under ``grant_type=client_credentials``\n— required by Epic / SMART Backend Services."},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes","description":"RFC 7523 § 2.1 ``scope`` form-body parameter. Vendors that put scopes inside\nthe JWT instead (Google service accounts) use ``extra_claims = {\"scope\": \"...\"}``\nand leave this empty."},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims","description":"RFC 7523 § 3 item 8 — arbitrary additional JWT claims (e.g. Google's\n``scope`` claim, Azure's tenant claim). Merged BEFORE the required claims so\nIdP-specific extensions can't override ``iss`` / ``sub`` / ``aud`` / ``exp`` /\n``iat`` / ``nbf`` / ``jti``.","default":{}}},"type":"object","required":["token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_usage"],"title":"OAuth2JwtBearerAuthRequest","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` (required) selects the flow: § 2.1 (JWT as authorization\ngrant) or § 2.2 (JWT as client authentication / private_key_jwt)."},"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``\nfor nested fields, or ``/foo`` for a root-level field). Values may contain ``{secret}``\nplaceholder.","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\nat dispatch. A bound param is dropped from the LLM-facing tool schema and injected from the\nverified session context (never model-supplied), closing the per-user-identity impersonation hole.\nKeys 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.\n\nOnly ``external_user.subject_key`` bindings may carry test values. Runtime\ndispatch 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\n(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.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nPath-shaped fields (``response_token_path``, ``static_body_fields`` keys,\n``param_body_fields`` keys) MUST be valid RFC 6901 JSON Pointer — one\nsyntax throughout."},"ParamValueRequest":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueRequest","description":"Routing target for a single per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthRequest.param_headers`` / ``param_body_fields``."},"RestIntegrationResponse":{"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, immutable post-create."},"display_name":{"type":"string","title":"Display Name","description":"Human-readable name."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether the integration is active."},"managed":{"type":"boolean","title":"Managed","description":"Whether the integration is system-managed and 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`` = no approval required;\n``writes`` = approval required for write-classified endpoints;\n``all`` = approval required for every endpoint.","default":"none"},"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."},"kind":{"type":"string","const":"rest","title":"Kind","description":"Discriminator.","default":"rest"},"base_url":{"type":"string","title":"Base Url","description":"Base URL for REST integrations."},"auth":{"anyOf":[{"$ref":"#/components/schemas/StaticHeaderAuthDict"},{"$ref":"#/components/schemas/OAuth2ClientCredentialsAuthDict"},{"$ref":"#/components/schemas/OAuth2JwtBearerAuthDict"},{"$ref":"#/components/schemas/CustomTokenExchangeAuthDict"},{"type":"null"}],"title":"Auth","description":"Authentication configuration (lib TypedDict union)."},"endpoint_count":{"type":"integer","title":"Endpoint Count","description":"Number of configured endpoints. Fetch the full list via GET /endpoints."}},"type":"object","required":["id","workspace_id","name","display_name","enabled","created_at","updated_at","base_url","endpoint_count"],"title":"RestIntegrationResponse","description":"REST variant — base URL, auth config, endpoint count."},"StaticHeaderAuthDict":{"properties":{"type":{"type":"string","const":"static_header","title":"Type"},"header_name":{"type":"string","title":"Header Name"}},"type":"object","required":["type","header_name"],"title":"StaticHeaderAuthDict","description":"Static workspace-level secret used verbatim as a single header value.\n\nReplaces legacy ``api_key_header`` and ``bearer_token`` — bearer is just\n``header_name=\"Authorization\"`` with the SSM secret holding ``\"Bearer <token>\"``."},"OAuth2ClientCredentialsAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_client_credentials","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"client_id":{"type":"string","title":"Client Id"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"client_auth_method":{"type":"string","enum":["basic","body"],"title":"Client Auth Method"}},"type":"object","required":["type","token_url","client_id","scopes","client_auth_method"],"title":"OAuth2ClientCredentialsAuthDict","description":"OAuth 2.0 Client Credentials Grant — RFC 6749 § 4.4."},"OAuth2JwtBearerAuthDict":{"properties":{"type":{"type":"string","const":"oauth2_jwt_bearer","title":"Type"},"token_url":{"type":"string","title":"Token Url"},"assertion_issuer":{"type":"string","title":"Assertion Issuer"},"assertion_audience":{"type":"string","title":"Assertion Audience"},"assertion_subject":{"type":"string","title":"Assertion Subject"},"assertion_lifetime_seconds":{"type":"integer","title":"Assertion Lifetime Seconds"},"include_iat":{"type":"boolean","title":"Include Iat"},"include_jti":{"type":"boolean","title":"Include Jti"},"assertion_algorithm":{"type":"string","enum":["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512"],"title":"Assertion Algorithm"},"assertion_usage":{"type":"string","enum":["authorization_grant","client_authentication"],"title":"Assertion Usage"},"scopes":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Scopes"},"extra_claims":{"additionalProperties":true,"type":"object","title":"Extra Claims"}},"type":"object","required":["type","token_url","assertion_issuer","assertion_audience","assertion_subject","assertion_lifetime_seconds","include_iat","include_jti","assertion_algorithm","assertion_usage","scopes","extra_claims"],"title":"OAuth2JwtBearerAuthDict","description":"OAuth 2.0 JWT Bearer Token — RFC 7523.\n\n``assertion_usage`` selects the flow: § 2.1 (JWT as authorization grant) or\n§ 2.2 (JWT as client authentication / private_key_jwt)."},"CustomTokenExchangeAuthDict":{"properties":{"type":{"type":"string","const":"custom_token_exchange","title":"Type"},"exchange_url":{"type":"string","title":"Exchange Url"},"body_encoding":{"type":"string","enum":["json","form"],"title":"Body Encoding"},"static_headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Headers"},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields"},"param_headers":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Headers"},"param_body_fields":{"additionalProperties":{"$ref":"#/components/schemas/ParamValueDict"},"type":"object","title":"Param Body Fields"},"response_token_path":{"type":"string","title":"Response Token Path"},"identity_bindings":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Bindings"},"identity_binding_test_values":{"additionalProperties":{"type":"string"},"type":"object","title":"Identity Binding Test Values"}},"type":"object","required":["type","exchange_url","body_encoding","static_headers","static_body_fields","param_headers","param_body_fields","response_token_path","identity_bindings"],"title":"CustomTokenExchangeAuthDict","description":"Pre-flight exchange that mints a downstream bearer.\n\nReplaces legacy ``json_token_exchange`` AND ``bearer_token_exchange``.\nDownstream call always receives ``Authorization: Bearer {token}``. No\nin-process caching — every call mints fresh."},"ParamValueDict":{"properties":{"param_name":{"type":"string","title":"Param Name"},"description":{"type":"string","title":"Description"}},"type":"object","required":["param_name","description"],"title":"ParamValueDict","description":"Routing target for one per-request parameter on the exchange call.\n\nPaired with a wire-name (header / body-field key) on\n``CustomTokenExchangeAuthDict.param_headers`` / ``param_body_fields``."}}},"paths":{"/v1/{workspace_id}/integrations/{integration_id}":{"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"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Integration not found."},"409":{"description":"Managed integration mutation blocked."},"422":{"description":"Invalid request body, NOT NULL field set to null, or no fields to update."}}}}}}
```

## List endpoints

> 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.

```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},"src__routes__integrations__list_endpoints__Response":{"properties":{"items":{"items":{"$ref":"#/components/schemas/EndpointResponse"},"type":"array","title":"Items","description":"The endpoints under this integration."},"has_more":{"type":"boolean","title":"Has More","description":"Whether there are more endpoints to retrieve."},"continuation_token":{"title":"Continuation Token","description":"Opaque token for the next page. Null when there are no more results."}},"type":"object","required":["items","has_more"],"title":"Response"},"EndpointResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs."},"name":{"type":"string","title":"Name","description":"Slug-like identifier. Unique per integration; immutable post-create."},"description":{"type":"string","title":"Description","description":"LLM-facing description."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","description":"HTTP method."},"path":{"type":"string","title":"Path","description":"URL path appended to the integration's base_url."},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON Schema for the tool's input arguments."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Static request headers."},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Static body fields merged into every request. Keys are RFC 6901 JSON Pointers\n(e.g. ``/meta/tool_name`` for nested, ``/foo`` for a root-level field)."},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","description":"Outbound body encoding.","default":"json"},"response_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Template","description":"Jinja template rendered against the parsed JSON response."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"description":"Opt-in typed artifact contract for external-user conversation delivery."},"max_response_length":{"type":"integer","title":"Max Response Length","description":"Truncate the final rendered string to this many chars.","default":0},"timeout_seconds":{"type":"number","title":"Timeout Seconds","description":"Per-request timeout.","default":30},"max_retries":{"type":"integer","title":"Max Retries","description":"Retry attempts on transient failures.","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","uniqueItems":true,"title":"Retry On Status","description":"HTTP status codes that trigger a retry."}},"type":"object","required":["id","name","description","method","path"],"title":"EndpointResponse","description":"Per-endpoint response (V186 flat shape)."},"ClientOutputConfig":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"json_schema":{"additionalProperties":true,"type":"object","title":"Json Schema"},"max_bytes":{"type":"integer","maximum":262144,"minimum":1,"title":"Max Bytes","default":262144},"external_user_enabled":{"type":"boolean","title":"External User Enabled","default":false}},"type":"object","required":["type","schema_version","json_schema"],"title":"ClientOutputConfig","description":"External-user-safe projection contract for a direct integration endpoint.\n\nThe endpoint's existing ``response_template`` performs the projection. With no\ntemplate, the parsed upstream JSON body is emitted unchanged."}}},"paths":{"/v1/{workspace_id}/integrations/{integration_id}/endpoints":{"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`\n(direction prefix REQUIRED). Allowed fields: ``name``, ``created_at``, ``updated_at``.\nDefault: ``-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`\n(direction prefix REQUIRED). Allowed fields: ``name``, ``created_at``, ``updated_at``.\nDefault: ``-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"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"422":{"description":"Query parameter failed validation or continuation_token is unparseable."}}}}}}
```

## Add an endpoint

> Add a new endpoint to a REST integration. Requires \`Integration.update\` 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":{"src__routes__integrations__create_endpoint__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, immutable post-create."},"description":{"type":"string","maxLength":2048,"minLength":1,"title":"Description","description":"LLM-facing description shown in the tool definition."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","description":"HTTP method.","default":"POST"},"path":{"type":"string","maxLength":2048,"minLength":1,"pattern":"^[^/]","title":"Path","description":"URL path appended to the integration's base_url. Must NOT start with `/` — the path is\njoined onto the base URL (which already carries the leading slash). Supports `{param}` substitution."},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON Schema describing the tool's input arguments."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Static headers merged into every request."},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Static body fields merged into POST/PUT/PATCH bodies. Keys are RFC 6901 JSON Pointers\n(e.g. ``/meta/tool_name`` for nested, ``/foo`` for a root-level field)."},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","description":"Outbound body encoding for write methods.","default":"json"},"response_template":{"anyOf":[{"type":"string","maxLength":16384},{"type":"null"}],"title":"Response Template","description":"Jinja template (sandboxed, StrictUndefined) rendered against the parsed JSON response."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"description":"Optional external-user-safe output contract. Uses response_template as its projection."},"max_response_length":{"type":"integer","maximum":1000000,"minimum":0,"title":"Max Response Length","description":"Truncate the rendered string to this many chars. 0 = no truncation.","default":0},"timeout_seconds":{"type":"number","maximum":600,"exclusiveMinimum":0,"title":"Timeout Seconds","description":"Per-request timeout.","default":30},"max_retries":{"type":"integer","maximum":10,"minimum":0,"title":"Max Retries","description":"Retry attempts on transient failures.","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","maxItems":20,"uniqueItems":true,"title":"Retry On Status","description":"HTTP status codes that trigger a retry."}},"type":"object","required":["name","description","path"],"title":"Request","description":"Add a new endpoint to a REST integration (V186 flat shape)."},"ClientOutputConfig":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"json_schema":{"additionalProperties":true,"type":"object","title":"Json Schema"},"max_bytes":{"type":"integer","maximum":262144,"minimum":1,"title":"Max Bytes","default":262144},"external_user_enabled":{"type":"boolean","title":"External User Enabled","default":false}},"type":"object","required":["type","schema_version","json_schema"],"title":"ClientOutputConfig","description":"External-user-safe projection contract for a direct integration endpoint.\n\nThe endpoint's existing ``response_template`` performs the projection. With no\ntemplate, the parsed upstream JSON body is emitted unchanged."},"EndpointResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs."},"name":{"type":"string","title":"Name","description":"Slug-like identifier. Unique per integration; immutable post-create."},"description":{"type":"string","title":"Description","description":"LLM-facing description."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","description":"HTTP method."},"path":{"type":"string","title":"Path","description":"URL path appended to the integration's base_url."},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON Schema for the tool's input arguments."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Static request headers."},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Static body fields merged into every request. Keys are RFC 6901 JSON Pointers\n(e.g. ``/meta/tool_name`` for nested, ``/foo`` for a root-level field)."},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","description":"Outbound body encoding.","default":"json"},"response_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Template","description":"Jinja template rendered against the parsed JSON response."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"description":"Opt-in typed artifact contract for external-user conversation delivery."},"max_response_length":{"type":"integer","title":"Max Response Length","description":"Truncate the final rendered string to this many chars.","default":0},"timeout_seconds":{"type":"number","title":"Timeout Seconds","description":"Per-request timeout.","default":30},"max_retries":{"type":"integer","title":"Max Retries","description":"Retry attempts on transient failures.","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","uniqueItems":true,"title":"Retry On Status","description":"HTTP status codes that trigger a retry."}},"type":"object","required":["id","name","description","method","path"],"title":"EndpointResponse","description":"Per-endpoint response (V186 flat shape)."}}},"paths":{"/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"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Integration not found."},"409":{"description":"Integration is managed or endpoint name already exists."},"422":{"description":"Invalid request body."}}}}}}
```

## Get an endpoint

> Get a single endpoint on a REST integration. 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":{"EndpointResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs."},"name":{"type":"string","title":"Name","description":"Slug-like identifier. Unique per integration; immutable post-create."},"description":{"type":"string","title":"Description","description":"LLM-facing description."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","description":"HTTP method."},"path":{"type":"string","title":"Path","description":"URL path appended to the integration's base_url."},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON Schema for the tool's input arguments."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Static request headers."},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Static body fields merged into every request. Keys are RFC 6901 JSON Pointers\n(e.g. ``/meta/tool_name`` for nested, ``/foo`` for a root-level field)."},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","description":"Outbound body encoding.","default":"json"},"response_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Template","description":"Jinja template rendered against the parsed JSON response."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"description":"Opt-in typed artifact contract for external-user conversation delivery."},"max_response_length":{"type":"integer","title":"Max Response Length","description":"Truncate the final rendered string to this many chars.","default":0},"timeout_seconds":{"type":"number","title":"Timeout Seconds","description":"Per-request timeout.","default":30},"max_retries":{"type":"integer","title":"Max Retries","description":"Retry attempts on transient failures.","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","uniqueItems":true,"title":"Retry On Status","description":"HTTP status codes that trigger a retry."}},"type":"object","required":["id","name","description","method","path"],"title":"EndpointResponse","description":"Per-endpoint response (V186 flat shape)."},"ClientOutputConfig":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"json_schema":{"additionalProperties":true,"type":"object","title":"Json Schema"},"max_bytes":{"type":"integer","maximum":262144,"minimum":1,"title":"Max Bytes","default":262144},"external_user_enabled":{"type":"boolean","title":"External User Enabled","default":false}},"type":"object","required":["type","schema_version","json_schema"],"title":"ClientOutputConfig","description":"External-user-safe projection contract for a direct integration endpoint.\n\nThe endpoint's existing ``response_template`` performs the projection. With no\ntemplate, the parsed upstream JSON body is emitted unchanged."},"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_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"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Endpoint not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete an endpoint

> Delete an endpoint from a REST integration. Requires \`Integration.update\` 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}/endpoints/{endpoint_id}":{"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"},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Endpoint not found."},"409":{"description":"Managed integration endpoint mutation blocked."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update an endpoint

> 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.

```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":{"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 Format"},"response_template":{"anyOf":[{"type":"string","maxLength":16384},{"type":"null"}],"title":"Response Template","description":"Jinja template; pass `null` to clear (the only DB-nullable column on this row)."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"title":"Client Output","description":"Client output contract; pass `null` to disable external artifact delivery."},"max_response_length":{"type":"integer","maximum":1000000,"minimum":0,"title":"Max Response Length"},"timeout_seconds":{"type":"number","maximum":600,"exclusiveMinimum":0,"title":"Timeout Seconds"},"max_retries":{"type":"integer","maximum":10,"minimum":0,"title":"Max Retries"},"retry_on_status":{"items":{"type":"integer"},"type":"array","maxItems":20,"uniqueItems":true,"title":"Retry On Status"}},"type":"object","title":"Request","description":"Patch an existing endpoint (V186 flat shape). ``name`` is immutable."},"ClientOutputConfig":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"json_schema":{"additionalProperties":true,"type":"object","title":"Json Schema"},"max_bytes":{"type":"integer","maximum":262144,"minimum":1,"title":"Max Bytes","default":262144},"external_user_enabled":{"type":"boolean","title":"External User Enabled","default":false}},"type":"object","required":["type","schema_version","json_schema"],"title":"ClientOutputConfig","description":"External-user-safe projection contract for a direct integration endpoint.\n\nThe endpoint's existing ``response_template`` performs the projection. With no\ntemplate, the parsed upstream JSON body is emitted unchanged."},"EndpointResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs."},"name":{"type":"string","title":"Name","description":"Slug-like identifier. Unique per integration; immutable post-create."},"description":{"type":"string","title":"Description","description":"LLM-facing description."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"title":"Method","description":"HTTP method."},"path":{"type":"string","title":"Path","description":"URL path appended to the integration's base_url."},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema","description":"JSON Schema for the tool's input arguments."},"headers":{"additionalProperties":{"type":"string"},"type":"object","title":"Headers","description":"Static request headers."},"static_body_fields":{"additionalProperties":{"type":"string"},"type":"object","title":"Static Body Fields","description":"Static body fields merged into every request. Keys are RFC 6901 JSON Pointers\n(e.g. ``/meta/tool_name`` for nested, ``/foo`` for a root-level field)."},"body_format":{"type":"string","enum":["json","form"],"title":"Body Format","description":"Outbound body encoding.","default":"json"},"response_template":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Template","description":"Jinja template rendered against the parsed JSON response."},"client_output":{"anyOf":[{"$ref":"#/components/schemas/ClientOutputConfig"},{"type":"null"}],"description":"Opt-in typed artifact contract for external-user conversation delivery."},"max_response_length":{"type":"integer","title":"Max Response Length","description":"Truncate the final rendered string to this many chars.","default":0},"timeout_seconds":{"type":"number","title":"Timeout Seconds","description":"Per-request timeout.","default":30},"max_retries":{"type":"integer","title":"Max Retries","description":"Retry attempts on transient failures.","default":2},"retry_on_status":{"items":{"type":"integer"},"type":"array","uniqueItems":true,"title":"Retry On Status","description":"HTTP status codes that trigger a retry."}},"type":"object","required":["id","name","description","method","path"],"title":"EndpointResponse","description":"Per-endpoint response (V186 flat shape)."}}},"paths":{"/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}":{"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"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Endpoint not found."},"409":{"description":"Managed integration endpoint mutation blocked."},"422":{"description":"Invalid request body, NOT NULL field set to null, or no fields to update."}}}}}}
```

## 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":{"src__routes__integrations__test_endpoint__Request":{"properties":{"params":{"additionalProperties":true,"type":"object","maxProperties":200,"title":"Params","description":"Tool arguments — the endpoint's ``input_schema``-declared inputs (path/query/body)."},"auth_params":{"additionalProperties":true,"type":"object","maxProperties":200,"title":"Auth Params","description":"Caller-supplied values for auth-routed params — the AUTH-ONLY channel.\n\nA ``custom_token_exchange`` integration declares ``param_headers`` /\n``param_body_fields`` whose ``param_name`` placeholders are NOT part of the\nendpoint's ``input_schema`` (they feed the pre-flight token exchange, not the\nendpoint call). They never reach the auth renderer through ``params`` alone, so\nthe renderer raised before any HTTP call. Supply them here to exercise the\nexchange end-to-end.\n\nPLA-980: these values resolve the token exchange but are STRIPPED before the\ndownstream endpoint request is built, so a pure-auth secret put here never\nechoes into the outbound body/query. A param that legitimately feeds BOTH the\nexchange and the endpoint call belongs in ``params`` (which keeps its existing\ndual-use behavior). ``auth_params`` is for pure-auth keys absent from ``params``;\non a key collision the ``params`` value wins (for both the exchange and the call)."}},"type":"object","title":"Request","description":"Inputs to ``POST /{integration_id}/endpoints/{endpoint_id}/test``."},"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."},"artifact":{"anyOf":[{"$ref":"#/components/schemas/ClientArtifact"},{"type":"null"}],"description":"Client artifact preview after JSON Schema and size validation."},"artifact_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Artifact Error","description":"Safe validation summary when client output is enabled but cannot be emitted."}},"type":"object","title":"Response","description":"Full breadcrumb returned by the test handler."},"ClientArtifact":{"properties":{"type":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_.-]*$","title":"Type"},"schema_version":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9_.-]*$","title":"Schema Version"},"payload":{"$ref":"#/components/schemas/ClientArtifactPayload"}},"type":"object","required":["type","schema_version","payload"],"title":"ClientArtifact","description":"A versioned JSON payload that a client can render as a product component."},"ClientArtifactPayload":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"}]},"JsonValue":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"items":{"$ref":"#/components/schemas/JsonValue"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"type":"object"},{"type":"null"}]},"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_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"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"Integration or endpoint not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.