State sentences as a policy

POST/api/public/v1/policies/stated

Grounds each stated sentence in a read_ground job, then ratifies every sentence that is grounded or deferred into zone_ids — one Autonomy Zone (409 ONE_ZONE_PER_AIP for more) — in the mode; the caller is recorded as its ratifier, and a refused sentence creates nothing. Answers 202 with the job to poll; its result names the AIP (policy_public_id, null when every sentence was refused). A sentence is a string (dimension security) or {sentence, dimension}. An agent (OAuth) caller is refused with 403 AGENT_AUTHORING_VIA_DRAFTS: agents author intent policies through drafts.

cURL

curl --fail-with-body -X POST 'https://app.openlatch.ai/api/public/v1/policies/stated' \
  -H "Authorization: Bearer $OPENLATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"sentences":["Block a direct push to main."],"zone_ids":["<zone_id>"],"mode":"monitor"}'

Python

import json
import os
import urllib.request

body = '{"sentences":["Block a direct push to main."],"zone_ids":["<zone_id>"],"mode":"monitor"}'
request = urllib.request.Request(
    'https://app.openlatch.ai/api/public/v1/policies/stated',
    method='POST',
    data=body.encode(),
    headers={
        'Authorization': 'Bearer ' + os.environ['OPENLATCH_API_KEY'],
        'Content-Type': 'application/json',
    },
)
with urllib.request.urlopen(request) as response:
    text = response.read().decode()
    print(json.dumps(json.loads(text), indent=2) if text else response.status)

Bash

#!/usr/bin/env bash
set -euo pipefail

curl -sS --fail-with-body -X POST 'https://app.openlatch.ai/api/public/v1/policies/stated' \
  -H "Authorization: Bearer $OPENLATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"sentences":["Block a direct push to main."],"zone_ids":["<zone_id>"],"mode":"monitor"}' | jq .

PowerShell

$headers = @{
  Authorization = "Bearer $env:OPENLATCH_API_KEY"
}
$body = '{"sentences":["Block a direct push to main."],"zone_ids":["<zone_id>"],"mode":"monitor"}'
Invoke-RestMethod -Method POST -Uri 'https://app.openlatch.ai/api/public/v1/policies/stated' -Headers $headers -ContentType 'application/json; charset=utf-8' -Body $body | ConvertTo-Json -Depth 20

Authorization

Role in the organization	This endpoint
owner	Allowed
admin	Allowed
editor	Allowed
viewer	Not allowed

A key carries the role its owner holds in the organization. See Authentication.

API key scope: policies:write

Header parameters

Parameter	Type	Description
Idempotency-Key	string or null	Optional. Makes the request safe to retry: the same key and the same request, within 24 hours, returns the stored response with Idempotent-Replayed: true and runs once.

Request body

Field	Type	Description
language	string or null
mode	string — one of disabled, monitor, enforce	Required.
sentences	array of one of: string, object	Required.
sentences[] (StatedSentenceIn).dimension	string — one of quality, economics, security, safety, compliance
sentences[] (StatedSentenceIn).sentence	string	Required.
zone_ids	array of string (uuid)	Required.

Response

• 202 Accepted — the call succeeded.
• 400 Bad Request — BAD_REQUEST
• 401 Unauthorized — UNAUTHORIZED
• 402 Payment Required — license_expired
• 403 Forbidden — AGENT_AUTHORING_VIA_DRAFTS, FEATURE_DISABLED, FORBIDDEN, INSUFFICIENT_SCOPE
• 409 Conflict — AI_NOT_ENABLED, IDEMPOTENCY_IN_PROGRESS, ONE_ZONE_PER_AIP
• 422 Unprocessable Content — IDEMPOTENCY_KEY_REUSED, INVALID_ID, NO_ZONE, VALIDATION_ERROR, ZONE_UNAVAILABLE
• 429 Too Many Requests — TOO_MANY_REQUESTS
• 500 Internal Server Error — INTERNAL_SERVER_ERROR, tenant_isolation_violation
• 503 Service Unavailable — FEATURE_STATE_UNAVAILABLE, SERVICE_UNAVAILABLE

Response fields

Field	Type	Description
data	object	Required. `202 for a job-starting operation: poll GET /aip/jobs/{job_id}`.
data.job_id	string	Required.

Example response

{
  "data": {
    "job_id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10"
  }
}

Related

• DELETE Delete a policy
• GET Read one ratified policy
• PATCH Change the mode of a policy in one Autonomy Zone