> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt > Use this file to discover all available pages before exploring further. # 지식 베이스 문서 조회 > knowledge base의 source document 1건을 조회합니다. 메타데이터와 추출된 본문 텍스트를 함께 반환하며, 본문은 한 번에 최대 40,000자씩 나누어 반환합니다. `next_cursor`가 `null`이 될 때까지 따라가면 전체 본문을 읽을 수 있습니다. file document는 원본 업로드 파일을 내려받을 수 있는 단기 `source_file_url`도 포함합니다. 페이지를 넘기는 사이에 본문이 교체되면 409 `KNOWLEDGE_DOCUMENT_CONTENT_CHANGED`를 반환하며, 이때는 cursor 없이 처음부터 다시 읽어야 합니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json get /knowledges/{knowledge_id}/documents/{document_id} openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 워크스페이스 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 대량 발신 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /knowledges/{knowledge_id}/documents/{document_id}: get: tags: - Knowledge Documents summary: 지식 베이스 문서 조회 description: >- knowledge base의 source document 1건을 조회합니다. 메타데이터와 추출된 본문 텍스트를 함께 반환하며, 본문은 한 번에 최대 40,000자씩 나누어 반환합니다. `next_cursor`가 `null`이 될 때까지 따라가면 전체 본문을 읽을 수 있습니다. file document는 원본 업로드 파일을 내려받을 수 있는 단기 `source_file_url`도 포함합니다. 페이지를 넘기는 사이에 본문이 교체되면 409 `KNOWLEDGE_DOCUMENT_CONTENT_CHANGED`를 반환하며, 이때는 cursor 없이 처음부터 다시 읽어야 합니다. operationId: getKnowledgeDocument parameters: - name: knowledge_id in: path required: true schema: type: integer minimum: 1 description: '`GET /v3/knowledges`에서 반환되는 숫자형 public knowledge ID입니다.' title: Knowledge Id description: '`GET /v3/knowledges`에서 반환되는 숫자형 public knowledge ID입니다.' - name: document_id in: path required: true schema: type: string format: uuid description: knowledge document ID입니다. title: Document Id description: knowledge document ID입니다. - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' description: >- 이전 응답의 `next_cursor` 값입니다. 다음 페이지를 조회할 때 그대로 전달합니다. 처음부터 읽을 때는 생략합니다. title: Cursor description: >- 이전 응답의 `next_cursor` 값입니다. 다음 페이지를 조회할 때 그대로 전달합니다. 처음부터 읽을 때는 생략합니다. responses: '200': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/KnowledgeDocumentDetail' '400': description: 요청 검증 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한이 없습니다. value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: knowledge document를 찾을 수 없습니다. value: error: code: KNOWLEDGE_DOCUMENT_NOT_FOUND message: 지식 문서를 찾을 수 없습니다. details: document_id: 55555555-5555-4555-8555-555555555555 '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: contentChanged: summary: 페이지를 넘기는 사이 본문이 교체되었습니다. value: error: code: KNOWLEDGE_DOCUMENT_CONTENT_CHANGED message: 문서 본문이 바뀌었습니다. cursor 없이 처음부터 다시 읽어주세요. details: {} '429': description: >- 요청 한도를 초과했습니다. API 키 트래픽은 기본값으로 워크스페이스당 초당 5회·분당 120회, Supabase JWT 트래픽은 기본값으로 사용자당 초당 10회·분당 240회로 제한되며, 워크스페이스 대시보드에는 기본 분당 2,400회의 백스톱 한도가 적용됩니다. 한도는 운영자가 조정할 수 있고, 초과한 버킷의 실제 한도와 윈도우는 429 응답의 X-RateLimit-Limit·X-RateLimit-Window 헤더로 알려 줍니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. headers: Retry-After: description: >- 초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우가 초기화될 때까지 남은 시간입니다. 단위는 초입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Limit: description: >- 초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 최대 요청 수입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Window: description: >- 초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 길이입니다. 단위는 초입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 10 window_seconds: 1 scope: user '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류가 발생했습니다. value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스를 일시적으로 사용할 수 없습니다. value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} storageUnavailable: summary: document 저장소를 읽지 못했습니다. value: error: code: KNOWLEDGE_DOCUMENT_STORAGE_UNAVAILABLE message: 문서 저장소를 읽지 못했습니다. 잠시 후 다시 시도해주세요. details: {} security: - BearerAuth: [] components: schemas: KnowledgeDocumentDetail: properties: id: type: string format: uuid title: Id description: knowledge document의 고유 식별자입니다. knowledge_id: type: integer title: Knowledge Id description: 상위 knowledge numeric public ID. name: type: string title: Name description: document 의 이름. document_type: type: string enum: - file - text - webpage title: Document Type description: document 타입. status: type: string enum: - uploading - completed - failed title: Status description: >- 문서 처리 상태입니다. 업로드 중에서 완료 또는 실패로 전환됩니다. 웹페이지 최초 등록은 모든 URL 수집에 성공해야 완료됩니다. 하나라도 실패하면 실패 상태가 됩니다. 이후 갱신에 실패해도 기존 완료 상태와 공개본을 유지합니다. 갱신 결과는 refresh 상태에서, 실패한 페이지는 webpage_failures에서 확인하세요. upload_percentage: anyOf: - type: integer maximum: 100 minimum: 0 - type: 'null' title: Upload Percentage description: 업로드 진행률(%)입니다. `status`가 `uploading`일 때만 의미가 있습니다. 집계 전에는 null입니다. token_count: anyOf: - type: integer - type: 'null' title: Token Count description: document 의 토큰 수. 아직 집계하지 않았다면 null. webpage_urls: anyOf: - items: type: string type: array - type: 'null' items: type: string format: uri title: Webpage Urls description: '`webpage` document일 때만 값이 있습니다. 그 외에는 null입니다.' webpage_failures: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Webpage Failures description: >- webpage document 의 페이지 단위 수집 실패 목록. key 는 URL, value 는 사유 (`HTTP `, `scrape error`, `empty content`, `no scrape result`). HTTP 오류 페이지의 본문은 지식에 포함되지 않는다. 처리 전 또는 webpage 가 아니면 null, 처리 후 실패가 없으면 빈 객체. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. content: anyOf: - type: string - type: 'null' title: Content description: >- 이 페이지에 해당하는 추출 텍스트입니다. 최대 40,000자(Unicode code point 기준)입니다. 추출된 텍스트가 아직 없으면(예: 업로드 중이거나 텍스트 추출 전에 실패한 document) `null`입니다. 빈 문자열은 추출은 되었으나 텍스트가 비어 있다는 뜻입니다. content_length: anyOf: - type: integer - type: 'null' title: Content Length description: >- 페이지가 아닌 전체 추출 텍스트의 길이입니다. 단위는 Unicode code point입니다. `content`가 `null`이면 `null`입니다. next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor description: 다음 페이지 커서입니다. 조회할 항목이 더 없으면 null입니다. source_file_url: anyOf: - type: string - type: 'null' title: Source File Url description: >- file document에서만 값이 있습니다. 업로드한 원본 파일을 내려받을 수 있는 서명 URL이며 15분 동안 유효합니다. text와 webpage document는 `null`입니다. source_file_url_expires_at: anyOf: - type: integer - type: 'null' title: Source File Url Expires At description: >- `source_file_url`의 만료 시각입니다. unix milliseconds 형식입니다. URL이 없으면 `null`입니다. type: object required: - id - knowledge_id - name - document_type - status - created_at title: KnowledgeDocumentDetail description: knowledge document 단건 조회 응답입니다. 요약 필드에 추출 본문 한 쪽과 원본 파일 링크가 더해집니다. ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '워크스페이스 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.