Supersede a belief

curl --request POST \
  --url https://api.get-exo.com/v1/graph/nodes/{node_id}/supersede \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "confidence": 1,
  "content": "<string>",
  "nodeId": "<string>",
  "reason": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/graph/nodes/{node_id}/supersede"

payload = {
    "confidence": 1,
    "content": "<string>",
    "nodeId": "<string>",
    "reason": "<string>"
}
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({confidence: 1, content: '<string>', nodeId: '<string>', reason: '<string>'})
};

fetch('https://api.get-exo.com/v1/graph/nodes/{node_id}/supersede', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "created": true,
  "edgeId": "<string>",
  "newAuthority": 123,
  "newNodeId": "<string>",
  "oldNodeId": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

POST

graph

nodes

{node_id}

supersede

Supersede a belief

curl --request POST \
  --url https://api.get-exo.com/v1/graph/nodes/{node_id}/supersede \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "confidence": 1,
  "content": "<string>",
  "nodeId": "<string>",
  "reason": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/graph/nodes/{node_id}/supersede"

payload = {
    "confidence": 1,
    "content": "<string>",
    "nodeId": "<string>",
    "reason": "<string>"
}
headers = {
    "X-Exo-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Exo-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({confidence: 1, content: '<string>', nodeId: '<string>', reason: '<string>'})
};

fetch('https://api.get-exo.com/v1/graph/nodes/{node_id}/supersede', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "created": true,
  "edgeId": "<string>",
  "newAuthority": 123,
  "newNodeId": "<string>",
  "oldNodeId": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

{
  "code": "<string>",
  "detail": "<string>",
  "status": 123,
  "title": "<string>",
  "type": "<string>",
  "documentationUrl": "<string>",
  "errors": [
    {
      "code": "<string>",
      "field": "<string>",
      "message": "<string>",
      "pointer": "<string>"
    }
  ],
  "requestId": "",
  "suggestedAction": "<string>"
}

Record that a belief was superseded (old -> superseded_by -> new). The successor is either a NEW node created from content (Voyage-embedded) or an already-owned node named by nodeId. Authority transfers per the internal adaptive semantics: the successor inherits max(old, new) and the superseded node decays by 1 - confidence. Both nodes must be owned by the effective subject; anything else is 404. This is the default “wrong belief” verb (forget = erasure only).

Authorization

This route requires the graph:write scope. A key carrying memory:forget or write also qualifies. A missing or invalid credential returns 401 authentication_error. A valid credential without the scope returns 403 permission_denied, and the problem body names the exact scope required.

Headers

These are request conventions the contract does not declare as parameters, so they do not appear in the schema tables below.

Header	Applies	What it does
`X-Exo-API-Key`	Required	Your Exo API key, `exo_<env>_<token>`. `Authorization: Bearer exo_...` is accepted as an alternate.
`X-Exo-Subject`	Optional	Acts for a provisioned subject instead of the key owner. An unprovisioned id returns 403 `subject_not_provisioned`.
`Idempotency-Key`	Honoured	Makes a retry safe. The same key with the same body replays the original response instead of acting twice. See Idempotency.
`X-Request-Id`	Response	Returned on every response, including `204`s. Quote it in a support request.

Success responses

Status	Meaning
`200`	Successful Response

Errors

Status	Code	When
`400`	`invalid_request`	Malformed request, for example an invalid cursor.
`401`	`authentication_error`	Missing or invalid credentials.
`403`	`permission_denied`	Missing scope, or an unprovisioned subject selector.
`404`	`not_found`	The resource does not exist, or is not visible to this caller.
`409`	`conflict`	A conflict with the current state of the resource.
`422`	`validation_error`	The request was understood but failed field validation.
`429`	`rate_limit_exceeded`	Rate limit exceeded. Retry after the Retry-After interval.
`503`	`service_degraded`	A dependency is temporarily unavailable. Safe to retry.

Beyond the shared statuses, this route can answer with idempotency_in_flight, idempotency_key_reuse. Every problem body names its own code, and the type URI always resolves to the matching page. Every error is an RFC 9457 application/problem+json body carrying a stable code, a requestId, and a suggestedAction where Exo has one. See Errors.

Notes

Exo never overwrites a belief. Supersede keeps the old node, links the new one to it, and transfers authority. The trail is readable afterwards at GET /v1/graph/nodes/{node_id}/history.
Give it either an existing nodeId or new content. With content a successor node is created for you and created comes back true.
This is how you close a contradiction. There is no resolve route: supersede the side that lost.

Authorizations

X-Exo-API-Key

string

header

required

An Exo API key (exo_...) sent as the X-Exo-API-Key header.

Path Parameters

node_id

string

required

The knowledge-graph node id.

Body

application/json

Body for POST /v1/graph/nodes/{id}/supersede.

Exactly one of content (create a successor node from text) or nodeId (link an already-owned node as the successor) must be set. confidence in [0,1] drives the authority transfer (the superseded belief decays by 1 - confidence; default 1.0 fully demotes it, matching the internal adaptive supersession semantics).

confidence

number

default:1

content

string | null

Maximum string length: 100000

nodeId

string | null

Maximum string length: 512

reason

string | null

Maximum string length: 4000

Response

Successful Response

Result of a belief supersession.

created

boolean

required

edgeId

string

required

newAuthority

number

required

newNodeId

string

required

oldNodeId

string

required

​Authorization

​Headers

​Success responses

​Errors

​Notes

Authorizations

Path Parameters

Body

Response

Authorization

Headers

Success responses

Errors

Notes