POST /v1/retract

Marks an edge as retracted. After retraction, the edge is excluded from POST /v1/search results but the row remains in Neo4j with a retracted_at timestamp — so you keep the audit trail and can un-retract later.

Scope required: admin

Request

POST /v1/retract
Authorization: Bearer ck_live_...
Content-Type: application/json

{
  "edge_uuid": "0cb65218-6cfa-4ec6-9802-1b24d6d0cb93",
  "reason": "Source recanted in follow-up conversation"
}

Field	Type	Required	Notes
`edge_uuid`	string (uuid)	yes	The `edge_uuid` from a prior search response
`reason`	string	no	Free-form audit note attached to the retraction

Response — 200 OK

{
  "ok": true,
  "edge_uuid": "0cb65218-6cfa-4ec6-9802-1b24d6d0cb93",
  "retracted_at": "2026-05-11T11:42:08Z"
}

Hard vs soft delete

/v1/retract is soft. The edge survives in the graph; future searches just skip it. To hard-delete an edge (for legal compliance reasons), contact support — there's no public endpoint for permanent removal.

Errors

HTTP	Slug	When
400	`invalid_request`	Missing or malformed `edge_uuid`
401	`unauthenticated`	Bad Bearer
403	`missing_scope`	Key lacks `admin` scope
404	`not_found`	Edge doesn't exist or belongs to a different `(team, project)`

Cross-team retraction is forbidden

A key can only retract edges in its own (team, project). Attempting to retract an edge from outside that partition returns 404 — never a 403, so the existence of foreign edges isn't leaked.

Examples

curl -X POST https://api.thebreeth.com/v1/retract \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"edge_uuid": "0cb65218-...", "reason": "Source recanted"}'

r = httpx.post(
    "https://api.thebreeth.com/v1/retract",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"edge_uuid": "0cb65218-...", "reason": "Source recanted"},
)

await fetch("https://api.thebreeth.com/v1/retract", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ edge_uuid: "0cb65218-...", reason: "Source recanted" }),
});