문서

문서는 AI 에이전트 지식 베이스의 구성 요소입니다. 각 문서는 도움말 페이지, FAQ, 제품 설명 등 AI가 알아야 할 지식 하나를 나타냅니다.

문서는 세 종류입니다. Article은 제목과 본문이 있는 전체 문서, Paragraph는 짧은 독립 텍스트, URL 문서는 웹 콘텐츠를 가져올 때 자동 생성됩니다. API로 직접 만들거나 외부 콘텐츠 가져오기로 웹사이트에서 가져오거나 파일 업로드나 Intercom 동기화를 사용할 수 있습니다.

재학습 단계는 없습니다. 생성, 수정, 삭제한 문서는 백그라운드에서 자동 처리되며 보통 수초 안에 완료되는 즉시 반영됩니다. 아래 embed_state 또는 지식 베이스 설정 조회의 pending_embed_count로 추적하세요.

선택적으로 사용할 수 있는 예시 검사

• API Action 요청 미리보기. 요청을 보내지 않고 가상 예시 값으로 제공한 요청 템플릿을 렌더링합니다. 인증 헤더는 제외하세요.

• JSONPath 일치 미리보기. 제공한 JSON에서 루트, 필드, 배열 인덱스, 와일드카드 경로를 검사합니다. Action을 실행하거나 대화 메모리를 저장하지 않습니다.

문서 생성

권한 범위: write_all

POST https://app.quickchat.ai/v1/api/knowledge_base/articles/

요청 본문

매개변수	설명
content 문자열, 필수	문서 내용
type 문자열	"Article"(기본값) 또는 "Paragraph"
title 문자열	문서 제목

문서 유형

• "Article": 제목과 본문이 있는 전체 지식 베이스 문서. FAQ, 도움말, 제품 설명에 사용하세요.
• "Paragraph": 제목 없는 짧은 독립 텍스트. 간단한 사실, 한 줄 답변, 빠른 참조 정보에 사용하세요.
• "URL"(읽기 전용): 웹사이트 콘텐츠를 가져올 때 자동 생성됩니다. 수집한 페이지 내용과 소스 URL을 포함하며 생성 시 직접 지정할 수 없습니다.

Shell

curl -X POST https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "content": "Our return policy allows returns within 30 days.",
  "title": "Return Policy"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "content": "Our return policy allows returns within 30 days.",
        "title": "Return Policy",
    },
)
data = response.json()

응답 201 Created

{
  "id": 1234,
  "article_id": "abc-123",
  "type": "Article",
  "title": "Return Policy",
  "description": "",
  "content": "Our return policy allows returns within 30 days.",
  "state": "draft",
  "deploy_state": "draft",
  "embed_state": "pending",
  "refresh_failure_reason": "",
  "version": null,
  "max_available_version": null,
  "url": null,
  "tags": [],
  "created_timestamp": "2026-01-15",
  "last_modified_timestamp": "2026-01-15",
  "downloaded_timestamp": "2026-01-15",
  "last_updated_timestamp": "2026-01-15",
  "last_updated_from_external_source_timestamp": null
}

필드	설명
id 정수	문서 숫자 ID. 모든 URL 경로에서 사용하는 공식 식별자입니다.
article_id 문자열	기존 문자열 식별자. 비어 있을 수 있으므로 id를 사용하세요.
type 문자열	"Article", "Paragraph", "URL"
title 문자열	문서 제목
description 문자열	문서 설명
content 문자열	문서 내용
deploy_state 문자열	"draft" 또는 "published". 라벨일 뿐입니다(아래 참고).
embed_state 문자열 또는 null	반영 상태: "pending", "embedding", "embedded", "failed"(아래 참고)
state 문자열	내부 처리 상태(아래 참고)
refresh_failure_reason 문자열	마지막 URL 새로고침의 실패 원인. 분류된 실패가 저장되지 않았으면 비어 있습니다.
version 정수 또는 null	현재 버전 번호
max_available_version 정수 또는 null	사용 가능한 가장 높은 버전
url 문자열 또는 null	소스 URL(URL 유형 문서)
tags 문자열 배열	관련 태그
created_timestamp 문자열	생성일
last_modified_timestamp 문자열	마지막 수정일
downloaded_timestamp 문자열	다운로드일
last_updated_timestamp 문자열	마지막 업데이트일
last_updated_from_external_source_timestamp 문자열 또는 null	마지막 외부 소스 업데이트

문서 상태 이해하기

문서에는 세 가지 상태 필드가 있습니다. AI 에이전트의 문서 사용 여부를 알려주는 필드는 하나뿐입니다.

• embed_state: 가장 중요한 필드입니다. "pending"과 "embedding"은 처리 중, "embedded"는 반영되어 AI가 사용 중, "failed"는 처리 미완료로 사용하지 않는다는 뜻입니다. 쓰기 후 이 필드를 폴링하세요.
• deploy_state: "draft" 또는 "published". 자체 정리용 라벨일 뿐이며 AI의 사용 여부에는 영향을 주지 않습니다.
• state: 내부 콘텐츠 가져오기 상태. 대부분의 API 사용자는 무시해도 됩니다. URL 문서의 "refresh_failed"는 마지막 새로고침이 저장된 콘텐츠를 교체하지 못했다는 뜻입니다.
• refresh_failure_reason: 분류된 URL 새로고침 실패의 고정 범주: "http_error", "soft_404", "off_domain_redirect", "auth_wall", "error_page", "empty_content", "thin_content". 페이지 분류 전에 수집이 실패하면 비어 있을 수 있습니다. embed_state도 실패하지 않는 한 마지막 저장 콘텐츠는 계속 사용됩니다.

