API docs by Redocly

Sakura AI Engine RAG API (2026-02-25)

Download OpenAPI specification:Download

さくらのAI Engine RAG API

documents_list

Authorizations:
BearerAuth
query Parameters
model
string
name
string
page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page.

tag
string

Responses

Response samples

Content type
application/json
{
  • "meta": {},
  • "results": [
    ]
}

documents_retrieve

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

A UUID string identifying this document.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "name": "string",
  • "model": "string",
  • "chunk_size": 0,
  • "chunk_count": 0,
  • "tags": [
    ],
  • "content": "string",
  • "error_message": "string"
}

documents_update

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

A UUID string identifying this document.

Request Body schema: application/json
name
required
string <= 255 characters
tags
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "name": "string",
  • "model": "string",
  • "chunk_size": 0,
  • "chunk_count": 0,
  • "tags": [
    ],
  • "content": "string",
  • "error_message": "string"
}

documents_destroy

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

A UUID string identifying this document.

Responses

chunks

document_chunks_list

ドキュメント配下のチャンク一覧/単体取得用 ViewSet。

  • list: /documents/{document_id}/chunks/
  • retrieve: /documents/{document_id}/chunks/{index}/ ← index で取得
Authorizations:
BearerAuth
path Parameters
document_pk
required
string
query Parameters
page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page.

Responses

Response samples

Content type
application/json
{
  • "meta": {},
  • "results": [
    ]
}

document_chunks_retrieve

ドキュメント配下のチャンク一覧/単体取得用 ViewSet。

  • list: /documents/{document_id}/chunks/
  • retrieve: /documents/{document_id}/chunks/{index}/ ← index で取得
Authorizations:
BearerAuth
path Parameters
document_pk
required
string
index
required
string^\d+$

Responses

Response samples

Content type
application/json
{
  • "document": {
    },
  • "chunk_index": 0,
  • "content": "string",
  • "metadata": {
    }
}

chat

documents_chat

Authorizations:
BearerAuth
Request Body schema: application/json
distance_type
string
Default: "cosine"
Enum: "cosine" "l2"

類似度計算に使用する距離メトリクスです。

  • cosine: コサイン距離

  • l2: L2距離（ユークリッド距離）

  • cosine - cosine

  • l2 - l2

model
string <= 255 characters
Default: "multilingual-e5-large"

検索時に使用する埋め込みモデルを指定します。 指定したモデルでクエリおよびドキュメントの埋め込みを生成し、 類似度検索を行います。(利用可能なモデルはコントロールパネル等をご確認ください。)

chat_model
required
string <= 255 characters

回答生成に使用するチャットモデルを指定します。 検索結果をもとに、このモデルを用いて回答文を生成します。(利用可能なモデルはコントロールパネル等をご確認ください。)

query
required
string <= 1000 characters

質問文を指定します。 指定されたクエリは検索および回答生成の両方に使用されます。

prompt
string <= 2000 characters

回答生成時のsystem_promptに追加されるカスタム指示文を指定します。 口調の指定や回答形式の制御などに利用できます。 未指定の場合は、デフォルトのsystem_promptが使用されます。

tags
Array of strings[ items <= 255 characters ]

検索対象にするタグを指定します。 指定したタグが含まれるドキュメントのみが検索対象となります。 複数指定した場合はすべてのタグが指定されているドキュメントのみ対象となります。

top_k
integer [ 1 .. 100 ]
Default: 5

検索結果として取得する最大件数を指定します。 類似度の高いドキュメントから順に、この件数分が使用されます。

threshold
number <double> [ 0 .. 1 ]
Default: 0.3

類似度の閾値を指定します。 この値よりも類似度が低いドキュメントは検索結果から除外されます。

use_full_content
boolean
Default: false

trueの場合は、ドキュメント全文をコンテキストとして使用します。 falseの場合は、分割されたチャンク単位で検索・回答生成を行います。

Responses

Request samples

Content type
application/json
{
  • "distance_type": "cosine",
  • "model": "multilingual-e5-large",
  • "chat_model": "string",
  • "query": "string",
  • "prompt": "string",
  • "tags": [
    ],
  • "top_k": 5,
  • "threshold": 0.3,
  • "use_full_content": false
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "sources": [
    ]
}

query

documents_query

Authorizations:
BearerAuth
query Parameters
model
string
name
string
tag
string
Request Body schema: application/json
model
string <= 255 characters
Default: "multilingual-e5-large"

クエリのベクトル化に利用するモデル。

query
required
string <= 1000 characters
tags
Array of strings[ items <= 255 characters ]

すべてのタグを持つドキュメントのみ対象。

top_k
integer [ 1 .. 100 ]
Default: 3

返す検索結果の最大件数。

threshold
number <double> [ 0 .. 1 ]
Default: 0.3

類似度のしきい値。この值よりも類似度が低いドキュメントは検索結果から除外されます。

distance_type
string
Default: "cosine"
Enum: "cosine" "l2"

類似度計算に使用する距離メトリクスです。

  • cosine: コサイン距離。テキストの類似度測定に適しており、値の範囲は0〜2（0が完全に一致）です。

  • l2: L2距離（ユークリッド距離）。ベクトル空間での直線距離で、数値データの類似度測定に適しています。値の範囲は0〜∞（0が完全に一致）です。

  • cosine - cosine

  • l2 - l2

Responses

Request samples

Content type
application/json
{
  • "model": "multilingual-e5-large",
  • "query": "string",
  • "tags": [
    ],
  • "top_k": 3,
  • "threshold": 0.3,
  • "distance_type": "cosine"
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

upload

documents_upload

Authorizations:
BearerAuth
Request Body schema:
file
required
string <uri>
name
string <= 255 characters

未指定の場合はアップロードされたファイル名が使用されます。

tags
Array of strings
model
string
Enum: "multilingual-e5-large" "preview/Qwen3-Embedding-4B-FP16"

ベクトル化に利用するモデル。

  • multilingual-e5-large - multilingual-e5-large
  • preview/Qwen3-Embedding-4B-FP16 - preview/Qwen3-Embedding-4B-FP16
chunk_size
integer

モデルによって最大値が異なります。未指定の場合はモデルのデフォルト値が設定されます。

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "status": "pending",
  • "content": "string",
  • "name": "string",
  • "tags": [
    ],
  • "model": "multilingual-e5-large",
  • "chunk_size": 0
}