Edges & Graph

Show: All versions v2 only

Bucket edges represent relationships between nodes inside a bucket, such as supersedes, references, or part_of. The v1 routes that read and write these edges directly are no longer a public consumer API.

Note: Do not use these routes in new integrations. Schift may still use relationship signals internally during search, but raw graph edges are not a supported public surface. Use v2 bucket search for user-facing retrieval.

API Versions

Version	Status	Notes
v1	Deprecated	Direct edge mutation routes. Kept for existing internal callers only.
v2	Current	Retrieve related content via bucket search.

POST /v1/buckets/{bucket_id}/edges

Add edges to a bucket.

Note: This endpoint is deprecated and is not included in the public OpenAPI schema.

Path parameters

Name	Type	Description
bucket_id	string	UUID of the bucket.

Request body

Name	Type	Required	Description
edges	array	Yes	Up to 10,000 edge objects.
edges[].source	string	Yes	Source node ID.
edges[].target	string	Yes	Target node ID.
edges[].relation	string	No	One of contradicts, supersedes, caused_by, is_a, related_to (default), has_child, follows, references, summarizes, alias_of, part_of.
edges[].weight	number	No	Confidence weight from 0.0 to 1.0. Defaults to 1.0.

Example request

curl -X POST ${API_BASE_URL:-https://api.schift.io}/v1/buckets/550e8400-e29b-41d4-a716-446655440000/edges \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "edges": [
      {
        "source": "node-1",
        "target": "node-2",
        "relation": "supersedes",
        "weight": 0.95
      }
    ]
  }'

Example response

{
  "count": 1
}

Error examples

// 400 invalid_relation_type
{
  "error": "invalid_relation_type",
  "unknown_relation_types": ["supersedes"]
}

// 402 Payment Required
{
  "allowed": false,
  "reason": "quota_exceeded"
}

// 403 Forbidden
{
  "detail": "Ingest quota unavailable. Upgrade your plan."
}

// 404 Not Found
{
  "detail": "Bucket not found"
}

GET /v1/buckets/{bucket_id}/edges/{node_id}

List edges connected to a node.

Note: This endpoint is deprecated and is not included in the public OpenAPI schema.

Path parameters

Name	Type	Description
bucket_id	string	UUID of the bucket.
node_id	string	Node ID to query.

Query parameters

Name	Type	Required	Description
direction	string	No	outgoing (default), incoming, or both.
relation	string	No	Filter to a single relation type. Must be defined in the bucket ontology.

Example request

curl -G ${API_BASE_URL:-https://api.schift.io}/v1/buckets/550e8400-e29b-41d4-a716-446655440000/edges/node-1 \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d "direction=both" \
  -d "relation=supersedes"

Example response

{
  "node_id": "node-1",
  "direction": "both",
  "edges": [
    {
      "source": "node-1",
      "target": "node-2",
      "relation": "supersedes",
      "weight": 0.95
    }
  ]
}

Error examples

// 400 invalid_relation_type
{
  "error": "invalid_relation_type",
  "unknown_relation_types": ["supersedes"]
}

// 404 Not Found
{
  "detail": "Bucket not found"
}

DELETE /v1/buckets/{bucket_id}/edges

Delete a specific edge.

Note: This endpoint is deprecated and is not included in the public OpenAPI schema.

Path parameters

Name	Type	Description
bucket_id	string	UUID of the bucket.

Request body

Name	Type	Required	Description
source	string	Yes	Source node ID.
target	string	Yes	Target node ID.
relation	string	No	Relation type. Defaults to related_to. Must be defined in the bucket ontology.

Example request

curl -X DELETE ${API_BASE_URL:-https://api.schift.io}/v1/buckets/550e8400-e29b-41d4-a716-446655440000/edges \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "node-1",
    "target": "node-2",
    "relation": "supersedes"
  }'

Example response

204 No Content on success.

Error examples

// 400 invalid_relation_type
{
  "error": "invalid_relation_type",
  "unknown_relation_types": ["supersedes"]
}

// 404 Not Found
{
  "detail": "Bucket not found"
}

Replace with v2 bucket search

Instead of reading raw edges, submit a natural-language query to the v2 search endpoint:

curl -X POST ${API_BASE_URL:-https://api.schift.io}/v2/buckets/550e8400-e29b-41d4-a716-446655440000/search \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Which policy supersedes the old refund rule?",
    "top_k": 8,
    "options": {
      "rerank": {"enabled": true}
    }
  }'

See also

• Buckets
• Bucket search