> 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/developer-guide/platform-api/workspaces/use-cases.md). # Use Cases & Bindings Use cases define how a workspace uses a specific communication channel, and service bindings connect each use case to the platform service that handles its conversations. Each use case ties an approved channel setup to a named purpose - for example, an outbound voice use case for appointment reminders or an email use case for transactional notifications. Use case lifecycle is managed through the separately authenticated channel management API with the `use-case:write` scope on the target channel setup. Those lifecycle operations are not published in the Platform API OpenAPI document; the Platform workspace list, ownership, and binding operations are embedded below. See [Channel Manager](/developer-guide/platform-api/conversations/channel-manager.md). ## Create a Use Case Create a use case through the channel management API. The request body is a discriminated union on the `channel` field: `inbound_voice`, `outbound_voice`, `ringless_voicemail`, and `sms` use cases associate a telephony setup, `imessage` use cases associate an iMessage setup, and `email` use cases associate an email setup plus a sender email address and email type (`transactional` or `marketing`). **Scope required:** `use-case:write` on the target setup ```http POST /v1/use-case Authorization: Bearer Content-Type: application/json ``` ## List Use Cases List use cases with optional filters by entity name, channel, and setup ID. Filtering by `setup_id` requires `channel` to also be specified. **Permission required:** Channel.view {% openapi src="" path="/v1/{workspace\_id}/use-cases" method="get" %} {% endopenapi %} ## Delete a Use Case Delete a use case by ID through the channel management API. Returns 409 while phone numbers or lines are still assigned to the use case - unassign them first. **Scope required:** `use-case:write` on the target setup ```http DELETE /v1/use-case/{use_case_id} Authorization: Bearer ``` ## Ownership A workspace claims ownership of a channel-manager use case before binding it to a service. Claiming requires the Channel.ManageOwnership permission (admin tier), is idempotent (re-claiming an already-owned use case returns 200), and returns 409 if another workspace already owns the use case. Releasing ownership returns 409 while any service still binds the use case - unbind first. ### List Owned Use Cases {% openapi src="" path="/v1/{workspace\_id}/use-cases/ownership" method="get" %} {% endopenapi %} ### Get Use Case Ownership {% openapi src="" path="/v1/{workspace\_id}/use-cases/{use\_case\_id}/ownership" method="get" %} {% endopenapi %} ### Claim Use Case Ownership {% openapi src="" path="/v1/{workspace\_id}/use-cases/{use\_case\_id}/ownership" method="put" %} {% endopenapi %} ### Release Use Case Ownership {% openapi src="" path="/v1/{workspace\_id}/use-cases/{use\_case\_id}/ownership" method="delete" %} {% endopenapi %} ## Service Binding A use case can be bound to a platform service. A binding is unique per workspace for a given service and channel pair: only one use case may bind a given (service, channel) at a time. ### Bind a Service Upserts a binding for the use case. If the use case already has a binding, the prior binding is replaced. A different use case cannot bind a service and channel pair that is already bound. **Permission required:** Channel.create {% openapi src="" path="/v1/{workspace\_id}/use-cases/{use\_case\_id}/service-binding" method="put" %} {% endopenapi %} ### Unbind a Service Soft-unbinds the use case from its service. Fails if no live binding exists for the use case. **Permission required:** Channel.delete {% openapi src="" path="/v1/{workspace\_id}/use-cases/{use\_case\_id}/service-binding" method="delete" %} {% endopenapi %} ### Get the Service Binding Returns the current service binding for the use case. Fails if no binding exists for the use case. **Permission required:** Channel.view {% openapi src="" path="/v1/{workspace\_id}/use-cases/{use\_case\_id}/service-binding" method="get" %} {% endopenapi %} --- # 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/developer-guide/platform-api/workspaces/use-cases.md?ask=&goal= ``` `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.