Assert an edge

curl --request POST \
  --url https://api.get-exo.com/v1/graph/edges \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "sourceNodeId": "<string>",
  "targetNodeId": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/graph/edges"

payload = {
    "sourceNodeId": "<string>",
    "targetNodeId": "<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({sourceNodeId: '<string>', targetNodeId: '<string>'})
};

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

{
  "edgeType": "<string>",
  "id": "<string>",
  "sourceNodeId": "<string>",
  "targetNodeId": "<string>",
  "weight": 123,
  "origin": "api",
  "rationale": "<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

edges

Assert an edge

curl --request POST \
  --url https://api.get-exo.com/v1/graph/edges \
  --header 'Content-Type: application/json' \
  --header 'X-Exo-API-Key: <api-key>' \
  --data '
{
  "sourceNodeId": "<string>",
  "targetNodeId": "<string>"
}
'

import requests

url = "https://api.get-exo.com/v1/graph/edges"

payload = {
    "sourceNodeId": "<string>",
    "targetNodeId": "<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({sourceNodeId: '<string>', targetNodeId: '<string>'})
};

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

{
  "edgeType": "<string>",
  "id": "<string>",
  "sourceNodeId": "<string>",
  "targetNodeId": "<string>",
  "weight": 123,
  "origin": "api",
  "rationale": "<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>"
}

Provenance is stamped origin=api (via created_by + directionality_source) and the edge weight/confidence are capped at ASSERTED_EDGE_AUTHORITY_CAP (0.4) so a leaked key cannot inject a dominating edge into the identity graph. NLI contradiction screening is SKIPPED in v1 (documented). Both endpoints must be owned by the effective subject; otherwise 404. Idempotent on the deterministic edge id.

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
`201`	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

Asserted edges are capped. weight and confidence are limited to 0.4, so organic evidence always outranks an assertion and a leaked key cannot inject a dominating edge.
Provenance is stamped origin: "api", which is what lets you tell your assertions apart from what Exo inferred.
Contradiction screening is skipped in v1. Asserting an edge that conflicts with existing evidence is accepted rather than refused.
Idempotent on a deterministic edge id. Asserting the same edge twice does not create two edges.

Authorizations

X-Exo-API-Key

string

header

required

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

Body

application/json

Body for POST /v1/graph/edges. Both endpoints must be owned by the effective subject. weight is capped at ASSERTED_EDGE_AUTHORITY_CAP.

sourceNodeId

string

required

Maximum string length: 512

targetNodeId

string

required

Maximum string length: 512

edgeType

string

default:relates_to

Maximum string length: 200

rationale

string | null

Maximum string length: 4000

weight

number | null

Response

Successful Response

An edge asserted through the API, as stored.

Returned by POST /v1/graph/edges. origin is always api and weight is the capped value actually written (see the asserted-edge authority cap), which may be lower than the weight requested.

edgeType

string

required

string

required

sourceNodeId

string

required

targetNodeId

string

required

weight

number

required

origin

string

default:api

rationale

string | null

​Authorization

​Headers

​Success responses

​Errors

​Notes

Authorizations

Body

Response

Authorization

Headers

Success responses

Errors

Notes