VocalDocscontracts 1.65.0

Replace the platform settings entries

PATCH /v1/platform/settings

PropertyValue
Operationupdate_platform_settings
GroupPlatform
Scopeplatform:write
Route classcontrol
IdempotencyNo Idempotency-Key
AuditAudited platform.settings.update (mutation)
Released in1.9.0
Phase 0 hostServed (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": []
  }'

Parameters

NameInTypeRequiredDescription
if-matchheaderstringyesThe revision the change was made against, quoted as the ETag returns it, or * to overwrite.

Request body

Content type application/json, required: PlatformSettingsUpdateRequest.

FieldTypeRequiredDescription
entriesarray of PlatformEntryInputyes
price_ceiling_factorPriceCeilingFactornoThe new factor of the price ceiling (1.38.0); absent keeps the factor in force. The Audit event records it before and after.

Responses

StatusContent typeShapeError codes
200application/jsonPlatformSettings
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden
412application/jsonErrorEnveloperevision_mismatch
422application/jsonErrorEnvelopevalidation_failed
428application/jsonErrorEnvelopeprecondition_required
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 200 answer

The shape is PlatformSettings.

FieldTypeRequiredDescription
carrier_legCarrierLegSecurity or nullnoWhat 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.
entriesarray of PlatformEntryyes
object"platform_settings"yes
price_ceiling_factorPriceCeilingFactornoThe 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_atTimestamp or nullyes
updated_byActorRef or nullyes
versionintegeryes0 before the first replacement; the ETag.