Override, link or reset an agent's ownership

PATCH/api/public/v1/agents/{agent_id}/ownership

Exactly ONE directive per body: owner_person_id · owner_provider_id + owner_external_id · owner_local_email (+ optional owner_local_display_name / owner_local_title / owner_local_org_path — sent applies, omitted leaves alone, sent blank clears) · owner_kind: "service" + service_label + one accountable ref · function · external_agent_id + external_agent_provider · reset: "owner" | "function". Writes unconditionally (a human outranks any in-flight resolution), audits agent.owner.overridden / agent.owner.reset, and for the link and both resets enqueues an immediate background re-resolution — the response is the cleared / linked state, never the re-resolved one. 400 zero or several directives or an off-enum function · 404 unknown agent / person / provider · 422 a directive missing a co-key, or a typed address that matches people in more than one directory (OWNER_EMAIL_AMBIGUOUS).

cURL

curl --fail-with-body -X PATCH 'https://app.openlatch.ai/api/public/v1/agents/<agent_id>/ownership' \
  -H "Authorization: Bearer $OPENLATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"owner_local_display_name":"Dana Whitfield","owner_local_email":"dana.whitfield@example.com"}'

Python

import json
import os
import urllib.request

body = '{"owner_local_display_name":"Dana Whitfield","owner_local_email":"dana.whitfield@example.com"}'
request = urllib.request.Request(
    'https://app.openlatch.ai/api/public/v1/agents/<agent_id>/ownership',
    method='PATCH',
    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 PATCH 'https://app.openlatch.ai/api/public/v1/agents/<agent_id>/ownership' \
  -H "Authorization: Bearer $OPENLATCH_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"owner_local_display_name":"Dana Whitfield","owner_local_email":"dana.whitfield@example.com"}' | jq .

PowerShell

$headers = @{
  Authorization = "Bearer $env:OPENLATCH_API_KEY"
}
$body = '{"owner_local_display_name":"Dana Whitfield","owner_local_email":"dana.whitfield@example.com"}'
Invoke-RestMethod -Method PATCH -Uri 'https://app.openlatch.ai/api/public/v1/agents/<agent_id>/ownership' -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: agents:write

Path parameters

Parameter	Type	Description
agent_id	string	Required.

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
external_agent_id	string or null
external_agent_provider	string or null
function	string or null
owner_external_id	string or null
owner_kind	string or null
owner_local_display_name	string or null
owner_local_email	string (email) or null
owner_local_org_path	string or null
owner_local_title	string or null
owner_person_id	string or null
owner_provider_id	string or null
reset	string or null
service_accountable_org_unit_id	string or null
service_accountable_person_id	string or null
service_label	string or null

Response

• 200 OK — 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 — NOT_FOUND
• 409 Conflict — IDEMPOTENCY_IN_PROGRESS
• 422 Unprocessable Content — IDEMPOTENCY_KEY_REUSED, INVALID_ID, OWNER_EMAIL_AMBIGUOUS, VALIDATION_ERROR
• 429 Too Many Requests — TOO_MANY_REQUESTS
• 500 Internal Server Error — INTERNAL_SERVER_ERROR, tenant_isolation_violation
• 502 Bad Gateway — BAD_GATEWAY
• 503 Service Unavailable — FEATURE_STATE_UNAVAILABLE, SERVICE_UNAVAILABLE

Response fields

Field	Type	Description
capture_capable	boolean
function	string or null
function_confidence	number or null
function_source	string or null
owner	object or null
owner.display_name	string or null
owner.email	string or null
owner.org_unit	object or null
owner.person_id	string	Required.
owner.privilege	object or null
owner.status	string	Required.
owner.title	string or null
owner_kind	string or null
owner_resolved_at	string (date-time) or null
owner_source	string or null
provider	object or null
provider.display_name	string	Required.
provider.id	string	Required.
provider.kind	string	Required.
provider.last_synced_at	string (date-time) or null
provider.stale	boolean
service	object or null
service.accountable_org_unit	object or null
service.accountable_person	object or null
service.label	string or null
signals	array of object
signals[].kind	string	Required.
signals[].outcome	string	Required.
signals[].value	string or null
unattributed_reason	string or null
unattributed_since	string (date-time) or null

Example response

{
  "capture_capable": true,
  "function": "string",
  "function_confidence": 0.25,
  "function_source": "string",
  "owner": {
    "display_name": "release-bot",
    "email": "ada@example.com",
    "org_unit": {
      "id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
      "name": "release-bot",
      "path": "Engineering / Platform"
    },
    "person_id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
    "privilege": {
      "capabilities": {},
      "evaluated_at": "2026-01-15T14:32:05Z",
      "grant_count": 0,
      "grant_counts": {},
      "tier": "string"
    },
    "status": "string",
    "title": "string"
  },
  "owner_kind": "string",
  "owner_resolved_at": "2026-01-15T14:32:05Z",
  "owner_source": "string",
  "provider": {
    "display_name": "release-bot",
    "id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
    "kind": "string",
    "last_synced_at": "2026-01-15T14:32:05Z",
    "stale": false
  },
  "service": {
    "accountable_org_unit": {
      "id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
      "name": "release-bot",
      "path": "Engineering / Platform"
    },
    "accountable_person": {
      "display_name": "release-bot",
      "email": "ada@example.com",
      "org_unit": {},
      "person_id": "3f6c1a2e-8b4d-4c1f-9a7e-0d5b2c8e4f10",
      "privilege": {},
      "status": "string",
      "title": "string"
    },
    "label": "string"
  },
  "signals": [
    {
      "kind": "string",
      "outcome": "string",
      "value": "string"
    }
  ],
  "unattributed_reason": "Never push to main without a review.",
  "unattributed_since": "2026-01-15T14:32:05Z"
}

Related

• GET List agents connected to the authenticated organization
• DELETE Delete an agent and cascade to all its sessions, events, and stats.
• GET Get a single agent by ID