메타데이터

metadata는 객체에 붙이는 직접 정한 키-값 쌍의 집합이에요. CRM에 있는 항목의 ID, 그 항목을 맡은 팀, 그 항목을 쓴 동기화 실행 같은 정보를 담을 수 있어요. Sursa는 메타데이터를 저장하고, 객체와 이벤트에 담아 반환하고, 메타데이터로 카드, 컬렉션, 폴더의 목록을 필터링할 수 있게 해 줘요. 메타데이터의 의미는 전혀 해석하지 않아요.

{
  "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60",
  "title": "Refund policy",
  "metadata": {"crm_id": "A-1042", "team": "support"}
}

metadata가 있는 객체는 카드, 컬렉션, 폴더예요. 사용자 지정 소스의 문서에도 metadata가 있으며, 이 값은 문서에서 만들어진 카드의 metadata가 돼요.

한도

한도를 벗어난 요청은 400 상태와 api.metadata_invalid 코드를 반환해요. error.details.key는 문제가 된 키를, error.details.reason은 무엇이 잘못되었는지를 알려 줘요. 이유는 too_many_keys, key_invalid, value_too_long, too_large, value_invalid(값이 문자열이 아님) 중 하나예요.

값은 문자열이에요. 숫자와 날짜도 문자열로 저장하세요. 예: "2026-10-24".

메타데이터 설정하기

객체를 생성하거나 교체할 때(POST, PUT) metadata는 통째로 설정돼요.

curl -X PUT https://api.sursa.com/v1/cards-by-external-id/policy-refunds \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund policy",
    "body": "Refunds are processed within 14 days.",
    "metadata": {"crm_id": "A-1042", "team": "support"}
  }'

파일 업로드 같은 multipart/form-data 요청에서는 metadata를 값이 JSON 객체인 폼 필드로 보내세요. 예: metadata={"crm_id":"A-1042"}.

메타데이터 수정하기

PATCH는 보낸 키를 기존 키에 병합해요. 값이 ""이나 null인 키는 삭제되고, 보내지 않은 키는 그대로 남아요.

curl -X PATCH https://api.sursa.com/v1/cards/3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60 \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"team": "billing", "legacy_flag": null}}'

{"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "metadata": {"crm_id": "A-1042", "team": "billing"}}

"metadata": {}는 아무것도 바꾸지 않아요. 모든 쌍을 지우려면 각 키를 null 값으로 보내세요.

메타데이터로 필터링하기

다음 목록은 metadata[<key>]=<value> 파라미터를 받아요.

• 카드: GET /v1/cards와 GET /v1/cards/count
• 컬렉션: GET /v1/collections
• 폴더: GET /v1/folders와 GET /v1/collections/{name}/folders

값이 정확히 일치해야 해요. 조건은 최대 3개까지 조합할 수 있으며, 객체는 모든 조건과 일치해야 해요.

curl -G https://api.sursa.com/v1/cards \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  --data-urlencode "metadata[team]=support" \
  --data-urlencode "metadata[crm_id]=A-1042"

필터를 쓰면 폴더 트리가 평면 목록으로 와요. 각 컬렉션의 folders에는 조건과 일치하는 폴더가 빈 children과 함께 담기고, 각 폴더의 위치는 parent_id로 알 수 있어요. 이때 GET /v1/folders는 일치하는 폴더가 없는 컬렉션을 빼고 반환해요. 조건이 3개를 넘거나 키가 잘못되면 400 상태와 api.metadata_invalid 코드를 반환해요.

메타데이터가 아닌 것

• 콘텐츠가 아니에요. 검색과 어시스턴트의 답변은 메타데이터를 쓰지 않아요. 사람들이 찾아야 할 내용은 카드의 본문, 제목, 태그에 넣으세요.
• 비공개가 아니에요. 객체를 볼 수 있는 모든 사람이 메타데이터도 볼 수 있어요. 객체를 읽는 사람이 보면 안 되는 시크릿, 토큰, 개인 정보는 절대 저장하지 마세요.
• external_id를 대신하지 않아요. 직접 관리하는 항목의 ID로 카드를 찾으려면 카드에 external_id를 지정하세요. 이 값은 고유하지만 메타데이터 값은 고유하지 않아요.