베타 라이브러리 문서 엔드포인트

베타 라이브러리 문서 엔드포인트 (Beta Libraries Documents Endpoints)

(beta) Libraries API - 라이브러리 안의 문서를 관리합니다.

출처: 문서

본문

라이브러리에 문서를 업로드하고, 목록·상세·텍스트·처리 상태·서명 URL을 조회하며, 이름·속성을 수정하거나 삭제·재처리하는 엔드포인트예요. 업로드한 문서는 처리가 완료돼야 라이브러리 검색에서 찾을 수 있답니다.

GET /v1/libraries/{library_id}/documents — List documents in a given library (문서 목록)

주어진 라이브러리에 업로드된 문서를 나열합니다.

경로 파라미터:

  • library_id#string (필수)

응답 필드 (200 Successful Response):

  • data#array<Document> (필수) — 문서 목록.
  • pagination#PaginationInfo|null (필수) — Deprecated: offset 페이지네이션 메타데이터. deprecated page 파라미터를 쓰는 호출자에게만 채워지고, page_token을 쓰면 생략돼요. RBAC 필터링 롤아웃 동안 total_items는 대략적 추정치예요. next_page_token을 사용하세요. 이 필드는 offset 페이징이 은퇴하면 제거됩니다.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.libraries.documents.list({
    libraryId: "5c3ca4cd-62bc-4c71-ad8a-1531ae80d078",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.libraries.documents.list(library_id="5c3ca4cd-62bc-4c71-ad8a-1531ae80d078", page_size=100, page=0, sort_by="created_at", sort_order="desc")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "data": [
    {
      "created_at": "2025-12-17T10:25:07.818693Z",
      "extension": null,
      "hash": null,
      "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
      "library_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
      "mime_type": null,
      "name": "My resource",
      "process_status": "self_managed",
      "processing_status": "completed",
      "size": null,
      "tokens_processing_total": 87,
      "uploaded_by_id": null,
      "uploaded_by_type": "User"
    }
  ],
  "pagination": null
}

POST /v1/libraries/{library_id}/documents — Upload a new document (문서 업로드)

라이브러리에 새 문서를 업로드합니다. 처리 대기 큐에 들어가며, 상태는 처리되면 바뀌어요. 처리(processing)가 완료돼야 라이브러리 검색에서 찾을 수 있어요.

경로 파라미터:

  • library_id#string (필수)

요청 본문 (multipart/form-data):

  • file#File (필수) — 업로드할 파일. 커스텀 파일명을 쓰려면 file=@path/to/your/file.jsonl;filename=custom_name.jsonl, 아니면 file=@path/to/your/file.jsonl 형태로 보내면 돼요.

응답 (200): 같은 해시의 문서가 이 라이브러리에 이미 있으면 기존 문서를 반환해요.

응답 필드:

  • id#string (필수), library_id#string (필수), name#string (필수), created_at#date-time (필수), extension#string|null (필수), hash#string|null (필수), mime_type#string|null (필수), size#integer|null (필수), number_of_pages#integer|null, process_status#"self_managed"|"missing_content"|"noop"|"done"|"todo"|"in_progress"|"error"|"waiting_for_capacity" (필수), processing_status#string (필수), tokens_processing_total#integer (필수), tokens_processing_main_content#integer|null, tokens_processing_summary#integer|null, uploaded_by_id#string|null (필수), uploaded_by_type#string (필수), expires_at#date-time|null — 설정되면 이 날짜 이후 자동 삭제돼요, last_processed_at#date-time|null, attributes#map<any>|null, summary#string|null, url#string|null

TypeScript:

import { Mistral } from "@mistralai/mistralai";
import { openAsBlob } from "node:fs";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.libraries.documents.upload({
    libraryId: "a02150d9-5ee0-4877-b62c-28b1fcdf3b76",
    requestBody: {
      file: await openAsBlob("example.file"),
    },
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.libraries.documents.upload(library_id="a02150d9-5ee0-4877-b62c-28b1fcdf3b76", file={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    })

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "file": {
    "content": "ipsum eiusmod",
    "fileName": "consequat do"
  }
}'

응답 예시 (200):

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "extension": null,
  "hash": null,
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "library_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "mime_type": null,
  "name": "My resource",
  "process_status": "self_managed",
  "processing_status": "completed",
  "size": null,
  "tokens_processing_total": 87,
  "uploaded_by_id": null,
  "uploaded_by_type": "User"
}

