POST/v1/push/sources/{source_id}/documents

문서 보내기(생성 또는 교체)

push_upsert_document

external_id 값으로 문서를 생성하거나 교체해요. JSON으로 보낼 때는 내용을 content 필드에 넣어요(content_type: html, markdown 또는 text, 최대 5MB). multipart/form-data로 보낼 때는 파일을 file 파트에 넣고(최대 100MB, 지식 베이스 업로드와 같은 형식), 메타데이터는 document 파트(content 필드를 뺀 같은 형식의 JSON)나 개별 필드 external_id, title, url, path, tags로 보내요. sync_number 값은 열린 동기화의 번호예요. 이 값이 없으면 문서를 바로 쓰지만(직접 쓰기), 다시 보내지 않으면 다음 전체 동기화에서 삭제돼요. 같은 문서를 다시 보내면 unchanged를 반환해요(멱등). 문서는 소스의 다음 동기화 때 카드가 돼요(1분 안에, 열린 동기화 안에서는 동기화를 닫은 뒤). 1.62.0부터는 카드 필드(metadata, category, verifiers, verify_interval_days), 멀티파트 업로드의 파일(upload_id), 첨부 파일(attachments)도 보낼 수 있으며, 응답에 status와 card_id(문서 결과)가 포함돼요. 소스의 문서 한도는 요금제에 따라 달라요.

인증

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

경로 파라미터

source_idinteger필수

쿼리 파라미터

sync_numberinteger

헤더 파라미터

Idempotency-Keystring
쓰기 요청을 안전하게 재시도하기 위한 키예요. 출력 가능한 ASCII 문자 1~255자이며, 논리적 처리 단위마다 UUID v4를 하나씩 쓰기를 권장해요. 24시간 안에 같은 키로 재시도하면 처리를 다시 실행하지 않고, 저장된 응답(상태, 헤더, 본문)을 Idempotency-Replayed: true 헤더와 함께 반환해요. 같은 키를 다른 메서드, 경로, Content-Type 값이나 본문과 함께 보내면 409 api.idempotency_mismatch 오류를 반환하고, 첫 요청이 아직 실행 중이면 409 api.idempotency_in_progress 오류를 Retry-After: 1 헤더와 함께 반환해요. 5xx나 429 응답 뒤에는 키가 해제되어, 재시도하면 처리가 다시 실행돼요. 키의 적용 범위는 조직과 호출자(API 키, 사용자, 사용자 지정 소스 키)예요.
length ≥ 1, length ≤ 255

요청 본문

application/json

객체: PushDocument

external_idstring필수
회사 시스템의 고정된 문서 ID. 같은 ID로 보내면 문서가 교체돼요.
length ≤ 512
titlestring필수
length ≤ 500
urlstring
회사 시스템에 있는 문서의 링크(http 또는 https).
contentstring
콘텐츠(최대 5MB).
content_typestring
허용 값: htmlmarkdowntext
기본값: "html"
patharray of string | string
문서의 폴더: 이름 배열 또는 “/”로 구분한 문자열(최대 10단계).
permissionsPushPermissions
tagsarray of string
items ≤ 50
author_emailstring
작성자. Sursa 사용자이면 카드의 담당자가 돼요.
updated_atstring (date-time)
회사 시스템에서의 수정 시각(문서 버전의 일부).
metadataMetadataPatch
문서 카드의 metadata 값(1.62.0부터): 객체가 카드의 이전 값을 대체하고, {}는 모든 쌍을 제거해요. metadata 필드가 없으면 카드의 메타데이터가 바뀌지 않아요.
categorystring
카드의 카테고리: 조직 카테고리의 키(GET /v1/categories), 1.62.0부터.
length ≤ 64
verifiersPushVerifiers
verify_interval_daysinteger
카드의 검증 주기(일, 1.62.0부터). 없으면 소스의 주기를 써요.
≥ 1, ≤ 3650
upload_idstring
content 대신 쓰는 멀티파트 업로드의 문서 파일(upl_…, 1.62.0부터). 업로드는 한 번만 사용돼요. 같은 문서를 같은 upload_id 값으로 다시 보내도 업로드가 소진되지 않아요. 설치 환경에서 멀티파트 업로드를 쓸 수 없는 동안에는 문서가 file_rejected 사유로 거부돼요.
length ≤ 64
attachmentsarray of string
멀티파트 업로드(upl_…, 1.62.0부터)로 올린 문서의 첨부 파일: 각 첨부 파일은 같은 폴더, 권한, 카드 필드를 가진 소스의 별도 카드가 돼요. 문서의 새 버전에서 빠진 첨부 파일은 보관돼요.
items ≤ 20

multipart/form-data

filestring (binary)필수
documentstring
문서의 JSON 메타데이터(content 필드를 뺀 PushDocument 필드).
external_idstring
titlestring
urlstring
pathstring
tagsstring

응답

200기록됨

응답 헤더

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
가장 엄격한 한도가 초기화될 때까지 남은 초.
Idempotency-Replayed
true이면 이 Idempotency-Key 값으로 저장된 응답을 재생한 것이에요. 처리는 다시 실행되지 않았어요.

application/json

객체: PushDocumentResult

external_idstring필수
resultstring필수
skipped: 다른 문서가 거부되어 atomic 배치의 문서가 적용되지 않았어요(1.62.0부터).
허용 값: createdupdatedunchangeddeletednot_founderrorskipped
versionstring
문서 버전(콘텐츠와 메타데이터의 SHA-256).
errorstring
사유(result = error일 때).
statusPushDocumentStatusValue
card_idstring | null
이미 기록되었다면 문서의 카드(1.62.0부터).
reasonPushDocumentReason

400잘못된 요청이에요. 파라미터 값이나 객체의 상태 때문에 이 동작을 할 수 없어요(`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

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

404객체가 없거나 접근할 수 없어요. 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

409객체의 상태 때문에 이 동작을 할 수 없어요. 예를 들어 중복이거나, 인덱싱 중이거나, 이미 처리된 작업인 경우예요.

응답 헤더

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

413요청 본문이 허용 크기를 넘었어요.

응답 헤더

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

415지원하지 않는 파일 형식이에요.

응답 헤더

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로 반환할 수 있는 코드예요.

안전한 재시도

POST와 PATCH 요청마다 Idempotency-Key 헤더(예: UUID)를 보내세요. 24시간 안에 같은 키로 재시도하면 요청을 다시 실행하지 않고 저장된 응답을 반환해요.

호출 한도

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

← sources · API 레퍼런스

curl -X POST 'https://api.sursa.com/v1/push/sources/1/documents' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

사용해 보기

API 키

키는 이 탭의 메모리에만 보관되며 https://api.sursa.com 주소로만 전송돼요.

요청은 조직의 실제 데이터에 적용돼요.

Idempotency-Key header

source_id path *

sync_number query

Idempotency-Key

비워 두면 요청마다 새 키가 생성돼요.

요청 본문(JSON)