Integrations

List integrations

get

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.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

enabledboolean · nullableOptional

Filter to integrations with this enabled flag. None matches both.

searchstring · min: 1 · max: 200 · nullableOptional

Substring match against name, display_name, or id (case-insensitive).

sort_bystring[]Optional

Sort axes. Repeated query param stacks left-to-right. Each entry is +field or -field (direction prefix REQUIRED). Allowed fields: name, created_at, updated_at. Default: -created_at. id is always appended as the final tiebreaker.

Default: []

limitinteger · max: 200Optional

The maximum number of integrations to return.

Default: 50

continuation_tokenanyOptional

Opaque token from a prior response. Pass back unchanged with the same sort_by to advance.

Responses

200

Successful Response

application/json

has_morebooleanRequired

Whether there are more integrations to retrieve.

continuation_tokenanyOptional

Opaque token for the next page. Null when there are no more results.

401

Missing or invalid API key.

403

Insufficient permissions.

422

Query parameter failed validation or continuation_token is unparseable.

get/v1/{workspace_id}/integrations

GET /v1/{workspace_id}/integrations HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "display_name": "text",
      "enabled": true,
      "managed": false,
      "approval_policy": "none",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "kind": "rest",
      "base_url": "text",
      "auth": {
        "type": "text",
        "header_name": "text"
      },
      "endpoint_count": 1
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Create a REST integration

post

Create a new REST integration in a workspace. Endpoints are added separately via POST /integrations/{integration_id}/endpoints. Requires Integration.create permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

Create body — REST only.

namestring · min: 2 · max: 128Required

Slug-like identifier, lowercase alphanumeric + hyphens/underscores. Immutable post-create.

Pattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$

display_namestring · min: 1 · max: 256Required

Human-readable name.

base_urlstring · uri · min: 1 · max: 2083Required

Base URL for the upstream REST API.

authone of · nullableOptional

Auth configuration. When set, secret_value is required.

or

or

or

secret_valuestring · min: 1 · max: 8192 · nullableOptional

Inline secret literal — auto-provisioned to the per-integration SSM path. Required when auth is set. Bounded to fit a PEM RSA-4096 key + cert chain.

enabledbooleanOptional

Whether the integration is active on create.

Default: true

managedbooleanOptional

Whether this is a system-managed integration protected from workspace CRUD.

Default: false

approval_policystring · enumOptional

Human-in-the-loop approval gate. none (default) = no approval required; writes = approval required for write-classified endpoints; all = approval required for every endpoint.

Default: nonePossible values:

Responses

201

Successful Response

application/json

REST variant — base URL, auth config, endpoint count.

idstring · uuidRequired

Integration ID.

workspace_idstring · uuidRequired

Workspace ID.

namestringRequired

Slug-like identifier, immutable post-create.

display_namestringRequired

Human-readable name.

enabledbooleanRequired

Whether the integration is active.

managedbooleanOptional

Whether the integration is system-managed and protected from workspace CRUD.

Default: false

approval_policystring · enumOptional

Human-in-the-loop approval gate. none = no approval required; writes = approval required for write-classified endpoints; all = approval required for every endpoint.

Default: nonePossible values:

created_atstring · date-timeRequired

When the integration was created.

updated_atstring · date-timeRequired

When the integration was last updated.

kindconst: restOptional

Discriminator.

Default: rest

base_urlstringRequired

Base URL for REST integrations.

authany of · nullableOptional

Authentication configuration (lib TypedDict union).

or

or

or

endpoint_countintegerRequired

Number of configured endpoints. Fetch the full list via GET /endpoints.

401

Missing or invalid API key.

403

Insufficient permissions.

404

Workspace not found.

409

Integration name already taken in this workspace.

422

Invalid request body.

post/v1/{workspace_id}/integrations

POST /v1/{workspace_id}/integrations HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 201

{
  "name": "text",
  "display_name": "text",
  "base_url": "https://example.com",
  "auth": {
    "type": "static_header",
    "header_name": "text"
  },
  "secret_value": "text",
  "enabled": true,
  "managed": false,
  "approval_policy": "none"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "display_name": "text",
  "enabled": true,
  "managed": false,
  "approval_policy": "none",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "kind": "rest",
  "base_url": "text",
  "auth": {
    "type": "text",
    "header_name": "text"
  },
  "endpoint_count": 1
}

Approve a pending integration-write approval

