Format 목록 API: handle·id로 Sume Format 찾기

API로 Sume Format 목록을 보려면 formats:read가 있는 키로 GET /v1/formats를 보내세요. 키의 워크스페이스가 소유한 Format과 first-party 카탈로그가 keyset 방식의 페이지로 돌아옵니다. 여러분의 Format 행에는 주소가 두 개 있습니다. {handle}/{slug} 형태의 vanity_invoke_url과, Format의 영구적인 skl_… id 형태의 invoke_url입니다.

아래 내용은 2026-09-26에 확인한 내 Format 찾기 (영문), Format 주소 지정하기 (영문), Format의 실행 목록 (영문)에서 가져왔습니다. 카탈로그의 각 Format이 무엇을 만드는지는 바로 쓰는 제품 영상 Format에서 다룹니다.

내 키로 호출할 수 있는 Format은 어떻게 나열하나요?

GET /v1/formats를 호출하세요. limit은 1–100이고 기본값은 50입니다. has_more가 true인 동안에는 next_cursor를 cursor로 다시 넘겨 다음 페이지를 받으세요.

무엇이 보이는지는 키가 정합니다. 개인 키는 여러분의 개인 Format을 나열하고, 팀 키는 모든 멤버에게 그 워크스페이스의 Format을 나열하며, 어느 쪽도 다른 쪽의 Format은 나열하지 않습니다. 키의 워크스페이스 밖에 있는 Format은 존재하지 않는 id와 똑같이 404 format_not_found입니다. 그러니 있어야 할 Format이 보이지 않는다면 다른 쪽 키를 들고 있는 것입니다.

curl -sS "https://api.sume.com/v1/formats?limit=50" \
  -H "Authorization: Bearer $SUME_API_KEY"

어떤 주소로 호출하고, 어떤 주소를 저장해야 하나요?

{handle}/{slug}와 {format_id} 형태는 같은 Format으로 해석되고 같은 파이프라인을 실행합니다. 본문, 헤더, 멱등성, 상한, 영수증이 모두 같습니다. 어느 형태를 썼든 영수증의 format.id는 항상 불투명한 skl_… id입니다.

handle 이름이 바뀌면 저장해 둔 URL은 어떻게 되나요?

handle은 팀 Format이면 소유 워크스페이스의 handle이고, 개인 Format이면 여러분 자신의 handle입니다. 불투명한 skl_… 경로인 invoke_url은 이름이 바뀌어도 영구적이므로, handle이나 slug가 바뀌어도 저장된 URL이 유지되어야 한다면 이 값을 저장하세요. 이름을 바꾼 handle은 90일 동안 계속 해석됩니다. API 레퍼런스는 vanity_invoke_url을 편의용 주소라고 설명합니다. 두 부분 중 어느 쪽 이름을 바꿔도 이 주소는 바뀝니다.

있어야 할 Format이 왜 404를 돌려주나요?

알 수 없는 handle, 알 수 없는 slug, 볼 수 없는 handle은 모두 같은 404 format_not_found로 응답합니다. 보관된 Format, 키의 워크스페이스 밖에 있는 Format, 공유 권한이 아직 대기 중이거나 제거된 공유 Format도 마찬가지입니다. 404가 아닌 응답은 두 가지입니다.

• 403 insufficient_scope: 키에 formats:read나 formats:write가 없습니다. 스코프가 빠진 경우는 절대 404 format_not_found가 아닙니다.
• 403 workspace_key_required: 팀은 맞지만 키가 틀렸습니다. 팀 워크스페이스의 멤버인데 개인 키를 보낸 경우입니다. Sume API 키 동작 방식을 참고하세요.

호출하기 전에 Format 하나를 어떻게 읽나요?

주소로는 GET /v1/formats/{handle}/{slug}, id로는 GET /v1/formats/{format_id}로 읽으세요. 문서의 쿡북은 이 호출을 설정 화면의 사전 점검으로 씁니다. 주소가 키로 해석되는지, Format이 무엇을 받는지, 상한이 얼마인지 확인합니다. 레시피 본문은 의도적으로 응답에 포함되지 않습니다.

status와 api_trigger_enabled가 모두 API 실행을 허용해야 합니다. 다만 API로 한 번도 실행하지 않은 Format은 첫 실행 전까지 inactive / false로 보일 수 있으며, 그래도 실행됩니다. 이 값을 연동의 조건으로 삼지 마세요. 파트너에게 Format 하나의 curl, 스코프, 폴링 루프를 건네려면 https://docs.sume.com/formats/{handle}/{slug}에 있는 콜 시트를 공유하세요. 콜 시트는 Format 본문의 내용을 전혀 보여 주지 않습니다.

curl -sS "https://api.sume.com/v1/formats/acme/product-promo" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq '.data | {id, handle, slug, version, status, api_trigger_enabled, io,
      cap_usd: (.generation_spend_cap_usd_micros / 1000000), vanity_invoke_url}'

Format의 실행 목록은 어떻게 보나요?

GET /v1/formats/{handle}/{slug}/runs나, 불투명 경로 쌍인 GET /v1/formats/{format_id}/runs는 실행을 최신순으로 돌려줍니다. limit은 1–100이고 기본값은 20입니다. cursor는 불투명한 값이며 (created_at, id) 기준 keyset이므로, 페이지를 넘기는 동안 새 실행이 생겨도 행이 밀리지 않습니다. Sume가 발급하지 않은 cursor는 400 invalid_request입니다. API로 한 번도 실행하지 않은 Format은 404가 아니라 빈 목록을 돌려줍니다.

• GET /v1/format-runs는 없습니다. Format별로 나열하거나, 생성할 때 저장한 실행 id로 자체 색인을 관리하세요.
• 실행 하나는 /v1/format-runs/{run_id}에서 읽으세요. Format 경로로는 생성과 목록 조회만 합니다.
• GET /v1/format-runs/{run_id}/messages는 없습니다. 대화 내용은 API로 공개되지 않습니다.