# Features

## Endpoints

- `POST /messaging/features/evaluate`: [Evaluate features](https://docs.polymorfa.com/api/features/evaluate-features)

## Evaluate features

`POST https://api.polymorfa.com/messaging/features/evaluate` (Messaging API)

Returns feature decisions for the authenticated team or project. Client credentials cannot access this operation. Machine requests do not record experiment exposure.

### Body

- `surface` (string, required, max length 100, pattern ^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$). Specifies surface for this schema.
- `keys` (array of string, required, max items 50, item max length 100, item pattern ^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$). Keys associated with this schema.
- `measurementAllowed` (boolean, deprecated). Deprecated. Has no effect on native operational experiment measurement. Default: `false`.
- `locale` (string). Specifies locale for this schema. Values: `en`, `pt-BR`. Default: `"en"`.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/features/evaluate" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "surface": "string",
  "keys": [
    "string"
  ]
}'
```

### Responses

#### 200

Feature decisions
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (array of object, required). Structured data carried by this object.
  - `decision` (object, required). Structured decision values for this data.
    - `key` (string, required, max length 100, pattern ^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$). Specifies key for this decision.
    - `version` (integer, required). Specifies version for this decision.
    - `available` (boolean, required). Whether this capability is available.
    - `enrolled` (boolean, required). Whether enrolled.
    - `variant` (string, required, nullable, deprecated). Deprecated. Always null; use experiments.
    - `experimentRevision` (integer, required, nullable, deprecated). Deprecated. Always null; use experiments.
    - `experimentAssigned` (boolean, required, deprecated). Deprecated. Always false; use experiments. Values: `false`.
  - `experiments` (array of object, required). Registered experiments. Evaluation does not record exposure.
    - `key` (string, required, max length 100, pattern ^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$). Specifies key for this experiment.
    - `variant` (string, required). Specifies variant for this experiment.
    - `revision` (integer, required, nullable, greater than 0). Specifies revision for this experiment.
    - `assigned` (boolean, required). Whether assigned.
  - `title` (string, required). Human-readable title shown to the recipient or operator.
  - `description` (string, required). Human-readable description of this resource.
  - `state` (string, required). Published access state. `opt_in` requires the team to accept `terms` before the feature is available. Values: `off`, `opt_in`, `on`.
  - `termsRevision` (string, required, nullable). Current terms revision while the feature is opt-in; null otherwise.
  - `terms` (string, required, nullable). Opt-in terms in the requested locale; null when the feature is not opt-in.
  - `withdrawal` (string, required, nullable). Specifies withdrawal for this data.
  - `enrollmentSource` (string, required, nullable). Who enabled an opt-in feature for the team: a team owner or admin, or Polymorfa. Null when not enrolled. Values: `customer`, `staff`.
  - `changedAt` (string (date-time), required, nullable, format date-time). When the team last joined or left this opt-in feature. Null when the team has never enrolled or the authenticated principal cannot read team enrollment attribution.
  - `changedBy` (object, required, nullable). Who last joined or left this opt-in feature for the team. Null when the team has never enrolled or the authenticated principal cannot read team enrollment attribution.
    - One of:
      - `member` (object).
        - `kind` (string, required). Kind discriminator for this object. Values: `member`.
        - `name` (string, required, nullable). Display name of the team member who made the change. Null when they have no display name or are no longer a member.
      - `staff` (object). The change was made by Polymorfa. Staff identity is never returned.
        - `kind` (string, required). Kind discriminator for this object. Values: `staff`.
  - `exposureToken` (string, required, nullable, deprecated). Deprecated. Always null.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": [
    {
      "decision": {
        "key": "string",
        "version": 0,
        "available": true,
        "enrolled": true,
        "variant": null,
        "experimentRevision": null,
        "experimentAssigned": false
      },
      "experiments": [
        {
          "key": "string",
          "variant": "string",
          "revision": 0,
          "assigned": true
        }
      ],
      "title": "string",
      "description": "string",
      "state": "off",
      "termsRevision": "string",
      "terms": "string",
      "withdrawal": "string",
      "enrollmentSource": "customer",
      "changedAt": "2026-09-22T12:00:00Z",
      "changedBy": {
        "kind": "member",
        "name": "string"
      },
      "exposureToken": null
    }
  ]
}
```

#### 400

Invalid feature request
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Authentication required
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Credential cannot access feature evaluation
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 413

Request exceeds 16 KiB
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```