문서 목록

권한 범위: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/

쿼리 매개변수

매개변수	설명
limit 정수	페이지당 항목 수
offset 정수	건너뛸 항목 수
types 문자열	유형별 필터: Article, Paragraph, URL
tags 문자열	태그 필터
url 문자열	URL 필터
title 문자열	제목 필터
query 문자열	내용 검색

Shell

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/?limit=10&offset=0' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "offset": 0},
)
data = response.json()

응답 200 OK

{
  "items": [
    {
      "id": 1234,
      "article_id": "abc-123",
      "type": "Article",
      "title": "Return Policy",
      "description": "",
      "state": "published",
      "deploy_state": "published",
      "embed_state": "embedded",
      "refresh_failure_reason": "",
      "version": 1,
      "max_available_version": 1,
      "url": null,
      "tags": ["policies"],
      "created_timestamp": "2026-01-15",
      "last_modified_timestamp": "2026-01-15",
      "downloaded_timestamp": "2026-01-15",
      "last_updated_timestamp": "2026-01-15",
      "last_updated_from_external_source_timestamp": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 1
}

참고

목록 응답에는 content 필드가 포함되지 않습니다. 특정 문서의 전체 내용은 문서 조회를 사용하세요.

문서 조회

권한 범위: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

Shell

curl https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

응답 200 OK: content를 포함한 전체 문서 객체를 반환합니다(문서 생성과 같은 스키마).

문서 수정

권한 범위: write_all

PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/{article_id}

요청 본문

매개변수	설명
content 문자열	수정할 문서 내용
title 문자열	수정할 제목
tags 문자열 배열	수정할 태그
save_mode 문자열	"draft"(기본값) 또는 "publish"

주의

save_mode: "draft"는 deploy_state 플래그만 설정하며 AI의 콘텐츠 사용을 막지 않습니다. 초안도 게시된 문서와 똑같이 처리되어 사용됩니다. 준비용 저장으로 의존하지 말고 실제 반영할 준비가 되었을 때만 문서를 쓰세요.

Shell

curl -X PATCH https://app.quickchat.ai/v1/api/knowledge_base/articles/1234 \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "Updated Return Policy",
  "content": "Returns accepted within 60 days.",
  "save_mode": "publish"
}'

Python

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/1234",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "title": "Updated Return Policy",
        "content": "Returns accepted within 60 days.",
        "save_mode": "publish",
    },
)
data = response.json()

응답 200 OK: 수정된 문서 객체를 반환합니다.

문서 삭제

ID로 하나 이상의 문서를 삭제합니다.

권한 범위: write_all

DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/

요청 본문: 문서 ID의 JSON 배열.

Shell

curl -X DELETE https://app.quickchat.ai/v1/api/knowledge_base/articles/ \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '[1234, 5678]'

Python

import requests

response = requests.delete(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json=[1234, 5678],
)

응답 200 OK

문서 검색

텍스트 일치로 문서 내용을 검색합니다.

권한 범위: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/search

쿼리 매개변수

매개변수	설명
query 문자열, 필수	검색어
is_case_insensitive 불리언	대소문자 무시 검색(기본값: true)
with_title_url_and_tags 불리언	제목/URL/태그를 검색에 포함(기본값: true)
strict_search 불리언	정확히 일치해야 함(기본값: false)
num_of_display_articles 정수	표시할 문서 수(기본값: 5)
num_of_data_articles 정수	검색할 문서 수(기본값: 15)

Shell

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/search?query=return%20policy' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/search",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"query": "return policy"},
)
data = response.json()

응답 200 OK

{
  "article_snippets": [
    {
      "article_id": 1234,
      "expository_sentence": "Our return policy allows returns within 30 days.",
      "query_words_ids": [
        {"start_char": 4, "end_char": 10, "text": "return"}
      ]
    }
  ],
  "article_snapshots": {
    "items": [],
    "offset": 0,
    "count": 1
  }
}

단락 목록

Paragraph 유형의 모든 문서를 나열합니다. 단락은 제목과 본문이 있는 전체 Article과 달리 제목 없는 짧은 독립 텍스트입니다.

권한 범위: read_all

GET https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs

쿼리 매개변수

매개변수	설명
limit 정수	페이지당 항목 수
offset 정수	건너뛸 항목 수
query 문자열	내용 필터

Shell

curl 'https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs?limit=10' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/knowledge_base/articles/paragraphs",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10},
)
data = response.json()

응답 200 OK

{
  "items": [
    {
      "id": 1,
      "content": "Our return policy allows returns within 30 days."
    }
  ],
  "offset": 0,
  "count": 1
}

---