# Use Cases

## List channel use cases

> List use cases with optional filters by entity\_name, channel, setup\_id. Requires Channel.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":{"UseCaseListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/UseCaseResponse"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"UseCaseListResponse"},"UseCaseResponse":{"properties":{"id":{"type":"string","title":"Id"},"channel":{"type":"string","title":"Channel"},"entity_name":{"type":"string","title":"Entity Name"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"setup_id":{"type":"string","title":"Setup Id"},"configuration_set_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Configuration Set Name"},"sender_email_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Email Address"},"email_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Type"},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","channel","entity_name","name","description","setup_id","created_at","updated_at"],"title":"UseCaseResponse"},"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}/use-cases":{"get":{"tags":["Use Cases"],"summary":"List channel use cases","description":"List use cases with optional filters by entity_name, channel, setup_id. Requires Channel.view permission.","operationId":"list-use-cases","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"entity_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"}},{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"enum":["outbound_voice","inbound_voice","ringless_voicemail","email"],"type":"string"},{"type":"null"}],"title":"Channel"}},{"name":"setup_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Setup Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UseCaseListResponse"}}}},"403":{"description":"Insufficient permissions."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create a channel use case

> Create a voice or email use case. Body is a discriminated union on the \`channel\` field. Requires Channel.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":{"VoiceUseCaseRequest":{"properties":{"channel":{"type":"string","enum":["outbound_voice","inbound_voice","ringless_voicemail"],"title":"Channel"},"entity_name":{"type":"string","maxLength":31,"minLength":1,"pattern":"^[A-Za-z\\- ]+$","title":"Entity Name"},"name":{"type":"string","maxLength":31,"minLength":1,"pattern":"^[A-Za-z\\- ]+$","title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"setup_id":{"type":"string","format":"uuid","title":"Setup Id"}},"type":"object","required":["channel","entity_name","name","setup_id"],"title":"VoiceUseCaseRequest"},"EmailUseCaseRequest":{"properties":{"channel":{"type":"string","const":"email","title":"Channel"},"entity_name":{"type":"string","maxLength":31,"minLength":1,"pattern":"^[A-Za-z\\- ]+$","title":"Entity Name"},"name":{"type":"string","maxLength":31,"minLength":1,"pattern":"^[A-Za-z\\- ]+$","title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Description"},"setup_id":{"type":"string","format":"uuid","title":"Setup Id"},"sender_email_address":{"type":"string","format":"email","title":"Sender Email Address"},"email_type":{"type":"string","enum":["transactional","marketing"],"title":"Email Type"}},"type":"object","required":["channel","entity_name","name","setup_id","sender_email_address","email_type"],"title":"EmailUseCaseRequest"},"UseCaseResponse":{"properties":{"id":{"type":"string","title":"Id"},"channel":{"type":"string","title":"Channel"},"entity_name":{"type":"string","title":"Entity Name"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"setup_id":{"type":"string","title":"Setup Id"},"configuration_set_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Configuration Set Name"},"sender_email_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sender Email Address"},"email_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Type"},"tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tier"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","channel","entity_name","name","description","setup_id","created_at","updated_at"],"title":"UseCaseResponse"},"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}/use-cases":{"post":{"tags":["Use Cases"],"summary":"Create a channel use case","description":"Create a voice or email use case. Body is a discriminated union on the `channel` field. Requires Channel.create permission.","operationId":"create-use-case","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/VoiceUseCaseRequest"},{"$ref":"#/components/schemas/EmailUseCaseRequest"}],"discriminator":{"propertyName":"channel","mapping":{"outbound_voice":"#/components/schemas/VoiceUseCaseRequest","inbound_voice":"#/components/schemas/VoiceUseCaseRequest","ringless_voicemail":"#/components/schemas/VoiceUseCaseRequest","email":"#/components/schemas/EmailUseCaseRequest"}},"title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UseCaseResponse"}}}},"403":{"description":"Insufficient permissions."},"404":{"description":"Setup not found."},"409":{"description":"Use case already exists or setup not approved."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"502":{"description":"Channel manager unavailable."},"504":{"description":"Channel manager timed out."}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Delete a channel use case

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

```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}/use-cases/{use_case_id}":{"delete":{"tags":["Use Cases"],"summary":"Delete a channel use case","description":"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.","operationId":"delete-use-case","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"use_case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Use Case Id"}}],"responses":{"204":{"description":"Successful Response"},"403":{"description":"Insufficient permissions."},"404":{"description":"Use case not found."},"409":{"description":"Use case is bound to a service, or still has active phone assignments."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"502":{"description":"Channel manager unavailable."},"504":{"description":"Channel manager timed out."}}}}}}
```

## Get the service binding for a use case

> Return the platform service this use case is bound to in this workspace, or 404 if unbound. Requires Channel.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":{"ServiceBindingResponse":{"properties":{"use_case_id":{"type":"string","format":"uuid","title":"Use Case Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"channel":{"type":"string","enum":["inbound_voice","outbound_voice","ringless_voicemail","email"],"title":"Channel"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["use_case_id","service_id","workspace_id","channel","created_at","updated_at"],"title":"ServiceBindingResponse"},"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}/use-cases/{use_case_id}/service-binding":{"get":{"tags":["Use Cases"],"summary":"Get the service binding for a use case","description":"Return the platform service this use case is bound to in this workspace, or 404 if unbound. Requires Channel.view permission.","operationId":"get-use-case-service-binding","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"use_case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Use Case Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceBindingResponse"}}}},"403":{"description":"Insufficient permissions."},"404":{"description":"Use case is not bound to a service in this workspace."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Bind a use case to a platform service

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

```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":{"ServiceBindingRequest":{"properties":{"service_id":{"type":"string","format":"uuid","title":"Service Id"}},"type":"object","required":["service_id"],"title":"ServiceBindingRequest"},"ServiceBindingResponse":{"properties":{"use_case_id":{"type":"string","format":"uuid","title":"Use Case Id"},"service_id":{"type":"string","format":"uuid","title":"Service Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"channel":{"type":"string","enum":["inbound_voice","outbound_voice","ringless_voicemail","email"],"title":"Channel"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["use_case_id","service_id","workspace_id","channel","created_at","updated_at"],"title":"ServiceBindingResponse"}}},"paths":{"/v1/{workspace_id}/use-cases/{use_case_id}/service-binding":{"put":{"tags":["Use Cases"],"summary":"Bind a use case to a platform service","description":"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.","operationId":"bind-use-case-to-service","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"use_case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Use Case Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceBindingRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceBindingResponse"}}}},"403":{"description":"Insufficient permissions."},"404":{"description":"Use case or service not found."},"409":{"description":"Service already has a different use case bound for this channel."},"422":{"description":"Unsupported use case channel."},"502":{"description":"Channel manager unavailable."},"504":{"description":"Channel manager timed out."}}}}}}
```

## Unbind a use case from its platform service

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

```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}/use-cases/{use_case_id}/service-binding":{"delete":{"tags":["Use Cases"],"summary":"Unbind a use case from its platform service","description":"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.","operationId":"unbind-use-case-from-service","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"use_case_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Use Case Id"}}],"responses":{"204":{"description":"Successful Response"},"403":{"description":"Insufficient permissions."},"404":{"description":"Use case is not bound to a service in this workspace."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

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

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

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

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

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