Create a Policy draft

POST /v1/policies

Property	Value
Operation	`create_policy`
Group	Policies
Scope	`policies:write`
Route class	`control`
Idempotency	`Idempotency-Key` accepted: a retry with the same key replays the first answer
Audit	Audited `policy.create` (mutation)
Released in	1.47.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Creates a Policy draft at revision 1. The document is linted under the Vocal profile at its hook and for its action type, and every error finding is a detail of 422 validation_failed, naming the node and the code; warnings return in analysis.warnings. A reserved action type (set_setting; raise_event until 1.58.0, record_opt_out until 1.61.0) is refused with capability_not_available. A write to an organization-scoped Policy, or one that disables a compliance-tagged Policy, also needs policies:admin and is otherwise refused with forbidden and the detail policies_admin_required.

Request

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

curl -X POST "$VOCAL_API/v1/policies" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "h2-appointment-tools-require-verification",
    "hook": "on_call_start",
    "action_type": "block",
    "logic": {
      "nodes": [
        {
          "id": "<id>",
          "name": "<name>",
          "type": "inputNode"
        }
      ],
      "edges": []
    }
  }'

const response = await fetch(`${process.env.VOCAL_API}/v1/policies`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "h2-appointment-tools-require-verification",
    "hook": "on_call_start",
    "action_type": "block",
    "logic": {
      "nodes": [
        {
          "id": "<id>",
          "name": "<name>",
          "type": "inputNode"
        }
      ],
      "edges": []
    }
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/policies",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "h2-appointment-tools-require-verification",
        "hook": "on_call_start",
        "action_type": "block",
        "logic": {
            "nodes": [
                {
                    "id": "<id>",
                    "name": "<name>",
                    "type": "inputNode",
                },
            ],
            "edges": [],
        },
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`idempotency-key`	header	string	no	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: PolicyCreateRequest.

Field	Type	Required	Description
`action_type`	PolicyActionType	yes
`compliance_tag`	ComplianceTag or null	no	Null when omitted.
`description`	string	no	For reviewers; never sent to the model.
`enabled`	boolean	no	True when omitted.
`hook`	HookPoint	yes
`logic`	JdmDocumentInput	yes	The JDM document under the Vocal profile: its input is the hook's Call context and it writes the parameters of the action type under `action`, or nothing. Every save and publish lints it (`policyLint`); an error refuses with 422 `validation_failed`.
`name`	PolicyName	yes
`priority`	integer	no	500 when omitted.
`scope`	PolicyScope	no	`agent` when omitted.

Responses

Status	Content type	Shape	Error codes
`201`	`application/json`	Policy
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`, `org_suspended`
`409`	`application/json`	ErrorEnvelope	`idempotency_in_progress`, `idempotency_key_reused`
`422`	`application/json`	ErrorEnvelope	`validation_failed`, `capability_not_available`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `201` answer

The shape is Policy.

Field	Type	Required	Description
`action_type`	PolicyActionType	yes	The one action type the document may output; its legality at `hook` is checked at save.
`active_version`	integer or null	yes	The version Agent version publish pins (agent scope) or dispatch resolves (organization scope), or null when none is active.
`analysis`	PolicyAnalysis	yes
`archived_at`	Timestamp or null	yes	When `DELETE` archived the Policy, or null. An archived Policy takes no write, publish or activation (409 `policy_archived`); its pinned versions keep running.
`compliance_tag`	ComplianceTag or null	yes
`created_at`	Timestamp	yes
`description`	string or null	yes	For reviewers; never sent to the model.
`enabled`	boolean	yes	The kill switch, read at dispatch and effective from the next Call; not part of any version.
`hook`	HookPoint	yes
`id`	PolicyId	yes
`latest_version`	integer or null	yes	The highest published version, or null before the first publish.
`logic`	JdmDocument	yes
`name`	PolicyName	yes
`object`	`"policy"`	yes
`organization_id`	OrganizationId	yes
`origin`	PolicyOrigin	yes
`priority`	integer	yes	Lower runs first; ties go to organization scope, then to the id.
`revision`	integer	yes	Counts writes to the draft; returned as the ETag and required in If-Match.
`scope`	PolicyScope	yes
`setting_path`	SettingPath or null	yes	For a derived Policy, the setting it was compiled from; null when `authored`.
`updated_at`	Timestamp	yes