> 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/callactions.md).
# CallActions
Call lifecycle verbs — pause, unpause, freeze, unfreeze. These are thin wrappers around internal helpers; external callers infer `client_id` from their API key (the body must omit it), internal callers must supply it explicitly.
## Pause today's queued calls (external)
> Marks today's \`attempted\_call IS NULL\` rows as \`attempted\_call=true\`\
> so the dialer skips them, then flips matching active use cases'\
> \`current\_calls\_status\` to \`Stopped\`. With \`perma=true\`, also\
> disables every scheduling rule for the client's active use cases.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"CallActions","description":"Call lifecycle verbs — pause, unpause, freeze, unfreeze. These are\nthin wrappers around internal helpers; external callers infer\n`client_id` from their API key (the body must omit it), internal\ncallers must supply it explicitly.\n"}],"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":{"PauseExternalRequest":{"type":"object","description":"Body for POST /v1/calls/actions/{pause,unpause}. `client_id` is\nrejected here — external callers' client_id is inferred from\nthe API key. Empty body is allowed (pauses all of the client's\nactive use cases for today).\n","properties":{"use_case_id":{"type":"integer","format":"int64","nullable":true},"perma":{"type":"boolean","default":false,"description":"When true, also disables every scheduling rule for the client's active use cases (pause) or re-enables them (unpause)."}}},"PauseResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/PauseResponseBody"},"meta":{"$ref":"#/components/schemas/Meta"}}},"PauseResponseBody":{"type":"object","required":["calls_updated","use_cases_updated","scheduling_rules_updated","perma"],"description":"Counts of rows touched by the pause/unpause operation. Useful\nfor operator dashboards — silently returning {} would lose\nobservability.\n","properties":{"calls_updated":{"type":"integer","format":"int64"},"use_cases_updated":{"type":"integer","format":"int64"},"scheduling_rules_updated":{"type":"integer","format":"int64"},"perma":{"type":"boolean"}}},"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/calls/actions/pause":{"post":{"summary":"Pause today's queued calls (external)","description":"Marks today's `attempted_call IS NULL` rows as `attempted_call=true`\nso the dialer skips them, then flips matching active use cases'\n`current_calls_status` to `Stopped`. With `perma=true`, also\ndisables every scheduling rule for the client's active use cases.\n","operationId":"postPauseCallsExternalV1","tags":["CallActions"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseExternalRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseResponse"}}}},"400":{"description":"Bad body or client_id supplied externally","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## Unpause today's paused calls (external)
> Inverse of /pause. Stricter predicate on the calls UPDATE\
> (\`pid IS NULL AND connected IS NULL AND inbound IS NULL\`) so\
> rows the dialer has already touched are not re-queued.\
> With \`perma=true\`, also re-enables every scheduling rule for\
> the client's active use cases.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"CallActions","description":"Call lifecycle verbs — pause, unpause, freeze, unfreeze. These are\nthin wrappers around internal helpers; external callers infer\n`client_id` from their API key (the body must omit it), internal\ncallers must supply it explicitly.\n"}],"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":{"PauseExternalRequest":{"type":"object","description":"Body for POST /v1/calls/actions/{pause,unpause}. `client_id` is\nrejected here — external callers' client_id is inferred from\nthe API key. Empty body is allowed (pauses all of the client's\nactive use cases for today).\n","properties":{"use_case_id":{"type":"integer","format":"int64","nullable":true},"perma":{"type":"boolean","default":false,"description":"When true, also disables every scheduling rule for the client's active use cases (pause) or re-enables them (unpause)."}}},"PauseResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/PauseResponseBody"},"meta":{"$ref":"#/components/schemas/Meta"}}},"PauseResponseBody":{"type":"object","required":["calls_updated","use_cases_updated","scheduling_rules_updated","perma"],"description":"Counts of rows touched by the pause/unpause operation. Useful\nfor operator dashboards — silently returning {} would lose\nobservability.\n","properties":{"calls_updated":{"type":"integer","format":"int64"},"use_cases_updated":{"type":"integer","format":"int64"},"scheduling_rules_updated":{"type":"integer","format":"int64"},"perma":{"type":"boolean"}}},"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/calls/actions/unpause":{"post":{"summary":"Unpause today's paused calls (external)","description":"Inverse of /pause. Stricter predicate on the calls UPDATE\n(`pid IS NULL AND connected IS NULL AND inbound IS NULL`) so\nrows the dialer has already touched are not re-queued.\nWith `perma=true`, also re-enables every scheduling rule for\nthe client's active use cases.\n","operationId":"postUnpauseCallsExternalV1","tags":["CallActions"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseExternalRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseResponse"}}}},"400":{"description":"Bad body or client_id supplied externally","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## Freeze a use case (external)
> Sets \`frozen = true\` on the use case. Scoped to the caller's\
> client — out-of-tenant ids surface as 404 to avoid leaking\
> cross-tenant existence.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"CallActions","description":"Call lifecycle verbs — pause, unpause, freeze, unfreeze. These are\nthin wrappers around internal helpers; external callers infer\n`client_id` from their API key (the body must omit it), internal\ncallers must supply it explicitly.\n"}],"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":{"FreezeResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/FreezeResponseBody"},"meta":{"$ref":"#/components/schemas/Meta"}}},"FreezeResponseBody":{"type":"object","required":["use_case_id","frozen","use_cases_updated"],"properties":{"use_case_id":{"type":"integer","format":"int64"},"frozen":{"type":"boolean"},"use_cases_updated":{"type":"integer","format":"int64","description":"Rows touched by the UPDATE. 0 means the use case was already in the requested state or did not exist for this client."}}},"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}/freeze":{"post":{"summary":"Freeze a use case (external)","description":"Sets `frozen = true` on the use case. Scoped to the caller's\nclient — out-of-tenant ids surface as 404 to avoid leaking\ncross-tenant existence.\n","operationId":"postFreezeUseCaseExternalV1","tags":["CallActions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreezeResponse"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found (or out-of-tenant)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## Unfreeze a use case (external)
> Sets \`frozen = false\`. PATCH (not DELETE) because unfreeze is a\
> state transition, not a deletion of the freeze record.
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"CallActions","description":"Call lifecycle verbs — pause, unpause, freeze, unfreeze. These are\nthin wrappers around internal helpers; external callers infer\n`client_id` from their API key (the body must omit it), internal\ncallers must supply it explicitly.\n"}],"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":{"FreezeResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/FreezeResponseBody"},"meta":{"$ref":"#/components/schemas/Meta"}}},"FreezeResponseBody":{"type":"object","required":["use_case_id","frozen","use_cases_updated"],"properties":{"use_case_id":{"type":"integer","format":"int64"},"frozen":{"type":"boolean"},"use_cases_updated":{"type":"integer","format":"int64","description":"Rows touched by the UPDATE. 0 means the use case was already in the requested state or did not exist for this client."}}},"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}/freeze":{"patch":{"summary":"Unfreeze a use case (external)","description":"Sets `frozen = false`. PATCH (not DELETE) because unfreeze is a\nstate transition, not a deletion of the freeze record.\n","operationId":"patchFreezeUseCaseExternalV1","tags":["CallActions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreezeResponse"}}}},"401":{"description":"Missing or invalid X-Api-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found (or out-of-tenant)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## POST /internal/v1/calls/actions/pause
> Pause today's queued calls (internal)
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"CallActions","description":"Call lifecycle verbs — pause, unpause, freeze, unfreeze. These are\nthin wrappers around internal helpers; external callers infer\n`client_id` from their API key (the body must omit it), internal\ncallers must supply it explicitly.\n"},{"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":{"PauseInternalRequest":{"type":"object","required":["client_id"],"description":"Body for POST /internal/v1/calls/actions/{pause,unpause}.\n`client_id` is required because internal env-keys aren't tied\nto a single client.\n","properties":{"client_id":{"type":"integer","format":"int64"},"use_case_id":{"type":"integer","format":"int64","nullable":true},"perma":{"type":"boolean","default":false}}},"PauseResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/PauseResponseBody"},"meta":{"$ref":"#/components/schemas/Meta"}}},"PauseResponseBody":{"type":"object","required":["calls_updated","use_cases_updated","scheduling_rules_updated","perma"],"description":"Counts of rows touched by the pause/unpause operation. Useful\nfor operator dashboards — silently returning {} would lose\nobservability.\n","properties":{"calls_updated":{"type":"integer","format":"int64"},"use_cases_updated":{"type":"integer","format":"int64"},"scheduling_rules_updated":{"type":"integer","format":"int64"},"perma":{"type":"boolean"}}},"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/calls/actions/pause":{"post":{"summary":"Pause today's queued calls (internal)","operationId":"postPauseCallsInternalV1","tags":["CallActions","Internal"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseInternalRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseResponse"}}}},"400":{"description":"Bad body or missing client_id","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"}}}}}}}}}
```
## POST /internal/v1/calls/actions/unpause
> Unpause today's paused calls (internal)
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"CallActions","description":"Call lifecycle verbs — pause, unpause, freeze, unfreeze. These are\nthin wrappers around internal helpers; external callers infer\n`client_id` from their API key (the body must omit it), internal\ncallers must supply it explicitly.\n"},{"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":{"PauseInternalRequest":{"type":"object","required":["client_id"],"description":"Body for POST /internal/v1/calls/actions/{pause,unpause}.\n`client_id` is required because internal env-keys aren't tied\nto a single client.\n","properties":{"client_id":{"type":"integer","format":"int64"},"use_case_id":{"type":"integer","format":"int64","nullable":true},"perma":{"type":"boolean","default":false}}},"PauseResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/PauseResponseBody"},"meta":{"$ref":"#/components/schemas/Meta"}}},"PauseResponseBody":{"type":"object","required":["calls_updated","use_cases_updated","scheduling_rules_updated","perma"],"description":"Counts of rows touched by the pause/unpause operation. Useful\nfor operator dashboards — silently returning {} would lose\nobservability.\n","properties":{"calls_updated":{"type":"integer","format":"int64"},"use_cases_updated":{"type":"integer","format":"int64"},"scheduling_rules_updated":{"type":"integer","format":"int64"},"perma":{"type":"boolean"}}},"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/calls/actions/unpause":{"post":{"summary":"Unpause today's paused calls (internal)","operationId":"postUnpauseCallsInternalV1","tags":["CallActions","Internal"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseInternalRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PauseResponse"}}}},"400":{"description":"Bad body or missing client_id","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"}}}}}}}}}
```
## POST /internal/v1/use-cases/{id}/freeze
> Freeze a use case (internal)
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"CallActions","description":"Call lifecycle verbs — pause, unpause, freeze, unfreeze. These are\nthin wrappers around internal helpers; external callers infer\n`client_id` from their API key (the body must omit it), internal\ncallers must supply it explicitly.\n"},{"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":{"FreezeInternalRequest":{"type":"object","required":["client_id"],"description":"Body for internal freeze/unfreeze. The use_case_id comes from\nthe URL; client_id is required so the UPDATE is scoped tightly\nand a fat-fingered request can't freeze a different client's\nuse case that happens to share the id.\n","properties":{"client_id":{"type":"integer","format":"int64"}}},"FreezeResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/FreezeResponseBody"},"meta":{"$ref":"#/components/schemas/Meta"}}},"FreezeResponseBody":{"type":"object","required":["use_case_id","frozen","use_cases_updated"],"properties":{"use_case_id":{"type":"integer","format":"int64"},"frozen":{"type":"boolean"},"use_cases_updated":{"type":"integer","format":"int64","description":"Rows touched by the UPDATE. 0 means the use case was already in the requested state or did not exist for this client."}}},"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}/freeze":{"post":{"summary":"Freeze a use case (internal)","operationId":"postFreezeUseCaseInternalV1","tags":["CallActions","Internal"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreezeInternalRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreezeResponse"}}}},"400":{"description":"Bad body or missing client_id","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 for this client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
## PATCH /internal/v1/use-cases/{id}/freeze
> Unfreeze a use case (internal)
```json
{"openapi":"3.0.3","info":{"title":"Aviary v1 API (merged — Osprey v1 + legacy clientApi)","version":"1.0.0"},"tags":[{"name":"CallActions","description":"Call lifecycle verbs — pause, unpause, freeze, unfreeze. These are\nthin wrappers around internal helpers; external callers infer\n`client_id` from their API key (the body must omit it), internal\ncallers must supply it explicitly.\n"},{"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":{"FreezeInternalRequest":{"type":"object","required":["client_id"],"description":"Body for internal freeze/unfreeze. The use_case_id comes from\nthe URL; client_id is required so the UPDATE is scoped tightly\nand a fat-fingered request can't freeze a different client's\nuse case that happens to share the id.\n","properties":{"client_id":{"type":"integer","format":"int64"}}},"FreezeResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/FreezeResponseBody"},"meta":{"$ref":"#/components/schemas/Meta"}}},"FreezeResponseBody":{"type":"object","required":["use_case_id","frozen","use_cases_updated"],"properties":{"use_case_id":{"type":"integer","format":"int64"},"frozen":{"type":"boolean"},"use_cases_updated":{"type":"integer","format":"int64","description":"Rows touched by the UPDATE. 0 means the use case was already in the requested state or did not exist for this client."}}},"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}/freeze":{"patch":{"summary":"Unfreeze a use case (internal)","operationId":"patchFreezeUseCaseInternalV1","tags":["CallActions","Internal"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreezeInternalRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreezeResponse"}}}},"400":{"description":"Bad body or missing client_id","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 for this client","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/callactions.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.