{
  "components": {
    "schemas": {
      "ChatQueryRequest": {
        "properties": {
          "chat_model": {
            "description": "回答生成に使用するチャットモデルを指定します。\n検索結果をもとに、このモデルを用いて回答文を生成します。(利用可能なモデルはコントロールパネル等をご確認ください。)",
            "maxLength": 255,
            "type": "string"
          },
          "distance_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DistanceTypeEnum"
              }
            ],
            "default": "cosine",
            "description": "類似度計算に使用する距離メトリクスです。\n* `cosine`: コサイン距離\n* `l2`: L2距離（ユークリッド距離）\n\n* `cosine` - cosine\n* `l2` - l2"
          },
          "model": {
            "default": "multilingual-e5-large",
            "description": "検索時に使用する埋め込みモデルを指定します。\n指定したモデルでクエリおよびドキュメントの埋め込みを生成し、\n類似度検索を行います。(利用可能なモデルはコントロールパネル等をご確認ください。)",
            "maxLength": 255,
            "type": "string"
          },
          "prompt": {
            "description": "回答生成時の`system_prompt`に追加されるカスタム指示文を指定します。\n口調の指定や回答形式の制御などに利用できます。\n未指定の場合は、デフォルトのsystem_promptが使用されます。",
            "maxLength": 2000,
            "type": "string"
          },
          "query": {
            "description": "質問文を指定します。\n指定されたクエリは検索および回答生成の両方に使用されます。",
            "maxLength": 1000,
            "type": "string"
          },
          "tags": {
            "description": "検索対象にするタグを指定します。\n指定したタグが含まれるドキュメントのみが検索対象となります。\n複数指定した場合はすべてのタグが指定されているドキュメントのみ対象となります。",
            "items": {
              "maxLength": 255,
              "type": "string"
            },
            "type": "array"
          },
          "threshold": {
            "default": 0.3,
            "description": "ベクトル距離のしきい値。この值よりも距離が大きいドキュメントは検索結果から除外されます。",
            "format": "double",
            "maximum": 2,
            "minimum": 0,
            "type": "number"
          },
          "top_k": {
            "default": 5,
            "description": "検索結果として取得する最大件数を指定します。\n類似度の高いドキュメントから順に、この件数分が使用されます。",
            "maximum": 100,
            "minimum": 1,
            "type": "integer"
          },
          "use_full_content": {
            "default": false,
            "description": "trueの場合は、ドキュメント全文をコンテキストとして使用します。\nfalseの場合は、分割されたチャンク単位で検索・回答生成を行います。",
            "type": "boolean"
          }
        },
        "required": [
          "chat_model",
          "query"
        ],
        "type": "object"
      },
      "ChatResult": {
        "properties": {
          "answer": {
            "type": "string"
          },
          "sources": {
            "items": {
              "$ref": "#/components/schemas/ChatResultSource"
            },
            "readOnly": true,
            "type": "array"
          }
        },
        "required": [
          "answer",
          "sources"
        ],
        "type": "object"
      },
      "ChatResultSource": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/QueryResultChunk"
          },
          {
            "$ref": "#/components/schemas/QueryResultDocument"
          }
        ]
      },
      "DistanceTypeEnum": {
        "description": "* `cosine` - cosine\n* `l2` - l2",
        "enum": [
          "cosine",
          "l2"
        ],
        "type": "string"
      },
      "Document": {
        "properties": {
          "chunk_count": {
            "readOnly": true,
            "type": "integer"
          },
          "chunk_size": {
            "readOnly": true,
            "type": "integer"
          },
          "content": {
            "readOnly": true,
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "readOnly": true,
            "type": "string"
          },
          "error_message": {
            "readOnly": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "readOnly": true,
            "type": "string"
          },
          "model": {
            "readOnly": true,
            "type": "string"
          },
          "name": {
            "maxLength": 255,
            "type": "string"
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/StatusEnum"
              }
            ],
            "readOnly": true,
            "title": "ステータス"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "chunk_count",
          "chunk_size",
          "content",
          "created_at",
          "error_message",
          "id",
          "model",
          "name",
          "status"
        ],
        "type": "object"
      },
      "DocumentChunk": {
        "properties": {
          "chunk_index": {
            "readOnly": true,
            "type": "integer"
          },
          "content": {
            "readOnly": true,
            "type": "string"
          },
          "document": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DocumentList"
              }
            ],
            "readOnly": true
          },
          "metadata": {
            "additionalProperties": {},
            "nullable": true,
            "readOnly": true,
            "type": "object"
          }
        },
        "required": [
          "chunk_index",
          "content",
          "document",
          "metadata"
        ],
        "type": "object"
      },
      "DocumentList": {
        "properties": {
          "chunk_count": {
            "readOnly": true,
            "type": "integer"
          },
          "chunk_size": {
            "readOnly": true,
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "readOnly": true,
            "type": "string"
          },
          "error_message": {
            "readOnly": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "readOnly": true,
            "type": "string"
          },
          "model": {
            "readOnly": true,
            "type": "string"
          },
          "name": {
            "maxLength": 255,
            "type": "string"
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/StatusEnum"
              }
            ],
            "readOnly": true,
            "title": "ステータス"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "chunk_count",
          "chunk_size",
          "created_at",
          "error_message",
          "id",
          "model",
          "name",
          "status"
        ],
        "type": "object"
      },
      "DocumentUpload": {
        "properties": {
          "chunk_size": {
            "description": "モデルによって最大値が異なります。未指定の場合はモデルのデフォルト値が設定されます。",
            "type": "integer"
          },
          "content": {
            "readOnly": true,
            "type": "string"
          },
          "file": {
            "format": "uri",
            "type": "string",
            "writeOnly": true
          },
          "id": {
            "format": "uuid",
            "readOnly": true,
            "type": "string"
          },
          "model": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ModelEnum"
              }
            ],
            "description": "ベクトル化に利用するモデル。\n\n* `multilingual-e5-large` - multilingual-e5-large\n* `preview/Qwen3-Embedding-4B-FP16` - preview/Qwen3-Embedding-4B-FP16"
          },
          "name": {
            "description": "未指定の場合はアップロードされたファイル名が使用されます。",
            "maxLength": 255,
            "type": "string"
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/StatusEnum"
              }
            ],
            "readOnly": true,
            "title": "ステータス"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "content",
          "file",
          "id",
          "status"
        ],
        "type": "object"
      },
      "ModelEnum": {
        "description": "* `multilingual-e5-large` - multilingual-e5-large\n* `preview/Qwen3-Embedding-4B-FP16` - preview/Qwen3-Embedding-4B-FP16",
        "enum": [
          "multilingual-e5-large",
          "preview/Qwen3-Embedding-4B-FP16"
        ],
        "type": "string"
      },
      "PaginatedDocumentChunkList": {
        "properties": {
          "meta": {
            "properties": {
              "count": {
                "type": "integer"
              },
              "next": {
                "format": "uri",
                "nullable": true,
                "type": "string"
              },
              "page": {
                "type": "integer"
              },
              "page_size": {
                "type": "integer"
              },
              "previous": {
                "format": "uri",
                "nullable": true,
                "type": "string"
              },
              "total_pages": {
                "type": "integer"
              }
            },
            "required": [
              "page",
              "page_size",
              "total_pages",
              "count",
              "next",
              "previous"
            ],
            "type": "object"
          },
          "results": {
            "items": {
              "$ref": "#/components/schemas/DocumentChunk"
            },
            "type": "array"
          }
        },
        "required": [
          "meta",
          "results"
        ],
        "type": "object"
      },
      "PaginatedDocumentListList": {
        "properties": {
          "meta": {
            "properties": {
              "count": {
                "type": "integer"
              },
              "next": {
                "format": "uri",
                "nullable": true,
                "type": "string"
              },
              "page": {
                "type": "integer"
              },
              "page_size": {
                "type": "integer"
              },
              "previous": {
                "format": "uri",
                "nullable": true,
                "type": "string"
              },
              "total_pages": {
                "type": "integer"
              }
            },
            "required": [
              "page",
              "page_size",
              "total_pages",
              "count",
              "next",
              "previous"
            ],
            "type": "object"
          },
          "results": {
            "items": {
              "$ref": "#/components/schemas/DocumentList"
            },
            "type": "array"
          }
        },
        "required": [
          "meta",
          "results"
        ],
        "type": "object"
      },
      "PaginatedQueryResultChunkList": {
        "properties": {
          "results": {
            "items": {
              "$ref": "#/components/schemas/QueryResultChunk"
            },
            "type": "array"
          }
        },
        "required": [
          "results"
        ],
        "type": "object"
      },
      "QueryRequest": {
        "properties": {
          "distance_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DistanceTypeEnum"
              }
            ],
            "default": "cosine",
            "description": "類似度計算に使用する距離メトリクスです。\n* `cosine`: コサイン距離。テキストの類似度測定に適しており、値の範囲は0〜2（0が完全に一致）です。\n* `l2`: L2距離（ユークリッド距離）。ベクトル空間での直線距離で、数値データの類似度測定に適しています。値の範囲は0〜2（0が完全に一致）です。\n\n* `cosine` - cosine\n* `l2` - l2"
          },
          "model": {
            "default": "multilingual-e5-large",
            "description": "クエリのベクトル化に利用するモデル。",
            "maxLength": 255,
            "type": "string"
          },
          "query": {
            "maxLength": 1000,
            "type": "string"
          },
          "tags": {
            "description": "すべてのタグを持つドキュメントのみ対象。",
            "items": {
              "maxLength": 255,
              "type": "string"
            },
            "type": "array"
          },
          "threshold": {
            "default": 0.3,
            "description": "ベクトル距離のしきい値。この值よりも距離が大きいドキュメントは検索結果から除外されます。",
            "format": "double",
            "maximum": 2,
            "minimum": 0,
            "type": "number"
          },
          "top_k": {
            "default": 3,
            "description": "返す検索結果の最大件数。",
            "maximum": 100,
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "query"
        ],
        "type": "object"
      },
      "QueryResultChunk": {
        "properties": {
          "chunk_index": {
            "readOnly": true,
            "type": "integer"
          },
          "content": {
            "readOnly": true,
            "type": "string"
          },
          "distance": {
            "format": "double",
            "readOnly": true,
            "type": "number"
          },
          "document": {
            "allOf": [
              {
                "$ref": "#/components/schemas/DocumentList"
              }
            ],
            "readOnly": true
          },
          "metadata": {
            "additionalProperties": {},
            "readOnly": true,
            "type": "object"
          }
        },
        "required": [
          "chunk_index",
          "content",
          "distance",
          "document",
          "metadata"
        ],
        "type": "object"
      },
      "QueryResultDocument": {
        "properties": {
          "chunk_size": {
            "readOnly": true,
            "type": "integer"
          },
          "content": {
            "readOnly": true,
            "type": "string"
          },
          "distance": {
            "format": "double",
            "readOnly": true,
            "type": "number"
          },
          "id": {
            "format": "uuid",
            "readOnly": true,
            "type": "string"
          },
          "model": {
            "readOnly": true,
            "type": "string"
          },
          "name": {
            "readOnly": true,
            "type": "string"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "chunk_size",
          "content",
          "distance",
          "id",
          "model",
          "name"
        ],
        "type": "object"
      },
      "StatusEnum": {
        "description": "* `pending` - Pending\n* `processing` - Processing\n* `available` - Available\n* `deleted` - Deleted\n* `error` - Error",
        "enum": [
          "pending",
          "processing",
          "available",
          "deleted",
          "error"
        ],
        "type": "string"
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "さくらのAI Engine RAG API",
    "title": "Sakura AI Engine RAG API",
    "version": "2026-06-29"
  },
  "openapi": "3.0.3",
  "paths": {
    "/v1/documents/": {
      "get": {
        "operationId": "documents_list",
        "parameters": [
          {
            "in": "query",
            "name": "model",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "name",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A page number within the paginated result set.",
            "in": "query",
            "name": "page",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Number of results to return per page.",
            "in": "query",
            "name": "page_size",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "tag",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedDocumentListList"
                }
              }
            },
            "description": ""
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/v1/documents/chat/": {
      "post": {
        "operationId": "documents_chat",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatQueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatResult"
                }
              }
            },
            "description": ""
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "tags": [
          "chat"
        ]
      }
    },
    "/v1/documents/query/": {
      "post": {
        "operationId": "documents_query",
        "parameters": [
          {
            "in": "query",
            "name": "model",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "name",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "tag",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedQueryResultChunkList"
                }
              }
            },
            "description": ""
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "tags": [
          "query"
        ]
      }
    },
    "/v1/documents/upload/": {
      "post": {
        "operationId": "documents_upload",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/DocumentUpload"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/DocumentUpload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentUpload"
                }
              }
            },
            "description": ""
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "tags": [
          "upload"
        ]
      }
    },
    "/v1/documents/{document_pk}/chunks/": {
      "get": {
        "description": "ドキュメント配下のチャンク一覧/単体取得用 ViewSet。\n\n- list: /documents/{document_id}/chunks/\n- retrieve: /documents/{document_id}/chunks/{index}/  ← index で取得",
        "operationId": "document_chunks_list",
        "parameters": [
          {
            "in": "path",
            "name": "document_pk",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A page number within the paginated result set.",
            "in": "query",
            "name": "page",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Number of results to return per page.",
            "in": "query",
            "name": "page_size",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedDocumentChunkList"
                }
              }
            },
            "description": ""
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "tags": [
          "chunks"
        ]
      }
    },
    "/v1/documents/{document_pk}/chunks/{index}/": {
      "get": {
        "description": "ドキュメント配下のチャンク一覧/単体取得用 ViewSet。\n\n- list: /documents/{document_id}/chunks/\n- retrieve: /documents/{document_id}/chunks/{index}/  ← index で取得",
        "operationId": "document_chunks_retrieve",
        "parameters": [
          {
            "in": "path",
            "name": "document_pk",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "index",
            "required": true,
            "schema": {
              "pattern": "^\\d+$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentChunk"
                }
              }
            },
            "description": ""
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "tags": [
          "chunks"
        ]
      }
    },
    "/v1/documents/{id}/": {
      "delete": {
        "operationId": "documents_destroy",
        "parameters": [
          {
            "description": "A UUID string identifying this document.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No response body"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      },
      "get": {
        "operationId": "documents_retrieve",
        "parameters": [
          {
            "description": "A UUID string identifying this document.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            },
            "description": ""
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      },
      "put": {
        "operationId": "documents_update",
        "parameters": [
          {
            "description": "A UUID string identifying this document.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Document"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            },
            "description": ""
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  },
  "servers": [
    {
      "url": " https://api.ai.sakura.ad.jp"
    }
  ]
}