Skip to the content

Read the Organization agent defaults

GET /v1/organization/agent-defaults

Property	Value
Operation	`get_organization_agent_defaults`
Group	Organization
Scope	`agents:read`
Route class	`read`
Idempotency	No `Idempotency-Key`
Audit	Not audited: A configuration read; the defaults are not Call content.
Released in	1.6.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the agents:read scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl "$VOCAL_API/v1/organization/agent-defaults" \
  -H "Authorization: Bearer $VOCAL_API_KEY"

const response = await fetch(`${process.env.VOCAL_API}/v1/organization/agent-defaults`, {
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.get(
    f"{os.environ['VOCAL_API']}/v1/organization/agent-defaults",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
    },
)
print(response.status_code, response.text)

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	OrganizationAgentDefaults
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is OrganizationAgentDefaults.

Field	Type	Required	Description
`bounds`	array of OrganizationSettingBound	no	At most 100 bounds, one per leaf path (1.18.0). An Agent version or a per-Call override outside one is refused with `setting_out_of_bounds` naming the `organization` layer. The api always sends it; absent means none.
`disclosure_attestation`	DisclosureAttestation or null	no	The attestation in force when this version's values turn the AI disclosure off (1.24.0), carried from version to version while it stays off; null while the disclosure is on. An api before 1.24.0 omits it, and a reader treats its absence as null.
`effective`	EffectiveSettings	yes	The Organization values over the platform defaults, for the same pack.
`locks`	array of SettingPath	no	At most 100 leaf paths the Organization locks (1.18.0): its value wins, and an Agent version or a per-Call override that sets the path is refused with `setting_locked` naming the `organization` layer. A platform lock on the path applies first. The api always sends it; absent means none.
`object`	`"organization_agent_defaults"`	yes
`platform_defaults`	EffectiveSettings	yes	The platform layer for the Organization's default language pack (`en`).
`updated_at`	Timestamp or null	yes
`updated_by`	ActorRef or null	yes
`values`	AgentSettings	yes	The paths the Organization sets.
`version`	integer	yes	Counts replacements; 0 before the first. Returned as the ETag.