Replace the platform settings entries
PATCH /v1/platform/settings
| Property | Value |
|---|---|
| Operation | update_platform_settings |
| Group | Platform |
| Scope | platform:write |
| Route class | control |
| Idempotency | No Idempotency-Key |
| Audit | Audited platform.settings.update (mutation) |
| Released in | 1.9.0 |
| Phase 0 host | Served (the hosted api pins 1.65.0) |
Replaces every platform entry as the next version, under If-Match on the version, and writes the Audit event platform.settings.update. An entry whose value the platform layer may not set, such as safety.disclosure.required false, which only the Organization layer may set, is refused with validation_failed and the issue setting_not_settable_at_layer at /entries/<i>/value with layer platform (1.42.0, board #141); an entry that only bounds the path is accepted.
Request
Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the platform:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.
curl -X PATCH "$VOCAL_API/v1/platform/settings" \
-H "Authorization: Bearer $VOCAL_API_KEY" \
-H 'If-Match: "1"' \
-H "Content-Type: application/json" \
-d '{
"entries": []
}'const response = await fetch(`${process.env.VOCAL_API}/v1/platform/settings`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
'If-Match': '"1"',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"entries": []
}),
});
console.log(response.status, await response.text());import os
import requests
response = requests.patch(
f"{os.environ['VOCAL_API']}/v1/platform/settings",
headers={
"Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
"If-Match": '"1"',
},
json={
"entries": [],
},
)
print(response.status_code, response.text)Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
if-match | header | string | yes | The revision the change was made against, quoted as the ETag returns it, or * to overwrite. |
Request body
Content type application/json, required: PlatformSettingsUpdateRequest.
| Field | Type | Required | Description |
|---|---|---|---|
entries | array of PlatformEntryInput | yes | |
price_ceiling_factor | PriceCeilingFactor | no | The new factor of the price ceiling (1.38.0); absent keeps the factor in force. The Audit event records it before and after. |
Responses
| Status | Content type | Shape | Error codes |
|---|---|---|---|
200 | application/json | PlatformSettings | |
400 | application/json | ErrorEnvelope | invalid_request |
401 | application/json | ErrorEnvelope | unauthenticated |
403 | application/json | ErrorEnvelope | forbidden |
412 | application/json | ErrorEnvelope | revision_mismatch |
422 | application/json | ErrorEnvelope | validation_failed |
428 | application/json | ErrorEnvelope | precondition_required |
429 | application/json | ErrorEnvelope | rate_limited |
500 | application/json | ErrorEnvelope | internal_error |
Fields of the 200 answer
The shape is PlatformSettings.
| Field | Type | Required | Description |
|---|---|---|---|
carrier_leg | CarrierLegSecurity or null | no | What the deployment sets the SIP trunks to (1.34.0), read-only and not part of the entries or their version: PATCH /v1/platform/settings refuses a body that names it. Null when the deployment sets none; a reader treats its absence as null, as from an api before 1.34.0. |
entries | array of PlatformEntry | yes | |
object | "platform_settings" | yes | |
price_ceiling_factor | PriceCeilingFactor | no | The factor of the price ceiling in force (1.38.0, PriceCeilingFactor): a new vendor price entry above it times the highest price in force of the same unit is refused with price_above_ceiling. The api from 1.38.0 always sends it; a reader treats its absence as 2, the default. |
updated_at | Timestamp or null | yes | |
updated_by | ActorRef or null | yes | |
version | integer | yes | 0 before the first replacement; the ETag. |