post

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.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

conversation_idstring · uuidRequired

Responses

200

Successful Response

application/json

Resolution outcome for a pending integration-write approval.

statusstring · enumRequiredPossible values:

conversation_idstring · min: 1 · max: 256Required

401

Missing or invalid API key.

403

Insufficient permissions.

404

Conversation not found in this workspace.

422

Validation Error

application/json

429

Rate limited.

post/v1/{workspace_id}/integrations/approvals/{conversation_id}/approve

POST /v1/{workspace_id}/integrations/approvals/{conversation_id}/approve HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "granted",
  "conversation_id": "text"
}

Reject a pending integration-write approval

post

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.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

conversation_idstring · uuidRequired

Body

Reject body — optional free-text reason surfaced to the agent.

reasonstring · max: 2000 · nullableOptional

Responses

200

Successful Response

application/json

Resolution outcome for a pending integration-write approval.

statusstring · enumRequiredPossible values:

conversation_idstring · min: 1 · max: 256Required

401

Missing or invalid API key.

403

Insufficient permissions.

404

Conversation not found in this workspace.

422

Validation Error

application/json

429

Rate limited.

post/v1/{workspace_id}/integrations/approvals/{conversation_id}/reject

POST /v1/{workspace_id}/integrations/approvals/{conversation_id}/reject HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "reason": "text"
}

{
  "status": "granted",
  "conversation_id": "text"
}

Get an integration

get

Retrieve an integration by ID. Requires Integration.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

Responses

200

Successful Response

application/json

REST variant — base URL, auth config, endpoint count.

idstring · uuidRequired

Integration ID.

workspace_idstring · uuidRequired

Workspace ID.

namestringRequired

Slug-like identifier, immutable post-create.

display_namestringRequired

Human-readable name.

enabledbooleanRequired

Whether the integration is active.

managedbooleanOptional

Whether the integration is system-managed and protected from workspace CRUD.

Default: false

approval_policystring · enumOptional

Human-in-the-loop approval gate. none = no approval required; writes = approval required for write-classified endpoints; all = approval required for every endpoint.

Default: nonePossible values:

created_atstring · date-timeRequired

When the integration was created.

updated_atstring · date-timeRequired

When the integration was last updated.

kindconst: restOptional

Discriminator.

Default: rest

base_urlstringRequired

Base URL for REST integrations.

authany of · nullableOptional

Authentication configuration (lib TypedDict union).

or

or

or

endpoint_countintegerRequired

Number of configured endpoints. Fetch the full list via GET /endpoints.

401

Missing or invalid API key.

403

Insufficient permissions.

404

Integration not found.

422

Validation Error

application/json

get/v1/{workspace_id}/integrations/{integration_id}

GET /v1/{workspace_id}/integrations/{integration_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "display_name": "text",
  "enabled": true,
  "managed": false,
  "approval_policy": "none",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "kind": "rest",
  "base_url": "text",
  "auth": {
    "type": "text",
    "header_name": "text"
  },
  "endpoint_count": 1
}

Delete a REST integration

delete

Delete a REST integration. Requires Integration.delete permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

Responses

204

Successful Response

No content

401

Missing or invalid API key.

403

Insufficient permissions.

404

Integration not found.

409

Integration is managed or referenced by one or more skills.

422

Validation Error

application/json

delete/v1/{workspace_id}/integrations/{integration_id}

