본문으로 건너뛰기
Sursa Developers

빠른 시작

이 가이드를 따라 하면 아무것도 없는 상태에서 5분 만에 동작하는 연동을 만들 수 있어요. API 키를 만들어 확인하고, 지식 베이스에 문서를 추가한 다음 그 문서를 찾고 문서에 대해 질문해요. 각 단계는 HTTP 요청 하나예요. 아무 예시에서나 언어를 한 번 고르면 페이지의 모든 예시가 함께 바뀌어요.

언어 전환이 있는 예시는 이 포털의 API 전용 주소를 써요. Sursa 클라우드에서는 https://api.sursa.com이고, 자체 설치 환경에서는 그 설치 환경의 API 전용 주소예요. 예시에 https://api.example.com이 보이면 그 자리에 사용하는 API 전용 주소를 넣으세요. 어떤 주소를 쓰는지 잘 모르겠다면 API 전용 주소와 환경을 참고하세요.

1. API 키 만들기

조직 관리자는 Sursa의 Administration → API keys(관리 → API 키)에서 키를 만들어요. 키에는 어디에 쓰는지 알 수 있는 이름(예: “CRM 동기화”)을 붙이고, 역할을 고른 다음 범위를 더 좁히고 싶다면 스코프도 고르세요. 키는 그 역할의 사용자가 할 수 있는 일만 할 수 있고, 스코프가 허용하는 범위를 넘지 않아요. 이 가이드에서는 editor 역할이면 충분해요.

키는 한 번만 표시돼요. 시스템의 시크릿 저장소에 보관하고, 코드에는 환경 변수로 전달하세요.

export SURSA_API_KEY="kb_…"

모든 요청은 Authorization 헤더에 Bearer 토큰으로 키를 보내요. 역할, 스코프, 만료, 교체는 API 키와 스코프에서 설명해요.

2. 클라이언트 준비하기

라이브러리는 필요 없어요. API는 평범한 HTTPS와 JSON이에요. 이 가이드의 예시는 언어마다 작은 헬퍼를 써요. 사용하는 언어의 헬퍼를 복사해 두세요. 이후 가이드에서도 같은 헬퍼를 써요. 공식 클라이언트 라이브러리는 SDK에서 볼 수 있어요.

# cURL needs no setup: each example below is a complete command.
export SURSA_API="https://api.sursa.com"

3. 키 확인하기

GET /v1/me는 호출자를 설명해요. 조직, 키, 키의 역할과 스코프, 키에 적용되는 호출 한도를 반환해요. 유효한 키라면 어떤 키로든 호출할 수 있어서 모든 연동의 첫 요청으로 가장 좋아요.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"
{
  "principal": "api_key",
  "org": {"id": 1, "slug": "acme", "name": "Acme"},
  "key": {"id": 42, "name": "CRM sync", "prefix": "kb_3f9c", "role": "editor"},
  "user": null,
  "role": "editor",
  "scopes": ["cards:read", "cards:write", "search", "ask"],
  "data_profile": null,
  "expires_at": null,
  "rate_limit": {"class": "standard", "requests_per_second": 20, "burst": 100}
}

401 응답에 auth.not_authenticated 코드가 오면 키가 없거나, 폐기되었거나, 잘못 입력되었다는 뜻이에요. api_keys.expired 코드는 키가 만료되었다는 뜻이에요.

4. 컬렉션 찾기

카드는 컬렉션 안에 있어요. GET /v1/collections는 키로 볼 수 있는 컬렉션 목록을 반환해요.

curl https://api.sursa.com/v1/collections \
  -H "Authorization: Bearer $SURSA_API_KEY"

작업할 컬렉션의 id와 name 값을 기록해 두세요. 아래 예시는 이름이 support인 컬렉션 3을 사용해요.

5. 문서 추가하기

PUT /v1/cards-by-external-id/{external_id}는 직접 정한 ID로 카드를 만들고, 카드가 이미 있으면 교체해요. 같은 요청을 두 번 보내도 안전해요. 두 번째에는 내용이 바뀌지 않았으므로 응답이 skipped이고 이유는 unchanged예요. 회사 시스템에 있는 해당 항목의 ID를 external_id 값으로 쓰세요.

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 '{
    "collection_id": 3,
    "title": "Refund policy",
    "content_type": "markdown",
    "body": "# Refund policy\n\nRefunds are processed within 14 days of the request."
  }'

요청은 카드를 찾을 수 있는 상태가 되면 응답을 반환해요. 새 카드는 201과 "status": "ready", 교체한 카드는 200이에요. HTML과 일반 텍스트도 "content_type": "html" 또는 "text" 값으로 똑같이 보낼 수 있어요. 파일(PDF, Word, Excel 등)은 같은 엔드포인트에 multipart/form-data 형식으로 보내요. 파일, 폴더, 메타데이터, 많은 문서를 한꺼번에 가져오는 방법은 문서 가져오기에서 다뤄요.

POST /v1/search는 쿼리와 일치하는 카드의 발췌문을 가장 잘 맞는 것부터 찾아 줘요.

curl -X POST https://api.sursa.com/v1/search \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund policy", "collection": "support"}'

collection 값에는 컬렉션 이름을 넣어요. 생략하면 이름이 default인 컬렉션에서 검색해요.

7. 질문하기

POST /v1/ask는 자연어 질문에 답하고 답변의 출처를 반환해요. 어시스턴트는 관련 지식을 찾아, 키가 읽을 수 있는 카드만으로 답변해요.

curl -X POST https://api.sursa.com/v1/ask \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How long does a refund take?", "collection": "support"}'

관련된 내용을 찾지 못해도 응답은 200이며, "empty": "no_hits"와 함께 answer 필드에 짧은 설명이 담겨요. 이때 사용자에게 무엇을 보여 줄지는 코드에서 정하세요.

다음 단계