ものしりAI API (1.0.0)

ステップ1: トークン取得（パスワード認証）

POST /v1/auth/token
Content-Type: application/json

{
  "grant_type": "password",
  "username": "admin@example.com",
  "password": "yourpassword",
  "team_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

レスポンスの access_token を以降のリクエストで使用してください。

ステップ2: 認証済みリクエスト

GET /v1/teams/{teamId}/folders
Authorization: Bearer <access_token>
X-Team-Id: <team_id>

ステップ3: トークンリフレッシュ

access_token の有効期限（expires_in 秒）が切れた場合、refresh_token を使って更新します。

POST /v1/auth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "<refresh_token>"
}

ファイルアップロードはS3プリサインドPOSTを使用します。

ステップ1: アップロードURL取得

POST /v1/teams/{teamId}/folders/{folderId}/documents/upload-url
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "filename": "manual.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1048576,
  "sha256_hash": "e3b0c44298fc1c149afb...",
  "skip_if_duplicate": true
}

レスポンスに upload_url（S3エンドポイント）と upload_fields（フォームフィールド）、document_id が含まれます。 duplicate: true の場合はS3アップロード不要です。

ステップ2: S3へ直接アップロード

POST <upload_url>
Content-Type: multipart/form-data

# upload_fields の各フィールドをフォームに含め、最後に file フィールドを追加
key=<s3_key>&Content-Type=application/pdf&...&file=<binary>

ステップ3: アップロード完了通知

POST /v1/teams/{teamId}/folders/{folderId}/documents/{docId}/confirm
Authorization: Bearer <access_token>

confirmが成功するとドキュメントのベクトル化パイプラインが起動します。 ステータスが processing → ready に変わるまで、GETエンドポイントでポーリングしてください。

全エンドポイントのエラーレスポンスは以下の形式です。

{
  "statusCode": 400,
  "message": "Bad Request",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

認証エラー（401）と権限エラー（403）の message フィールドには、OAuth2.0互換の error / error_description フィールドが含まれることがあります。

• POST /v1/auth/token: 60秒あたり10リクエスト（10 req/60s）
• 認証済み一般エンドポイント: 1分あたり60リクエスト（60 req/min）
• 超過時は 429 Too Many Requests が返されます。

アクセストークンの取得・更新

フォルダ（ナレッジ単位）の管理

ドキュメントのアップロード・管理