GET /v1/libraries/{library_id}/documents/{document_id} — Retrieve the metadata of a specific document (문서 메타데이터 조회)

라이브러리와 그 안의 문서를 지정해 문서의 메타데이터를 가져옵니다.

경로 파라미터:

  • library_id#string (필수), document_id#string (필수)

응답 필드 (200 Successful Response): 업로드 응답과 동일한 Document 필드 목록.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.libraries.documents.get({
    libraryId: "03d908c8-90a1-44fd-bf3a-8490fb7c9a03",
    documentId: "90973aec-0508-4375-8b00-91d732414745",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.libraries.documents.get(library_id="03d908c8-90a1-44fd-bf3a-8490fb7c9a03", document_id="90973aec-0508-4375-8b00-91d732414745")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents/{document_id} \
 -X GET \
 -H 'Authorization: Bearer ***'

PUT /v1/libraries/{library_id}/documents/{document_id} — Update the metadata of a specific document (문서 갱신)

라이브러리와 그 안의 문서를 지정해 문서 이름을 갱신합니다.

경로 파라미터:

  • library_id#string (필수), document_id#string (필수)

요청 본문:

  • name#string — 새 이름.
  • expires_at#date-time|null — 설정 시 이 날짜 이후 자동 삭제.
  • attributes#map<boolean|string|integer|number|date-time|array<string>|array<integer>|array<number>|array<boolean>>|null

응답 필드 (200 Successful Response): Document 필드 목록.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: "MISTR...EY",
});

async function run() {
  const result = await mistral.beta.libraries.documents.librariesDocumentsUpdateV1({
    libraryId: "3ddd8d93-dca5-4a6d-980d-173226c35742",
    documentId: "2a25e44c-b160-40ca-b5c2-b65fb2fcae34",
    updateDocumentRequest: {},
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.libraries.documents.libraries_documents_update_v1(library_id="3ddd8d93-dca5-4a6d-980d-173226c35742", document_id="2a25e44c-b160-40ca-b5c2-b65fb2fcae34")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents/{document_id} \
 -X PUT \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

DELETE /v1/libraries/{library_id}/documents/{document_id} — Delete a document (문서 삭제)

라이브러리와 그 안의 문서를 지정해 삭제합니다. 라이브러리와 검색 인덱스에서 함께 제거돼요.

경로 파라미터:

  • library_id#string (필수), document_id#string (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  await mistral.beta.libraries.documents.delete({
    libraryId: "005daae9-d42e-407d-82d7-2261c6a1496c",
    documentId: "edc236b0-baff-49a9-884b-4ca36a258da4",
  });

}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    mistral.beta.libraries.documents.delete(library_id="005daae9-d42e-407d-82d7-2261c6a1496c", document_id="edc236b0-baff-49a9-884b-4ca36a258da4")

    # Use the SDK ...

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents/{document_id} \
 -X DELETE \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json'

PATCH /v1/libraries/{library_id}/documents/{document_id} — Update the metadata of a specific document (문서 부분 갱신)

라이브러리와 그 안의 문서를 지정해 이름과/또는 속성을 부분 갱신합니다.

경로 파라미터:

  • library_id#string (필수), document_id#string (필수)

요청 본문:

  • name#string
  • expires_at#date-time|null
  • attributes#map<boolean|string|integer|number|date-time|array<string>|array<integer>|array<number>|array<boolean>>|null

