Create a hand-made org unit

POST/api/public/v1/org-units

A unit a human authored, under an existing parent. source is manual, so a directory sync never removes it and the tree can be shaped in an organization with no directory connected at all. Depth is capped at 10 and the cap is a REJECTION here (422 DEPTH_EXCEEDED), never the silent truncation the ingest path applies. An optional zone: {agent_ids} creates the unit with its Autonomy Zone enabled and pins those agents to it by hand, all in one transaction.

cURL

curl --fail-with-body -X POST 'https://app.openlatch.ai/api/public/v1/org-units' \
  -H "Authorization: Bearer $OPENLATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"parent_id":"<parent_id>","name":"<unit_name>"}'

Python

import json
import os
import urllib.request

body = '{"parent_id":"<parent_id>","name":"<unit_name>"}'
request = urllib.request.Request(
    'https://app.openlatch.ai/api/public/v1/org-units',
    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/org-units' \
  -H "Authorization: Bearer $OPENLATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"parent_id":"<parent_id>","name":"<unit_name>"}' | jq .

PowerShell

$headers = @{
  Authorization = "Bearer $env:OPENLATCH_API_KEY"
}
$body = '{"parent_id":"<parent_id>","name":"<unit_name>"}'
Invoke-RestMethod -Method POST -Uri 'https://app.openlatch.ai/api/public/v1/org-units' -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	Not allowed
viewer	Not allowed

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

API key scope: org: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
name	string	Required.
parent_id	string (uuid)	Required.
zone	object or null	Create the unit with its Autonomy Zone enabled, and pin agent_ids to it, in one transaction. Omit for a unit without a zone.
zone.agent_ids	array of string or null	Agents pinned to the new zone by hand in the same transaction (at most 5 000; an id that is not an agent of this organization answers 404 AGENT_NOT_FOUND).

Response

• 201 Created — the call succeeded.
• 400 Bad Request — BAD_REQUEST
• 401 Unauthorized — UNAUTHORIZED
• 402 Payment Required — license_expired
• 403 Forbidden — FEATURE_DISABLED, FORBIDDEN, INSUFFICIENT_SCOPE
• 404 Not Found — AGENT_NOT_FOUND, NOT_FOUND
• 409 Conflict — ASSIGNMENT_BUSY, IDEMPOTENCY_IN_PROGRESS, UNIT_EXISTS
• 422 Unprocessable Content — DEPTH_EXCEEDED, IDEMPOTENCY_KEY_REUSED, INVALID_ID, INVALID_NAME, SELECTION_TOO_LARGE, VALIDATION_ERROR
• 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
agents_count	integer	Required.
agents_direct	integer or null
depth	integer	Required.
effective_zone_id	string or null
id	string	Required.
name	string	Required.
parent_id	string or null
path	string	Required.
policies_added_here	integer	Required.
policies_in_force	integer	Required.
short	string or null
source	string	Required.
zone	object or null
zone.ask_mode	string or null
zone.effective_ask_mode	string
zone.id	string	Required.
zone.is_default	boolean	Whether this is the organization's default zone: it serves agents with no owner and no pin.
zone.is_root	boolean	Required.
zone.limits	object or null

Example response

{
  "agents_count": 3,
  "agents_direct": 3,
  "depth": 3,
  "effective_zone_id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
  "id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
  "name": "release-bot",
  "parent_id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
  "path": "Engineering / Platform",
  "policies_added_here": 3,
  "policies_in_force": 3,
  "short": "string",
  "source": "string",
  "zone": {
    "ask_mode": "string",
    "effective_ask_mode": "both",
    "id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
    "is_default": false,
    "is_root": false,
    "limits": {
      "cannot_prompt": 3,
      "in_scope": 3,
      "shell_only": 3
    }
  }
}

Related

• DELETE Reset an agent to automatic zone assignment
• GET What governs this agent
• PUT Assign an agent to a zone by hand