> For the complete documentation index, see [llms.txt](https://api-docs.helloaviary.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.helloaviary.ai/usecases.md).
# UseCases
Client use cases (clients\_use\_cases table).
## Get a use case (external projection)
> Returns the safe-for-external projection of a single use case. Sensitive\
> columns (live\_config, prompt\_extension, internal infra paths) are filtered out.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"UseCases","description":"Client use cases (clients_use_cases table)."}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"schemas":{"UseCaseExternalResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/UseCaseExternal"},"meta":{"$ref":"#/components/schemas/Meta"}}},"UseCaseExternal":{"type":"object","required":["id","external_id","ab_test_enabled","multi_entity","send_blank_files","frozen","rcd_enabled","created_at","updated_at"],"description":"External projection of a use case. Excludes raw config blobs, prompt\nextensions, internal infra paths, and Teams routing details.\n","properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","format":"uuid"},"use_case_name":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"description":"voice_agent_life_cycle enum value (string)."},"voice_agent_name":{"type":"string","nullable":true},"config_file":{"type":"string","nullable":true},"config_file_b":{"type":"string","nullable":true},"ab_test_enabled":{"type":"boolean"},"campaign_type":{"type":"string","nullable":true},"current_calls_status":{"type":"string","nullable":true},"multi_entity":{"type":"boolean"},"send_blank_files":{"type":"boolean"},"frozen":{"type":"boolean"},"is_text":{"type":"boolean","nullable":true},"rcd_enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Unique ID for this request. Echoed in the `X-Request-ID` response\nheader. Send this back to support to debug a specific call.\n"}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"ErrorCode":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","internal_error","field_not_editable","call_already_started"]}}},"paths":{"/v1/use-cases/{id}":{"get":{"summary":"Get a use case (external projection)","description":"Returns the safe-for-external projection of a single use case. Sensitive\ncolumns (live_config, prompt_extension, internal infra paths) are filtered out.\n","operationId":"getUseCaseExternalV1","tags":["UseCases"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UseCaseExternalResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Use case not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## List use cases (internal)
> Paginated list of every use case, optionally filtered by client. Returns\
> the full internal projection per row.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"UseCases","description":"Client use cases (clients_use_cases table)."},{"name":"Internal","description":"Internal-only endpoints. Forbidden for external client keys."}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"parameters":{"Limit":{"name":"limit","in":"query","required":false,"description":"Page size (1-500). Default 50.","schema":{"type":"integer","minimum":1,"maximum":500,"default":50}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor returned in `meta.page.next_cursor` from the previous page.\nCurrently the last id of the previous page; treat as opaque.\n","schema":{"type":"string"}}},"schemas":{"UseCaseListResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UseCaseInternal"}},"meta":{"$ref":"#/components/schemas/ListMeta"}}},"UseCaseInternal":{"type":"object","description":"Full internal projection of a use case, including raw live_config JSONB\nand prompt_extension. Internal scope only.\n","required":["id","external_id","ab_test_enabled","multi_entity","send_blank_files","frozen","prompt_extension","rcd_enabled","created_at","updated_at"],"properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","format":"uuid"},"client_id":{"type":"integer","format":"int64","nullable":true},"organization_id":{"type":"string","nullable":true},"use_case_name":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"description":"voice_agent_life_cycle enum value (string)"},"config_file":{"type":"string","nullable":true},"config_file_b":{"type":"string","nullable":true},"ab_test_enabled":{"type":"boolean"},"voice_agent_name":{"type":"string","nullable":true},"teams_representative_ids":{"type":"string","nullable":true},"teams_bot_type":{"type":"string","nullable":true},"direct_contact_email":{"type":"string","nullable":true},"output_file_sql":{"type":"string","nullable":true},"product_req_doc":{"type":"string","nullable":true},"campaign_type":{"type":"string","nullable":true},"current_calls_status":{"type":"string","nullable":true},"output_bucket_name":{"type":"string","nullable":true},"template":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"multi_entity":{"type":"boolean"},"send_blank_files":{"type":"boolean"},"frozen":{"type":"boolean"},"is_text":{"type":"boolean","nullable":true},"prompt_extension":{"type":"string"},"rcd_enabled":{"type":"boolean"},"live_config":{"nullable":true,"description":"Raw config JSONB"},"live_config_b":{"nullable":true,"description":"Raw B-variant config JSONB"}}},"ListMeta":{"type":"object","required":["request_id","page"],"properties":{"request_id":{"type":"string","format":"uuid"},"page":{"$ref":"#/components/schemas/PageInfo"}}},"PageInfo":{"type":"object","required":["limit"],"properties":{"limit":{"type":"integer"},"next_cursor":{"type":"string","description":"Pass back as `?cursor=` to get the next page. Absent on the last page."}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"ErrorCode":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","internal_error","field_not_editable","call_already_started"]}}},"paths":{"/internal/v1/use-cases":{"get":{"summary":"List use cases (internal)","description":"Paginated list of every use case, optionally filtered by client. Returns\nthe full internal projection per row.\n","operationId":"listUseCasesInternalV1","tags":["UseCases","Internal"],"parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"integer","format":"int64"}},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UseCaseListResponse"}}}},"400":{"description":"Bad query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"External key cannot reach internal scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## Get a use case (internal, full + organization)
> Returns every column on clients\_use\_cases plus the joined organization shape.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"UseCases","description":"Client use cases (clients_use_cases table)."},{"name":"Internal","description":"Internal-only endpoints. Forbidden for external client keys."}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"schemas":{"UseCaseInternalResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["use_case"],"properties":{"use_case":{"$ref":"#/components/schemas/UseCaseInternal"},"organization":{"allOf":[{"$ref":"#/components/schemas/Organization"}],"nullable":true}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"UseCaseInternal":{"type":"object","description":"Full internal projection of a use case, including raw live_config JSONB\nand prompt_extension. Internal scope only.\n","required":["id","external_id","ab_test_enabled","multi_entity","send_blank_files","frozen","prompt_extension","rcd_enabled","created_at","updated_at"],"properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","format":"uuid"},"client_id":{"type":"integer","format":"int64","nullable":true},"organization_id":{"type":"string","nullable":true},"use_case_name":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"description":"voice_agent_life_cycle enum value (string)"},"config_file":{"type":"string","nullable":true},"config_file_b":{"type":"string","nullable":true},"ab_test_enabled":{"type":"boolean"},"voice_agent_name":{"type":"string","nullable":true},"teams_representative_ids":{"type":"string","nullable":true},"teams_bot_type":{"type":"string","nullable":true},"direct_contact_email":{"type":"string","nullable":true},"output_file_sql":{"type":"string","nullable":true},"product_req_doc":{"type":"string","nullable":true},"campaign_type":{"type":"string","nullable":true},"current_calls_status":{"type":"string","nullable":true},"output_bucket_name":{"type":"string","nullable":true},"template":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"multi_entity":{"type":"boolean"},"send_blank_files":{"type":"boolean"},"frozen":{"type":"boolean"},"is_text":{"type":"boolean","nullable":true},"prompt_extension":{"type":"string"},"rcd_enabled":{"type":"boolean"},"live_config":{"nullable":true,"description":"Raw config JSONB"},"live_config_b":{"nullable":true,"description":"Raw B-variant config JSONB"}}},"Organization":{"type":"object","required":["id","name","bucket_name","domain_name","use_telnyx","has_teams_integration","created_at","updated_at","client_id"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"bucket_name":{"type":"string"},"domain_name":{"type":"string"},"aoss_endpoint":{"type":"string","nullable":true},"is_saml":{"type":"boolean","nullable":true},"aoss_collection_arn":{"type":"string","nullable":true},"connection_name":{"type":"string","nullable":true},"email_domain":{"type":"string","nullable":true},"use_telnyx":{"type":"boolean"},"description":{"type":"string","nullable":true},"has_teams_integration":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"client_id":{"type":"integer","format":"int64"}}},"Meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Unique ID for this request. Echoed in the `X-Request-ID` response\nheader. Send this back to support to debug a specific call.\n"}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"ErrorCode":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","internal_error","field_not_editable","call_already_started"]}}},"paths":{"/internal/v1/use-cases/{id}":{"get":{"summary":"Get a use case (internal, full + organization)","description":"Returns every column on clients_use_cases plus the joined organization shape.","operationId":"getUseCaseInternalV1","tags":["UseCases","Internal"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UseCaseInternalResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"External key cannot reach internal scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## Update a use case (internal)
> Partial update with a strict allowlist. Sending any field outside the\
> allowlist returns 400 \`field\_not\_editable\`. \`status\` must be a valid\
> \`voice\_agent\_life\_cycle\` enum value (validated against pg\_enum at runtime).
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"UseCases","description":"Client use cases (clients_use_cases table)."},{"name":"Internal","description":"Internal-only endpoints. Forbidden for external client keys."}],"servers":[{"url":"https://osprey.helloaviary.com/api","description":"Production"},{"url":"https://osprey-dev.helloaviary.com/api","description":"Development"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"}},"schemas":{"UseCasePatchRequest":{"type":"object","description":"Allowlist for internal PATCH. Sending any field outside this set returns\n400 with `code: field_not_editable`. Empty body returns 400.\n","properties":{"use_case_name":{"type":"string","nullable":true},"config_file":{"type":"string","nullable":true},"status":{"type":"string","description":"Must be a valid voice_agent_life_cycle enum value."},"voice_agent_name":{"type":"string","nullable":true},"teams_representative_ids":{"type":"string","nullable":true},"rcd_enabled":{"type":"boolean"}}},"UseCaseInternal":{"type":"object","description":"Full internal projection of a use case, including raw live_config JSONB\nand prompt_extension. Internal scope only.\n","required":["id","external_id","ab_test_enabled","multi_entity","send_blank_files","frozen","prompt_extension","rcd_enabled","created_at","updated_at"],"properties":{"id":{"type":"integer","format":"int64"},"external_id":{"type":"string","format":"uuid"},"client_id":{"type":"integer","format":"int64","nullable":true},"organization_id":{"type":"string","nullable":true},"use_case_name":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"description":"voice_agent_life_cycle enum value (string)"},"config_file":{"type":"string","nullable":true},"config_file_b":{"type":"string","nullable":true},"ab_test_enabled":{"type":"boolean"},"voice_agent_name":{"type":"string","nullable":true},"teams_representative_ids":{"type":"string","nullable":true},"teams_bot_type":{"type":"string","nullable":true},"direct_contact_email":{"type":"string","nullable":true},"output_file_sql":{"type":"string","nullable":true},"product_req_doc":{"type":"string","nullable":true},"campaign_type":{"type":"string","nullable":true},"current_calls_status":{"type":"string","nullable":true},"output_bucket_name":{"type":"string","nullable":true},"template":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"multi_entity":{"type":"boolean"},"send_blank_files":{"type":"boolean"},"frozen":{"type":"boolean"},"is_text":{"type":"boolean","nullable":true},"prompt_extension":{"type":"string"},"rcd_enabled":{"type":"boolean"},"live_config":{"nullable":true,"description":"Raw config JSONB"},"live_config_b":{"nullable":true,"description":"Raw B-variant config JSONB"}}},"Meta":{"type":"object","required":["request_id"],"properties":{"request_id":{"type":"string","format":"uuid","description":"Unique ID for this request. Echoed in the `X-Request-ID` response\nheader. Send this back to support to debug a specific call.\n"}}},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}},"ErrorCode":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","internal_error","field_not_editable","call_already_started"]}}},"paths":{"/internal/v1/use-cases/{id}":{"patch":{"summary":"Update a use case (internal)","description":"Partial update with a strict allowlist. Sending any field outside the\nallowlist returns 400 `field_not_editable`. `status` must be a valid\n`voice_agent_life_cycle` enum value (validated against pg_enum at runtime).\n","operationId":"patchUseCaseInternalV1","tags":["UseCases","Internal"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UseCasePatchRequest"}}}},"responses":{"200":{"description":"OK — returns the post-update use case (full internal projection).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/UseCaseInternal"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Bad body, unknown field, or invalid status enum","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"External key cannot reach internal scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
---
# 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://api-docs.helloaviary.ai/usecases.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.