---
title: "Request or change the workspace's capabilities"
method: POST
path: "/v1/organizations/{organization_id}/capabilities"
---

# Request or change the workspace's capabilities

`POST /v1/organizations/{organization_id}/capabilities`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/organizations/{organization_id}/capabilities`
- Auth: none declared

Select the use-case profiles, channels and destinations outbound should be authorized for, and accept the outbound policy by sending `policy_version`. The destination choice is explicit: `all_countries: true` (every destination except the sanctioned set) or `countries` naming at least one well-formed ISO 3166-1 alpha-2 code. A request with neither, with an empty list, or with an entry that is not a two-letter code is refused with 400 and nothing is written, so an active allowlist is never widened or emptied by a request that was refused. A verified workspace that accepts the policy and selects no custom profile is activated immediately within the profiles' default caps; anything else opens an Skysay review, and what is already active stays active until the review resolves. `calling_rules` cannot be set here; an operator records them on approval.

## Path parameters

- `organization_id` string, required

## Request body

- CapabilitiesRequest
  - `accepted_by` string
  - `all_countries` boolean: True authorizes every destination except the sanctioned set and ignores `countries`. Exactly one of `all_countries: true` or a non-empty `countries` is required; a request with neither is refused with 400 and nothing is written.
  - `channels` string[]: Omitted or empty falls back to the selected profiles' own channels.
  - `countries` string[]: The destination allowlist as ISO 3166-1 alpha-2 codes, used when `all_countries` is not true. An empty list is refused, and so is any entry that is not a well-formed two-letter code once normalized (the refusal names it). A few aliases are normalized (UAE, USA, UK).
  - `limits` object: Optional cap overrides; `live_call_concurrency` is always taken from the plan and never from this payload.
  - `metadata` object: Free-form notes merged into the record. `calling_rules` and the retired `metadata.operational_profile` key are refused here: calling rules are set during Skysay approval.
  - `policy_version` string: Accepting the outbound policy here is what makes immediate activation possible for a verified workspace; without it the request goes to review.
  - `profiles` string[], required: At least one valid use-case profile. Unknown keys are dropped; a selection with none left is refused.

## Response `201`

The stored record, active or pending review

- Capabilities: The workspace's capabilities record: what it may do outbound. One per workspace, always. `active` authorizes outbound within the listed profiles, channels, destinations and limits; every other status authorizes nothing new.
  - `all_countries` boolean: True: every destination except the sanctioned set is authorized and `countries` is empty. False: `countries` is the explicit allowlist. Activation through verification sets it true; a request chooses.
  - `approved_at` string, nullable
  - `approved_by` string: `self_serve` for a request approved within the catalog, the operator who approved it, or the verification door that activated it.
  - `approved_profiles` string[]
  - `calling_rules` object: The application calling rules an operator recorded on approval; `{}` when none apply.
  - `channels` string[]
  - `compliance_profile_id` string: The verified business profile the record was activated against; empty until verification clears.
  - `countries` string[]: The destination allowlist as ISO 3166-1 alpha-2 codes when `all_countries` is false. A call or text to any other country is held for review.
  - `created_at` string
  - `customer_visible_message` string: Server-composed status sentence for the workspace; display as-is.
  - `destination_restrictions` string[], nullable: Optional customer narrowing, intersected with current capabilities at admission. null means no additional customer restriction.
  - `destination_revision` integer: Revision required when saving optional destination restrictions.
  - `id` string
  - `limits` object: The profile caps projected into the workspace's risk controls at its last activation or approval (per-day/per-minute call and SMS counts, unique destinations, daily voice and wallet spend in minor units). Empty when no profile caps were projected. The caps enforced right now are the workspace's risk controls, which an operator may have changed since; `/v1/dashboard/capabilities` reports those.
  - `metadata` object
  - `organization_id` string
  - `policy_accepted_at` string, nullable
  - `policy_accepted_by` string
  - `policy_version` string
  - `status` 'not_activated' | 'pending_review' | 'active' | 'suspended'
  - `updated_at` string

## Other responses

- `400`: No valid profile selected, no destination chosen (all_countries or a non-empty countries list), an unrecognized country code, or calling_rules / the retired metadata.operational_profile supplied
- `403`: The credential does not belong to this organization
- `404`: Unknown organization

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/148c7e111260?raw)