Use Cases

List channel use cases

get

List use cases with optional filters by entity_name, channel, setup_id. Requires Channel.view permission.

Authorizations

BearerAuth

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

entity_nameany ofOptional

stringOptional

or

nullOptional

channelany ofOptional

string · enumOptionalPossible values:

or

nullOptional

setup_idany ofOptional

string · uuidOptional

or

nullOptional

Responses

200

Successful Response

application/json

403

Insufficient permissions.

422

Validation Error

application/json

get

/v1/{workspace_id}/use-cases

HTTPcURLJavaScriptPython

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

{
  "items": [
    {
      "id": "text",
      "channel": "text",
      "entity_name": "text",
      "name": "text",
      "description": "text",
      "setup_id": "text",
      "configuration_set_name": "text",
      "sender_email_address": "text",
      "email_type": "text",
      "tier": "text",
      "created_at": "2026-05-12T12:58:39.163Z",
      "updated_at": "2026-05-12T12:58:39.163Z"
    }
  ]
}

Create a channel use case

post

Create a voice or email use case. Body is a discriminated union on the channel field. Requires Channel.create permission.

Authorizations

BearerAuth

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

application/json

or

Responses

201

Successful Response

application/json

403

Insufficient permissions.

404

Setup not found.

409

Use case already exists or setup not approved.

422

Validation Error

application/json

502

Channel manager unavailable.

504

Channel manager timed out.

post

/v1/{workspace_id}/use-cases

HTTPcURLJavaScriptPython

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

{
  "channel": "outbound_voice",
  "entity_name": "text",
  "name": "text",
  "description": "text",
  "setup_id": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "id": "text",
  "channel": "text",
  "entity_name": "text",
  "name": "text",
  "description": "text",
  "setup_id": "text",
  "configuration_set_name": "text",
  "sender_email_address": "text",
  "email_type": "text",
  "tier": "text",
  "created_at": "2026-05-12T12:58:39.163Z",
  "updated_at": "2026-05-12T12:58:39.163Z"
}

Delete a channel use case

delete

Delete a use case. Refuses (409) while any service still binds the use case — call DELETE /use-cases/{id}/service-binding first. Also refuses if a Twilio use case still has phone-number assignments. Requires Channel.delete permission.

Authorizations

BearerAuth

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

use_case_idstring · uuidRequired

Responses

204

Successful Response

403

Insufficient permissions.

404

Use case not found.

409

Use case is bound to a service, or still has active phone assignments.

422

Validation Error

application/json

502

Channel manager unavailable.

504

Channel manager timed out.

delete

/v1/{workspace_id}/use-cases/{use_case_id}

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/use-cases/{use_case_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get the service binding for a use case

get

Return the platform service this use case is bound to in this workspace, or 404 if unbound. Requires Channel.view permission.

Authorizations

BearerAuth

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

use_case_idstring · uuidRequired

Responses

200

Successful Response

application/json

use_case_idstring · uuidRequired

service_idstring · uuidRequired

workspace_idstring · uuidRequired

channelstring · enumRequiredPossible values:

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

403

Insufficient permissions.

404

Use case is not bound to a service in this workspace.

422

Validation Error

application/json

get

/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/use-cases/{use_case_id}/service-binding HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "inbound_voice",
  "created_at": "2026-05-12T12:58:39.163Z",
  "updated_at": "2026-05-12T12:58:39.163Z"
}

Bind a use case to a platform service

put

Bind this use case to a platform service in the current workspace. PUT semantics — rebinding to a different service replaces the prior binding. Inbound webhook events for the use case will resolve to this workspace; outbound dispatch from the service will route through this use case for its channel. 409 if a different use case already binds the same (service, channel) pair. 404 if the service or use case is missing or belongs to another workspace. Requires Channel.create permission.

Authorizations

BearerAuth

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

use_case_idstring · uuidRequired

Body

application/json

service_idstring · uuidRequired

Responses

200

Successful Response

application/json

use_case_idstring · uuidRequired

service_idstring · uuidRequired

workspace_idstring · uuidRequired

channelstring · enumRequiredPossible values:

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

403

Insufficient permissions.

404

Use case or service not found.

409

Service already has a different use case bound for this channel.

422

Unsupported use case channel.

502

Channel manager unavailable.

504

Channel manager timed out.

put

/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

HTTPcURLJavaScriptPython

PUT /v1/{workspace_id}/use-cases/{use_case_id}/service-binding HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "service_id": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_id": "123e4567-e89b-12d3-a456-426614174000",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
  "channel": "inbound_voice",
  "created_at": "2026-05-12T12:58:39.163Z",
  "updated_at": "2026-05-12T12:58:39.163Z"
}

Unbind a use case from its platform service

delete

Release a use case from its bound service in this workspace. Soft-delete on the binding row. 404 if the use case is not currently bound (covers both 'never bound' and 'already unbound'). Requires Channel.delete permission.

Authorizations

BearerAuth

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

use_case_idstring · uuidRequired

Responses

204

Successful Response

403

Insufficient permissions.

404

Use case is not bound to a service in this workspace.

422

Validation Error

application/json

delete

/v1/{workspace_id}/use-cases/{use_case_id}/service-binding

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/use-cases/{use_case_id}/service-binding HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content