DELETE /v1/{workspace_id}/integrations/{integration_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a REST integration

patch

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.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

Body

PATCH body — each field is sentinel-defaulted; absent ≠ explicit-null.

display_namestring · min: 1 · max: 256Optional

New display name.

base_urlstring · uri · min: 1 · max: 2083Optional

New base URL.

authone of · nullableOptional

New auth config. Absent ⇒ untouched; null ⇒ clear; value ⇒ replace. Independent of secret_value — updating auth alone reuses the existing SSM secret.

or

or

or

secret_valuestring · min: 1 · max: 8192Optional

Rotate the per-integration SSM secret. Absent ⇒ existing secret untouched; value ⇒ overwrite SSM at the canonical path. Explicit null is rejected at validation — there is no "clear the secret" operation (clearing auth makes the secret unreachable; that's the intended clear path).

enabledbooleanOptional

Toggle the integration on/off.

managedbooleanOptional

Mark/unmark the integration as system-managed. Requires platform:admin scope.

approval_policystring · enumOptional

Change the human-in-the-loop approval gate. none = no approval required; writes = approval required for write-classified endpoints; all = approval required for every endpoint. Absent ⇒ untouched.

Possible values:

Responses

200

Successful Response

application/json

REST variant — base URL, auth config, endpoint count.

idstring · uuidRequired

Integration ID.

workspace_idstring · uuidRequired

Workspace ID.

namestringRequired

Slug-like identifier, immutable post-create.

display_namestringRequired

Human-readable name.

enabledbooleanRequired

Whether the integration is active.

managedbooleanOptional

Whether the integration is system-managed and protected from workspace CRUD.

Default: false

approval_policystring · enumOptional

Human-in-the-loop approval gate. none = no approval required; writes = approval required for write-classified endpoints; all = approval required for every endpoint.

Default: nonePossible values:

created_atstring · date-timeRequired

When the integration was created.

updated_atstring · date-timeRequired

When the integration was last updated.

kindconst: restOptional

Discriminator.

Default: rest

base_urlstringRequired

Base URL for REST integrations.

authany of · nullableOptional

Authentication configuration (lib TypedDict union).

or

or

or

endpoint_countintegerRequired

Number of configured endpoints. Fetch the full list via GET /endpoints.

401

Missing or invalid API key.

403

Insufficient permissions.

404

Integration not found.

409

Managed integration mutation blocked.

422

Invalid request body, NOT NULL field set to null, or no fields to update.

patch/v1/{workspace_id}/integrations/{integration_id}

PATCH /v1/{workspace_id}/integrations/{integration_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 186

{
  "display_name": "text",
  "base_url": "https://example.com",
  "auth": {
    "type": "static_header",
    "header_name": "text"
  },
  "secret_value": "text",
  "enabled": true,
  "managed": true,
  "approval_policy": "none"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "display_name": "text",
  "enabled": true,
  "managed": false,
  "approval_policy": "none",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "kind": "rest",
  "base_url": "text",
  "auth": {
    "type": "text",
    "header_name": "text"
  },
  "endpoint_count": 1
}

List endpoints

get

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.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

Query parameters

searchstring · min: 1 · max: 200 · nullableOptional

Substring match against name or description (case-insensitive).

sort_bystring[]Optional

Sort axes. Repeated query param stacks left-to-right. Each entry is +field or -field (direction prefix REQUIRED). Allowed fields: name, created_at, updated_at. Default: -created_at. id is always appended as the final tiebreaker.

Default: []

limitinteger · max: 200Optional

The maximum number of endpoints to return.

Default: 50

continuation_tokenanyOptional

Opaque token from a prior response. Pass back unchanged with the same sort_by to advance.

Responses

200

Successful Response

application/json

has_morebooleanRequired

Whether there are more endpoints to retrieve.

continuation_tokenanyOptional

Opaque token for the next page. Null when there are no more results.

401

Missing or invalid API key.

403

Insufficient permissions.

422

Query parameter failed validation or continuation_token is unparseable.

get/v1/{workspace_id}/integrations/{integration_id}/endpoints

GET /v1/{workspace_id}/integrations/{integration_id}/endpoints HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "method": "GET",
      "path": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "static_body_fields": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "body_format": "json",
      "response_template": "text",
      "client_output": {
        "type": "text",
        "schema_version": "text",
        "json_schema": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "max_bytes": 262144,
        "external_user_enabled": false
      },
      "max_response_length": 0,
      "timeout_seconds": 30,
      "max_retries": 2,
      "retry_on_status": [
        1
      ]
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Add an endpoint

post

Add a new endpoint to a REST integration. Requires Integration.update permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

Body

Add a new endpoint to a REST integration (V186 flat shape).

namestring · min: 2 · max: 128Required

Slug-like identifier, immutable post-create.

Pattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$

descriptionstring · min: 1 · max: 2048Required

LLM-facing description shown in the tool definition.

methodstring · enumOptional

HTTP method.

Default: POSTPossible values:

pathstring · min: 1 · max: 2048Required

URL path appended to the integration's base_url. Must NOT start with / — the path is joined onto the base URL (which already carries the leading slash). Supports {param} substitution.

Pattern: ^[^/]

body_formatstring · enumOptional

Outbound body encoding for write methods.

Default: jsonPossible values:

response_templatestring · max: 16384 · nullableOptional

Jinja template (sandboxed, StrictUndefined) rendered against the parsed JSON response.

max_response_lengthinteger · max: 1000000Optional

Truncate the rendered string to this many chars. 0 = no truncation.

Default: 0

timeout_secondsnumber · max: 600Optional

Per-request timeout.

Default: 30

max_retriesinteger · max: 10Optional

Retry attempts on transient failures.

Default: 2

retry_on_statusinteger[] · max: 20Optional

HTTP status codes that trigger a retry.

Responses

201

Successful Response

application/json

Per-endpoint response (V186 flat shape).

idstring · uuidRequired

Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs.

namestringRequired

Slug-like identifier. Unique per integration; immutable post-create.

descriptionstringRequired

LLM-facing description.

methodstring · enumRequired

HTTP method.

Possible values:

pathstringRequired

URL path appended to the integration's base_url.

body_formatstring · enumOptional

Outbound body encoding.

Default: jsonPossible values:

response_templatestring · nullableOptional

Jinja template rendered against the parsed JSON response.

max_response_lengthintegerOptional

Truncate the final rendered string to this many chars.

Default: 0

timeout_secondsnumberOptional

Per-request timeout.

Default: 30

max_retriesintegerOptional

Retry attempts on transient failures.

Default: 2

retry_on_statusinteger[]Optional

HTTP status codes that trigger a retry.

401

Missing or invalid API key.

403

Insufficient permissions.

404

Integration not found.

409

Integration is managed or endpoint name already exists.

422

Invalid request body.

post/v1/{workspace_id}/integrations/{integration_id}/endpoints

POST /v1/{workspace_id}/integrations/{integration_id}/endpoints HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 510

{
  "name": "text",
  "description": "text",
  "method": "POST",
  "path": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "headers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "static_body_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "body_format": "json",
  "response_template": "text",
  "client_output": {
    "type": "text",
    "schema_version": "text",
    "json_schema": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "max_bytes": 262144,
    "external_user_enabled": false
  },
  "max_response_length": 0,
  "timeout_seconds": 30,
  "max_retries": 2,
  "retry_on_status": [
    1
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "method": "GET",
  "path": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "headers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "static_body_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "body_format": "json",
  "response_template": "text",
  "client_output": {
    "type": "text",
    "schema_version": "text",
    "json_schema": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "max_bytes": 262144,
    "external_user_enabled": false
  },
  "max_response_length": 0,
  "timeout_seconds": 30,
  "max_retries": 2,
  "retry_on_status": [
    1
  ]
}

Get an endpoint

get

Get a single endpoint on a REST integration. Requires Integration.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

endpoint_idstring · uuidRequired

Responses

200

Successful Response

application/json

Per-endpoint response (V186 flat shape).

idstring · uuidRequired

Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs.

namestringRequired

Slug-like identifier. Unique per integration; immutable post-create.

descriptionstringRequired

LLM-facing description.

methodstring · enumRequired

HTTP method.

Possible values:

pathstringRequired

URL path appended to the integration's base_url.

body_formatstring · enumOptional

Outbound body encoding.

Default: jsonPossible values:

response_templatestring · nullableOptional

Jinja template rendered against the parsed JSON response.

max_response_lengthintegerOptional

Truncate the final rendered string to this many chars.

Default: 0

timeout_secondsnumberOptional

Per-request timeout.

Default: 30

max_retriesintegerOptional

Retry attempts on transient failures.

Default: 2

retry_on_statusinteger[]Optional

HTTP status codes that trigger a retry.

401

Missing or invalid API key.

403

Insufficient permissions.

404

Endpoint not found.

422

Validation Error

application/json

get/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}

GET /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "method": "GET",
  "path": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "headers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "static_body_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "body_format": "json",
  "response_template": "text",
  "client_output": {
    "type": "text",
    "schema_version": "text",
    "json_schema": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "max_bytes": 262144,
    "external_user_enabled": false
  },
  "max_response_length": 0,
  "timeout_seconds": 30,
  "max_retries": 2,
  "retry_on_status": [
    1
  ]
}

Delete an endpoint

delete

Delete an endpoint from a REST integration. Requires Integration.update permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

endpoint_idstring · uuidRequired

Responses

204

Successful Response

No content

401

Missing or invalid API key.

403

Insufficient permissions.

404

Endpoint not found.

409

Managed integration endpoint mutation blocked.

422

Validation Error

application/json

delete/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}

DELETE /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update an endpoint

patch

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.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

endpoint_idstring · uuidRequired

Body

Patch an existing endpoint (V186 flat shape). name is immutable.

descriptionstring · min: 1 · max: 2048Optional

methodstring · enumOptionalPossible values:

pathstring · min: 1 · max: 2048Optional

URL path appended to the integration's base_url. Must NOT start with /.

Pattern: ^[^/]

body_formatstring · enumOptionalPossible values:

response_templatestring · max: 16384 · nullableOptional

Jinja template; pass null to clear (the only DB-nullable column on this row).

max_response_lengthinteger · max: 1000000Optional

timeout_secondsnumber · max: 600Optional

max_retriesinteger · max: 10Optional

retry_on_statusinteger[] · max: 20Optional

Responses

200

Successful Response

application/json

Per-endpoint response (V186 flat shape).

idstring · uuidRequired

Endpoint ID — stable, used in subsequent GET/PATCH/DELETE/test URLs.

namestringRequired

Slug-like identifier. Unique per integration; immutable post-create.

descriptionstringRequired

LLM-facing description.

methodstring · enumRequired

HTTP method.

Possible values:

pathstringRequired

URL path appended to the integration's base_url.

body_formatstring · enumOptional

Outbound body encoding.

Default: jsonPossible values:

response_templatestring · nullableOptional

Jinja template rendered against the parsed JSON response.

max_response_lengthintegerOptional

Truncate the final rendered string to this many chars.

Default: 0

timeout_secondsnumberOptional

Per-request timeout.

Default: 30

max_retriesintegerOptional

Retry attempts on transient failures.

Default: 2

retry_on_statusinteger[]Optional

HTTP status codes that trigger a retry.

401

Missing or invalid API key.

403

Insufficient permissions.

404

Endpoint not found.

409

Managed integration endpoint mutation blocked.

422

Invalid request body, NOT NULL field set to null, or no fields to update.

patch/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}

