본문으로 건너뛰기
Sursa Developers

GET/v1/catalog/services

카탈로그의 서비스 목록 조회

list_catalog_services

외부 서비스(SaaS와 공급업체) 전역 카탈로그의 항목을 반환해요. 이름, 그룹, 웹사이트 도메인에서 대소문자를 구분하지 않는 부분 문자열 검색, 카테고리 필터, 페이지네이션을 쓸 수 있어요. 필터에 맞는 전체 개수는 X-Total-Count 헤더에 있어요. 카탈로그는 모든 조직이 함께 쓰며, 로그인한 사용자라면 누구나 쓸 수 있어요. 카탈로그 데이터는 Sursa와 함께 제공되고 릴리스마다 갱신돼요(버전은 GET /v1/catalog/categories 응답과 각 항목의 icon_url에 있는 version 필드에 있어요).

인증

Authorization 헤더로 API 키를 보내세요: Authorization: Bearer <키>.

쿼리 파라미터

  • qstring | null

    이름, 그룹, 웹사이트 도메인의 부분 문자열(대소문자 구분 안 함).

    length ≤ 200

  • categorystring | null

    카테고리 슬러그(GET /v1/catalog/categories).

  • offsetinteger

    기본값: 0≥ 0

  • limitinteger

    기본값: 50≥ 1, ≤ 500

  • cursorstring

    같은 필터로 보낸 이전 응답의 X-Next-Cursor 헤더나 next_cursor 값에서 얻은 다음 페이지 커서예요. 커서에는 페이지 크기가 담겨 있어요. offset 파라미터와 함께 보내면 422 validation.failed 오류를, 다른 목록이나 다른 필터의 커서 또는 형식이 잘못된 커서를 보내면 400 api.cursor_invalid 오류를 반환해요.

    length ≤ 512

헤더 파라미터

  • X-View-Asstring

    admin 역할의 API 키만 쓸 수 있어요. <profile>[:viewer|verifier|editor] 형식의 데이터 프로필로 요청을 보내요(예: employee:viewer). 설치 키는 이 헤더를 쓸 수 없어요(403).

쿠키 파라미터

  • kb_view_asstring

    세션의 “View as” 모드(다른 사용자로 보기) 쿠키. POST /auth/view-as 요청으로 설정하고 DELETE /auth/view-as 요청으로 지워요.

응답

200성공 응답

응답 헤더

  • Link

    다음 페이지의 주소(<…>; rel="next"). 헤더가 없으면 마지막 페이지예요.

  • X-Next-Cursor

    cursor 파라미터에 넣을 다음 페이지 커서. 헤더가 없으면 마지막 페이지예요.

  • X-Total-Count

    limit, offset 값과 관계없이 필터에 맞는 전체 항목 수.

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

array of CatalogService
  • categorystring필수

    카테고리 슬러그(GET /v1/catalog/categories).

  • description_enstring | null필수

    영어로 된 짧은 설명. 설명이 없으면 null이에요.

  • domainstring | null필수

    www.를 뺀 웹사이트 도메인. 웹사이트가 없으면 null이에요.

  • group_namestring | null필수

    서비스가 제품군에 속하면 그 그룹(공급업체), 예: Atlassian. 그렇지 않으면 null이에요.

  • iconboolean필수

    Sursa에 아이콘이 함께 제공되는지 여부.

  • icon_urlstring | null필수

    아이콘 URL(/v1/catalog/services/{service_id}/icon?v=… 또는 설치 환경에서 설정한 외부 주소). 아이콘이 없으면 null이에요.

  • idstring (uuid)필수
  • namestring필수
  • slugstring필수
  • websitestring | null필수

    웹사이트 URL(https://…) 또는 null.

401자격 증명(세션 쿠키나 API 키)을 보내지 않았거나 키를 찾을 수 없어요.

응답 헤더

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

403이 동작은 허용되지 않아요. 역할이 부족하거나, 컬렉션이나 카드에 접근할 수 없거나, 요청이 “View as” 모드로 실행 중이거나, 조직이 정지 또는 삭제된 경우예요(`detail` 필드는 `code: org_suspended | org_deleted` 값을 가진 객체예요).

응답 헤더

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

422유효성 검사 오류예요. 본문이나 파라미터가 스키마와 맞지 않거나(`detail` 필드는 유효성 검사 오류 목록), 파라미터 값이 허용 범위를 벗어났어요(`detail` 필드는 메시지).

응답 헤더

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

429요청이 너무 많거나(`api.rate_limited`), 조직의 분·일·월 할당량을 다 썼거나(`api.quota_exceeded`, `error.details` 필드에 `quota`, `limit`, `reset_at` 값이 있어요), 조직의 한도에 도달했거나, 답변 서비스가 바쁜 상태예요(`answers.engine_busy`). `Retry-After` 헤더에 적힌 시간만큼 기다리세요.

응답 헤더

  • Retry-After

    요청을 다시 시도하기 전에 기다릴 초.

  • RateLimit-Policy

    적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.

  • RateLimit

    RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.

  • X-RateLimit-Remaining

    가장 엄격한 한도에서 남은 요청 수.

  • X-RateLimit-Reset

    가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

오류 코드

모든 요청에 공통으로 쓰이는 코드 외에 이 엔드포인트가 error.code로 반환할 수 있는 코드예요.

호출 한도

응답에는 RateLimit, RateLimit-Policy 헤더와 이전 헤더인 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 담겨요. 429 응답에는 초 단위의 Retry-After 헤더가 있어요. 그만큼 기다린 뒤 재시도하세요.

← catalog · API 레퍼런스