@hexis-ai/engram-server 0.3.0 → 0.5.0

package/openapi.json

@@ -3,12 +3,38 @@
   "info": {
     "title": "engram-server",
     "version": "1.0",
-    "description": "Cross-session retrieval for AI agents. Request bodies are derived from the server's Zod schemas (src/schemas.ts); response schemas are described by status only for now and are a planned follow-up."
+    "description": "AI エージェント向けのクロスセッション検索。リクエストボディはサーバーの Zod スキーマ（src/schemas.ts）から導出される。レスポンススキーマは現状ステータスコードのみの記述で、本格的な記述は今後対応予定。"
   },
+  "tags": [
+    {
+      "name": "Me",
+      "description": "識別プローブ"
+    },
+    {
+      "name": "Sessions",
+      "description": "セッションの作成・取得・イベント追加"
+    },
+    {
+      "name": "Search",
+      "description": "ワークスペースコーパスへのスコアリング検索"
+    },
+    {
+      "name": "Persons",
+      "description": "person の作成・更新・検索"
+    },
+    {
+      "name": "Workspaces (admin)",
+      "description": "ワークスペースの管理（管理者トークン必須）"
+    },
+    {
+      "name": "API Keys (admin)",
+      "description": "ワークスペース API キーの発行・無効化（管理者トークン必須）"
+    }
+  ],
   "servers": [
     {
       "url": "/",
-      "description": "relative to the deployed engram-server"
+      "description": "デプロイされた engram-server からの相対パス"
     }
   ],
   "security": [
@@ -21,13 +47,13 @@
       "workspaceKey": {
         "type": "http",
         "scheme": "bearer",
-        "description": "Workspace API key (`eng_…`). Also accepted as the `X-Api-Key` header."
+        "description": "ワークスペース API キー（`eng_…`）。`X-Api-Key` ヘッダーでも受け付ける。"
       },
       "adminToken": {
         "type": "apiKey",
         "in": "header",
         "name": "X-Admin-Token",
-        "description": "Platform admin token for `/admin/v1/*`. Also accepted as `Authorization: Bearer`."
+        "description": "`/admin/v1/*` 用のプラットフォーム管理者トークン。`Authorization: Bearer` でも受け付ける。"
       }
     },
     "schemas": {
@@ -329,20 +355,23 @@
   "paths": {
     "/v1/me": {
       "get": {
-        "summary": "Identity probe — the workspace the caller's key resolves to.",
+        "summary": "識別プローブ — 呼び出し元のキーが解決するワークスペースを返す。",
         "responses": {
           "200": {
-            "description": "workspace id"
+            "description": "ワークスペース id"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           }
-        }
+        },
+        "tags": [
+          "Me"
+        ]
       }
     },
     "/v1/sessions": {
       "post": {
-        "summary": "Create a session.",
+        "summary": "セッションを作成する。",
         "requestBody": {
           "required": true,
           "content": {
@@ -355,18 +384,21 @@
         },
         "responses": {
           "200": {
-            "description": "created session id"
+            "description": "作成されたセッション id"
           },
           "400": {
-            "description": "invalid body"
+            "description": "リクエストボディが不正"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           }
-        }
+        },
+        "tags": [
+          "Sessions"
+        ]
       },
       "get": {
-        "summary": "List recent sessions plus their persons map.",
+        "summary": "最近のセッション一覧と、それに紐づく persons マップを取得する。",
         "parameters": [
           {
             "name": "limit",
@@ -376,7 +408,7 @@
               "type": "integer",
               "minimum": 1
             },
-            "description": "Page size; clamped server-side."
+            "description": "ページサイズ。サーバー側で上限が適用される。"
           },
           {
             "name": "channel",
@@ -385,22 +417,25 @@
             "schema": {
               "type": "string"
             },
-            "description": "Filter by session channel."
+            "description": "セッションのチャンネルで絞り込む。"
           }
         ],
         "responses": {
           "200": {
-            "description": "session list envelope"
+            "description": "セッション一覧のエンベロープ"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           }
-        }
+        },
+        "tags": [
+          "Sessions"
+        ]
       }
     },
     "/v1/sessions/{id}": {
       "get": {
-        "summary": "Fetch one session plus its persons map.",
+        "summary": "単一セッションと、それに紐づく persons マップを取得する。",
         "parameters": [
           {
             "name": "id",
@@ -409,25 +444,28 @@
             "schema": {
               "type": "string"
             },
-            "description": "Session id."
+            "description": "セッション id。"
           }
         ],
         "responses": {
           "200": {
-            "description": "session envelope"
+            "description": "セッションのエンベロープ"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "session not found"
+            "description": "セッションが見つからない"
           }
-        }
+        },
+        "tags": [
+          "Sessions"
+        ]
       }
     },
     "/v1/sessions/{id}/events": {
       "post": {
-        "summary": "Append events to a session.",
+        "summary": "セッションにイベントを追加する。",
         "parameters": [
           {
             "name": "id",
@@ -436,7 +474,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Session id."
+            "description": "セッション id。"
           }
         ],
         "requestBody": {
@@ -451,23 +489,54 @@
         },
         "responses": {
           "204": {
-            "description": "appended"
+            "description": "追加完了"
           },
           "400": {
-            "description": "invalid body"
+            "description": "リクエストボディが不正"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "session not found"
+            "description": "セッションが見つからない"
           }
-        }
+        },
+        "tags": [
+          "Sessions"
+        ]
+      },
+      "get": {
+        "summary": "セッションの生イベントログを seq 順で取得する（fold せず、各イベントの時刻つき）。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "セッション id。"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "イベントログ"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "セッションが見つからない"
+          }
+        },
+        "tags": [
+          "Sessions"
+        ]
       }
     },
     "/v1/search": {
       "post": {
-        "summary": "Score the workspace corpus against a query session.",
+        "summary": "クエリセッションに対してワークスペースのコーパスをスコアリングする。",
         "requestBody": {
           "required": true,
           "content": {
@@ -480,23 +549,26 @@
         },
         "responses": {
           "200": {
-            "description": "scored results plus persons map"
+            "description": "スコアリング結果と persons マップ"
           },
           "400": {
-            "description": "invalid body"
+            "description": "リクエストボディが不正"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "query session not found"
+            "description": "クエリセッションが見つからない"
           }
-        }
+        },
+        "tags": [
+          "Search"
+        ]
       }
     },
     "/v1/persons": {
       "post": {
-        "summary": "Create a person (server allocates the id).",
+        "summary": "person を作成する（id はサーバーが採番する）。",
         "requestBody": {
           "required": true,
           "content": {
@@ -509,18 +581,21 @@
         },
         "responses": {
           "201": {
-            "description": "created person"
+            "description": "作成された person"
           },
           "400": {
-            "description": "invalid body"
+            "description": "リクエストボディが不正"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           }
-        }
+        },
+        "tags": [
+          "Persons"
+        ]
       },
       "get": {
-        "summary": "List or free-text search persons.",
+        "summary": "person の一覧取得、またはフリーテキスト検索を行う。",
         "parameters": [
           {
             "name": "limit",
@@ -530,7 +605,7 @@
               "type": "integer",
               "minimum": 1
             },
-            "description": "Page size; clamped server-side."
+            "description": "ページサイズ。サーバー側で上限が適用される。"
           },
           {
             "name": "q",
@@ -539,22 +614,25 @@
             "schema": {
               "type": "string"
             },
-            "description": "Free-text query over id + display_name."
+            "description": "id と display_name に対するフリーテキストクエリ。"
           }
         ],
         "responses": {
           "200": {
-            "description": "person list"
+            "description": "person 一覧"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           }
-        }
+        },
+        "tags": [
+          "Persons"
+        ]
       }
     },
     "/v1/persons/{id}": {
       "put": {
-        "summary": "Upsert a person at a caller-supplied id.",
+        "summary": "呼び出し元が指定した id で person を upsert する。",
         "parameters": [
           {
             "name": "id",
@@ -563,7 +641,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Person id."
+            "description": "person id。"
           }
         ],
         "requestBody": {
@@ -578,18 +656,21 @@
         },
         "responses": {
           "200": {
-            "description": "upserted person"
+            "description": "upsert された person"
           },
           "400": {
-            "description": "invalid body"
+            "description": "リクエストボディが不正"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           }
-        }
+        },
+        "tags": [
+          "Persons"
+        ]
       },
       "patch": {
-        "summary": "Patch a person's profile fields.",
+        "summary": "person のプロフィール項目を部分更新する。",
         "parameters": [
           {
             "name": "id",
@@ -598,7 +679,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Person id."
+            "description": "person id。"
           }
         ],
         "requestBody": {
@@ -613,21 +694,24 @@
         },
         "responses": {
           "200": {
-            "description": "updated person"
+            "description": "更新された person"
           },
           "400": {
-            "description": "invalid body"
+            "description": "リクエストボディが不正"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "person not found"
+            "description": "person が見つからない"
           }
-        }
+        },
+        "tags": [
+          "Persons"
+        ]
       },
       "get": {
-        "summary": "Fetch one person.",
+        "summary": "単一の person を取得する。",
         "parameters": [
           {
             "name": "id",
@@ -636,7 +720,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Person id."
+            "description": "person id。"
           }
         ],
         "responses": {
@@ -644,17 +728,20 @@
             "description": "person"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "person not found"
+            "description": "person が見つからない"
           }
-        }
+        },
+        "tags": [
+          "Persons"
+        ]
       }
     },
     "/v1/persons/{id}/sessions": {
       "get": {
-        "summary": "Sessions this person participates in (or can view).",
+        "summary": "この person が参加している（または閲覧可能な）セッション一覧。",
         "parameters": [
           {
             "name": "id",
@@ -663,7 +750,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Person id."
+            "description": "person id。"
           },
           {
             "name": "limit",
@@ -673,7 +760,7 @@
               "type": "integer",
               "minimum": 1
             },
-            "description": "Page size; clamped server-side."
+            "description": "ページサイズ。サーバー側で上限が適用される。"
           },
           {
             "name": "channel",
@@ -682,7 +769,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Filter by session channel."
+            "description": "セッションのチャンネルで絞り込む。"
           },
           {
             "name": "scope",
@@ -695,22 +782,104 @@
                 "viewable"
               ]
             },
-            "description": "`participant` (default) or `viewable`."
+            "description": "`participant`（デフォルト）または `viewable`。"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "セッション一覧のエンベロープ"
+          },
+          "401": {
+            "description": "認証エラー"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
+      }
+    },
+    "/v1/persons/{id}/aliases": {
+      "get": {
+        "summary": "この person の alias 一覧を取得する（直近使用が先頭）。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
           }
         ],
         "responses": {
           "200": {
-            "description": "session list envelope"
+            "description": "alias 一覧"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           }
-        }
+        },
+        "tags": [
+          "Persons"
+        ]
+      }
+    },
+    "/v1/persons/{id}/aliases/{name}": {
+      "put": {
+        "summary": "person に alias を upsert する。name は case-insensitive で比較される。",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "person id。"
+          },
+          {
+            "name": "name",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "alias の名前（URL-encoded）。"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AliasUpsert"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "upsert された alias"
+          },
+          "400": {
+            "description": "リクエストボディが不正"
+          },
+          "401": {
+            "description": "認証エラー"
+          },
+          "404": {
+            "description": "person が見つからない"
+          }
+        },
+        "tags": [
+          "Persons"
+        ]
       }
     },
     "/admin/v1/workspaces": {
       "post": {
-        "summary": "Create a workspace (and, by default, an initial key).",
+        "summary": "ワークスペースを作成する（デフォルトで初期キーも発行する）。",
         "security": [
           {
             "adminToken": []
@@ -728,18 +897,21 @@
         },
         "responses": {
           "200": {
-            "description": "workspace, plus key unless issueKey=false"
+            "description": "ワークスペース（issueKey=false でない限りキーも含む）"
           },
           "400": {
-            "description": "invalid body or workspace id"
+            "description": "リクエストボディまたはワークスペース id が不正"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           }
-        }
+        },
+        "tags": [
+          "Workspaces (admin)"
+        ]
       },
       "get": {
-        "summary": "List all workspaces.",
+        "summary": "全ワークスペースを一覧取得する。",
         "security": [
           {
             "adminToken": []
@@ -747,17 +919,20 @@
         ],
         "responses": {
           "200": {
-            "description": "workspace list"
+            "description": "ワークスペース一覧"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           }
-        }
+        },
+        "tags": [
+          "Workspaces (admin)"
+        ]
       }
     },
     "/admin/v1/workspaces/{id}": {
       "get": {
-        "summary": "Fetch one workspace.",
+        "summary": "単一のワークスペースを取得する。",
         "security": [
           {
             "adminToken": []
@@ -771,23 +946,26 @@
             "schema": {
               "type": "string"
             },
-            "description": "Workspace id."
+            "description": "ワークスペース id。"
           }
         ],
         "responses": {
           "200": {
-            "description": "workspace"
+            "description": "ワークスペース"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "workspace not found"
+            "description": "ワークスペースが見つからない"
           }
-        }
+        },
+        "tags": [
+          "Workspaces (admin)"
+        ]
       },
       "delete": {
-        "summary": "Delete a workspace (cascades to keys, sessions, events).",
+        "summary": "ワークスペースを削除する（キー・セッション・イベントにカスケードする）。",
         "security": [
           {
             "adminToken": []
@@ -801,25 +979,28 @@
             "schema": {
               "type": "string"
             },
-            "description": "Workspace id."
+            "description": "ワークスペース id。"
           }
         ],
         "responses": {
           "204": {
-            "description": "deleted"
+            "description": "削除完了"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "workspace not found"
+            "description": "ワークスペースが見つからない"
           }
-        }
+        },
+        "tags": [
+          "Workspaces (admin)"
+        ]
       }
     },
     "/admin/v1/workspaces/{id}/keys": {
       "post": {
-        "summary": "Issue a new API key for a workspace.",
+        "summary": "ワークスペースに新しい API キーを発行する。",
         "security": [
           {
             "adminToken": []
@@ -833,7 +1014,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Workspace id."
+            "description": "ワークスペース id。"
           }
         ],
         "requestBody": {
@@ -848,21 +1029,24 @@
         },
         "responses": {
           "200": {
-            "description": "issued key (raw key returned once)"
+            "description": "発行されたキー（生のキーは一度のみ返却）"
           },
           "400": {
-            "description": "invalid body"
+            "description": "リクエストボディが不正"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "workspace not found"
+            "description": "ワークスペースが見つからない"
           }
-        }
+        },
+        "tags": [
+          "API Keys (admin)"
+        ]
       },
       "get": {
-        "summary": "List a workspace's API keys (hashes only).",
+        "summary": "ワークスペースの API キー一覧を取得する（ハッシュのみ）。",
         "security": [
           {
             "adminToken": []
@@ -876,25 +1060,28 @@
             "schema": {
               "type": "string"
             },
-            "description": "Workspace id."
+            "description": "ワークスペース id。"
           }
         ],
         "responses": {
           "200": {
-            "description": "key list"
+            "description": "キー一覧"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "workspace not found"
+            "description": "ワークスペースが見つからない"
           }
-        }
+        },
+        "tags": [
+          "API Keys (admin)"
+        ]
       }
     },
     "/admin/v1/workspaces/{id}/keys/{keyId}": {
       "delete": {
-        "summary": "Revoke an API key.",
+        "summary": "API キーを無効化する。",
         "security": [
           {
             "adminToken": []
@@ -908,7 +1095,7 @@
             "schema": {
               "type": "string"
             },
-            "description": "Workspace id."
+            "description": "ワークスペース id。"
           },
           {
             "name": "keyId",
@@ -917,20 +1104,23 @@
             "schema": {
               "type": "string"
             },
-            "description": "Key id."
+            "description": "キー id。"
           }
         ],
         "responses": {
           "204": {
-            "description": "revoked (idempotent)"
+            "description": "無効化完了（冪等）"
           },
           "401": {
-            "description": "unauthorized"
+            "description": "認証エラー"
           },
           "404": {
-            "description": "key not found"
+            "description": "キーが見つからない"
           }
-        }
+        },
+        "tags": [
+          "API Keys (admin)"
+        ]
       }
     }
   }