PATCH /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 494

{
  "description": "text",
  "method": "GET",
  "path": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "headers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "static_body_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "body_format": "json",
  "response_template": "text",
  "client_output": {
    "type": "text",
    "schema_version": "text",
    "json_schema": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "max_bytes": 262144,
    "external_user_enabled": false
  },
  "max_response_length": 1,
  "timeout_seconds": 1,
  "max_retries": 1,
  "retry_on_status": [
    1
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "description": "text",
  "method": "GET",
  "path": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "headers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "static_body_fields": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "body_format": "json",
  "response_template": "text",
  "client_output": {
    "type": "text",
    "schema_version": "text",
    "json_schema": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "max_bytes": 262144,
    "external_user_enabled": false
  },
  "max_response_length": 0,
  "timeout_seconds": 30,
  "max_retries": 2,
  "retry_on_status": [
    1
  ]
}

Test an integration endpoint

post

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

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

integration_idstring · uuidRequired

endpoint_idstring · uuidRequired

Body

Inputs to POST /{integration_id}/endpoints/{endpoint_id}/test.

Responses

200

Successful Response

application/json

Full breadcrumb returned by the test handler.

status_codeinteger · nullableOptional

HTTP status code from the upstream call.

duration_msnumberOptional

Request duration in milliseconds.

Default: 0

retriesintegerOptional

Number of retry attempts.

Default: 0

raw_responseanyOptional

Raw response body from the upstream call.

renderedstring · nullableOptional

Response after Jinja response_template rendering, pre-truncation.

final_resultstring · nullableOptional

Final processed result (rendered + truncated to max_response_length).

errorstring · nullableOptional

Error message if the request failed.

artifact_errorstring · nullableOptional

Safe validation summary when client output is enabled but cannot be emitted.

401

Missing or invalid API key.

403

Insufficient permissions.

404

Integration or endpoint not found.

422

Validation Error

application/json

post/v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}/test

POST /v1/{workspace_id}/integrations/{integration_id}/endpoints/{endpoint_id}/test HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "params": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "auth_params": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "status_code": 1,
  "duration_ms": 0,
  "retries": 0,
  "raw_response": null,
  "rendered": "text",
  "final_result": "text",
  "error": "text",
  "artifact": {
    "type": "text",
    "schema_version": "text",
    "payload": {
      "ANY_ADDITIONAL_PROPERTY": true
    }
  },
  "artifact_error": "text"
}