엣지(Edge)와 그래프

Show: All versions v2 only

버킷(bucket) 내 노드(node) 간의 관계를 나타내는 엣지(edge)는 supersedes, references, part_of 등이 있습니다. 이러한 엣지를 직접 읽고 쓰는 v1 라우트는 더 이상 공개 사용자 API가 아닙니다.

참고: 신규 연동에 이 라우트를 사용하지 마세요. Schift는 검색 과정에서 여전히 내부적으로 관계 신호를 활용할 수 있지만, 원시 그래프(graph) 엣지는 공개적으로 지원되는 표면이 아닙니다. 사용자 중심 검색에는 v2 버킷 검색을 사용하세요.

API 버전

버전	상태	설명
v1	사용 중단(deprecated)	엣지를 직접 변경하는 라우트입니다. 기존 내부 호출자만을 위해 유지됩니다.
v2	현재(current)	버킷 검색을 통해 관련 콘텐츠를 검색합니다.

POST /v1/buckets/{bucket_id}/edges

버킷(bucket)에 엣지(edge)를 추가합니다.

참고: 이 엔드포인트는 사용 중단(deprecated)되었으며 공개 OpenAPI 스키마에 포함되어 있지 않습니다.

경로 매개변수

이름	유형	설명
bucket_id	string	버킷(bucket)의 UUID입니다.

요청 본문

이름	유형	필수	설명
edges	array	예	최대 10,000개의 엣지(edge) 객체입니다.
edges[].source	string	예	소스(source) 노드 ID입니다.
edges[].target	string	예	타겟(target) 노드 ID입니다.
edges[].relation	string	아니요	contradicts, supersedes, caused_by, is_a, related_to(기본값), has_child, follows, references, summarizes, alias_of, part_of 중 하나입니다.
edges[].weight	number	아니요	0.0에서 1.0 사이의 신뢰도 가중치(weight)입니다. 기본값은 1.0입니다.

예제 요청

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
      }
    ]
  }'

예제 응답

{
  "count": 1
}

오류 예시

// 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}

노드(node)에 연결된 엣지(edge) 목록을 조회합니다.

참고: 이 엔드포인트는 사용 중단(deprecated)되었으며 공개 OpenAPI 스키마에 포함되어 있지 않습니다.

경로 매개변수

이름	유형	설명
bucket_id	string	버킷(bucket)의 UUID입니다.
node_id	string	조회할 노드(node) ID입니다.

쿼리 매개변수

이름	유형	필수	설명
direction	string	아니요	엣지 방향(direction)입니다. outgoing (기본값), incoming, both 중 하나입니다.
relation	string	아니요	단일 관계(relation) 유형으로 필터링합니다. 버킷 온톨로지(ontology)에 정의되어 있어야 합니다.

예제 요청

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"

예제 응답

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

오류 예시

// 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

특정 엣지(edge)를 삭제합니다.

참고: 이 엔드포인트는 사용 중단(deprecated)되었으며 공개 OpenAPI 스키마에 포함되어 있지 않습니다.

경로 매개변수

이름	유형	설명
bucket_id	string	버킷(bucket)의 UUID입니다.

요청 본문

이름	유형	필수	설명
source	string	예	소스(source) 노드 ID입니다.
target	string	예	타겟(target) 노드 ID입니다.
relation	string	아니요	관계(relation) 유형입니다. 기본값은 related_to이며, 버킷 온톨로지(ontology)에 정의되어 있어야 합니다.

예제 요청

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"
  }'

예제 응답

성공 시 204 No Content를 반환합니다.

오류 예시

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

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

v2 버킷 검색으로 대체

원시 엣지를 읽는 대신, v2 검색 엔드포인트(search endpoint)에 자연어 쿼리(natural-language query)를 전송하세요:

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}
    }
  }'

참고 항목

• 버킷(Buckets)
• 버킷 검색(Bucket search)