응답 필드 (200 Successful Response): Document 필드 목록.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.libraries.documents.update({
    libraryId: "2a41249e-52ca-4436-b755-25ce3a9bfb53",
    documentId: "bc26fa54-e5d9-4269-bedf-86bed5471c7d",
    updateDocumentRequest: {},
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.libraries.documents.update(library_id="2a41249e-52ca-4436-b755-25ce3a9bfb53", document_id="bc26fa54-e5d9-4269-bedf-86bed5471c7d")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents/{document_id} \
 -X PATCH \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

GET /v1/libraries/{library_id}/documents/{document_id}/text_content — Retrieve the text content (문서 텍스트 조회)

문서가 있으면 그 텍스트 내용을 가져옵니다. pdf·docx·pptx 같은 문서는 Mistral OCR로 처리한 결과 텍스트예요.

경로/쿼리 파라미터:

  • library_id#string (필수), document_id#string (필수)
  • page_start#integer|null, page_end#integer|null — 페이지 범위.

응답 필드 (200 Successful Response):

  • text#string (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.libraries.documents.textContent({
    libraryId: "1d177215-3b6b-45ba-9fa9-baf773223bec",
    documentId: "60214c91-2aba-4692-a4e6-a53365de8caf",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.libraries.documents.text_content(library_id="1d177215-3b6b-45ba-9fa9-baf773223bec", document_id="60214c91-2aba-4692-a4e6-a53365de8caf")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents/{document_id}/text_content \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "text": "Example text."
}

GET /v1/libraries/{library_id}/documents/{document_id}/status — Retrieve the processing status (처리 상태 조회)

문서의 처리 상태를 가져옵니다.

경로 파라미터:

  • library_id#string (필수), document_id#string (필수)

응답 필드 (200 Successful Response):

  • document_id#string (필수)
  • process_status#"self_managed"|"missing_content"|"noop"|"done"|"todo"|"in_progress"|"error"|"waiting_for_capacity" (필수)
  • processing_status#string (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.libraries.documents.status({
    libraryId: "e6906f70-368f-4155-80da-c1718f01bc43",
    documentId: "2c904915-d831-4e9d-a345-8ce405bcef66",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.libraries.documents.status(library_id="e6906f70-368f-4155-80da-c1718f01bc43", document_id="2c904915-d831-4e9d-a345-8ce405bcef66")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents/{document_id}/status \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "document_id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "process_status": "self_managed",
  "processing_status": "completed"
}

GET /v1/libraries/{library_id}/documents/{document_id}/signed-url — Retrieve the signed URL (서명 URL 조회)

문서의 서명 URL을 가져옵니다. URL은 30분 후 만료되며, 링크가 있는 사람은 누구나 접근할 수 있어요.

경로 파라미터:

  • library_id#string (필수), document_id#string (필수)

응답 (200): 타입 string — 서명 URL.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.libraries.documents.getSignedUrl({
    libraryId: "23cf6904-a602-4ee8-9f5b-8efc557c336d",
    documentId: "48598486-df71-4994-acbb-1133c72efa8c",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.libraries.documents.get_signed_url(library_id="23cf6904-a602-4ee8-9f5b-8efc557c336d", document_id="48598486-df71-4994-acbb-1133c72efa8c")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents/{document_id}/signed-url \
 -X GET \
 -H 'Authorization: Bearer ***'

GET /v1/libraries/{library_id}/documents/{document_id}/extracted-text-signed-url — Retrieve signed URL of extracted text (추출 텍스트 서명 URL)

문서에서 추출된 텍스트의 서명 URL을 가져옵니다. OCR로 보낸 문서라면 OCR 쿼리 결과를 반환해요.

경로 파라미터:

  • library_id#string (필수), document_id#string (필수)

응답 (200): 타입 string — 서명 URL.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.beta.libraries.documents.extractedTextSignedUrl({
    libraryId: "a6f15de3-1e82-4f95-af82-851499042ef8",
    documentId: "9749d4f9-24e5-4ca2-99a3-a406863f805d",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.beta.libraries.documents.extracted_text_signed_url(library_id="a6f15de3-1e82-4f95-af82-851499042ef8", document_id="9749d4f9-24e5-4ca2-99a3-a406863f805d")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents/{document_id}/extracted-text-signed-url \
 -X GET \
 -H 'Authorization: Bearer ***'

POST /v1/libraries/{library_id}/documents/{document_id}/reprocess — Reprocess a document (문서 재처리)

문서를 다시 처리합니다. 다시 청구(billing)가 될 수 있어요.

경로 파라미터:

  • library_id#string (필수), document_id#string (필수)

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  await mistral.beta.libraries.documents.reprocess({
    libraryId: "51b29371-de8f-4ba4-932b-a0bafb3a7f64",
    documentId: "3052422c-49ca-45ac-a918-cadb35d61fd8",
  });

}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    mistral.beta.libraries.documents.reprocess(library_id="51b29371-de8f-4ba4-932b-a0bafb3a7f64", document_id="3052422c-49ca-45ac-a918-cadb35d61fd8")

    # Use the SDK ...

curl:

curl https://api.mistral.ai/v1/libraries/{library_id}/documents/{document_id}/reprocess \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json'

더 알아보기 (Learn more)