{"openapi":"3.1.0","info":{"title":"AgentLink Agent API","version":"0.2.1","description":"AI agent 协作平台 — 跨域数据同步 + 个人记忆托管 + OpenAI 兼容 LLM 代理 + SearXNG 搜索。","contact":{"name":"AgentLink","url":"https://www.mixlab.top/.well-known/security.txt"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://www.mixlab.top","description":"本部署实例"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"mix_<64hex> | OIDC access_token","description":"API Key(`mix_<64hex>`,在 /api/user/api-keys 创建)或 OIDC access token(由 /oauth/token 颁发)。"}},"schemas":{"Memory":{"type":"object","required":["id","source","category","content","tags","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"服务端生成的 UUID"},"source":{"type":"string","description":"来源标识(如 \"notion\" / \"manual\" / 任意 agent 名)"},"category":{"type":"string","description":"分类(如 \"笔记\" / \"todo\" / \"reference\")"},"content":{"type":"string","description":"主要内容(纯文本)"},"tags":{"type":"array","items":{"type":"string"},"description":"tag 列表,用于 tagExpr 查询"},"images":{"type":"array","items":{"type":"string","format":"uri"},"description":"可选图片 URL 列表"},"createdAt":{"type":"integer","format":"int64","description":"毫秒时间戳"},"updatedAt":{"type":"integer","format":"int64","description":"毫秒时间戳"},"metadata":{"description":"自由 JSON,业务自定义","type":"object","additionalProperties":true},"rawData":{"description":"原始输入快照(用于回放)","type":"object","additionalProperties":true}}},"MemoryCreate":{"type":"object","required":["source","category","content"],"properties":{"source":{"type":"string"},"category":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"default":[]},"images":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":true},"rawData":{"type":"object","additionalProperties":true},"findOrCreate":{"type":"boolean","default":false,"description":"true 时按 source upsert,避免重复"}}},"MemoryPatch":{"type":"object","properties":{"source":{"type":"string"},"category":{"type":"string"},"content":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":true},"rawData":{"type":"object","additionalProperties":true}}},"MemoryTableDimension":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string"},"label":{"type":"string"}}},"MemoryTable":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"dimensions":{"type":"array","items":{"$ref":"#/components/schemas/MemoryTableDimension"}},"markdown":{"type":"string"},"createdAt":{"type":"integer","format":"int64"},"updatedAt":{"type":"integer","format":"int64"}}},"MemoryTablePut":{"type":"object","required":["markdown"],"properties":{"dimensions":{"type":"array","items":{"$ref":"#/components/schemas/MemoryTableDimension"}},"markdown":{"type":"string"},"title":{"type":"string"}}},"ProcessRequest":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}}},"description":"OpenAI Chat Completions 风格 messages"},"response_format":{"type":"object","properties":{"type":{"type":"string","enum":["json_object","text"]}},"description":"不传或省略时,默认按 Memory 五字段 schema 输出 JSON;显式传 type=json_object|text 时不用 Memory 格式。"},"llm":{"type":"object","description":"调用方自己的 LLM 配置(OpenAI 兼容)","properties":{"apiUrl":{"type":"string","format":"uri"},"apiKey":{"type":"string"},"model":{"type":"string"}}},"temperature":{"type":"number","minimum":0,"maximum":2,"default":0.7},"stream":{"type":"boolean","default":false,"description":"true 时 SSE 推送"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"人类可读错误"},"detail":{"type":"string","description":"可选,结构化错误细节"}}},"PublicProfile":{"type":"object","properties":{"user":{"type":"object","additionalProperties":true,"description":"公开 profile 字段(slug/displayName/bio/socialLinks 等)"},"github":{"type":"object","nullable":true,"additionalProperties":true,"description":"同步的 GitHub 数据(若开启)"},"realSlug":{"type":"string","description":"当前实际 slug(可能与 URL 中的历史 slug 不同)"}}}},"responses":{"Unauthorized":{"description":"缺少或无效的 API Key / OIDC token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"资源不存在","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServiceUnavailable":{"description":"PostgreSQL 未配置(部分端点需要)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"tags":[{"name":"memories","description":"记忆 CRUD(原始数据源)"},{"name":"memory-table","description":"LLM 整理后的结构化文档(含版本)"},{"name":"process","description":"OpenAI Chat Completions 兼容 LLM 代理"},{"name":"search","description":"SearXNG 搜索代理"},{"name":"public","description":"公开用户数据(无需鉴权)"}],"paths":{"/api/agent/v1/memories":{"get":{"tags":["memories"],"summary":"列出 memories","description":"支持 q(全文搜索)/category/source/tag(单 tag)/tagExpr(AND/OR/括号)/limit/offset。tagExpr 中空格编码为 %20 或 +。","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"tagExpr","in":"query","schema":{"type":"string"},"example":"work AND important"},{"name":"limit","in":"query","schema":{"type":"integer","default":100,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Memory"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}},"post":{"tags":["memories"],"summary":"创建 memory","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryCreate"}}}},"responses":{"200":{"description":"创建成功(findOrCreate=true 时可能返回已存在项)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Memory"}}}},"400":{"description":"source/category/content 缺失","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/agent/v1/memories/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["memories"],"summary":"读取单个 memory","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Memory"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["memories"],"summary":"部分更新 memory","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryPatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Memory"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["memories"],"summary":"删除 memory","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agent/v1/memories/clear":{"post":{"tags":["memories"],"summary":"批量清空当前用户所有 memories","description":"memory-table 不受影响(由独立端点管理)。","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/agent/v1/memory-table":{"get":{"tags":["memory-table"],"summary":"获取当前 memory table(LLM 整理后的结构化文档)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryTable"}}}},"404":{"description":"未找到记忆表格","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["memory-table"],"summary":"保存新版本 memory table","description":"保存后会自动产生一条 version 记录(可通过 /versions 列出)。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryTablePut"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryTable"}}}},"400":{"description":"markdown 不能为空","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/memory-table/versions":{"get":{"tags":["memory-table"],"summary":"列出 memory table 历史版本","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MemoryTable"}}}}}}}},"/api/agent/v1/memory-table/versions/{id}/restore":{"post":{"tags":["memory-table"],"summary":"恢复到指定版本","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK,返回当前 memory table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryTable"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/agent/v1/process":{"post":{"tags":["process"],"summary":"OpenAI Chat Completions 兼容 LLM 代理","description":"默认按内置 systemPrompt + Memory 五字段 schema 返回 JSON;显式传 response_format.type=json_object|text 时不走 Memory schema。llm 模型解析顺序:body.llm > 用户「应用设置」中的「智能整理」配置(自定义模型 / 平台默认模型)。stream=true 返回 SSE。","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessRequest"}}}},"responses":{"200":{"description":"OK(OpenAI Chat Completions 兼容响应)","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","example":"chat.completion"},"choices":{"type":"array","items":{"type":"object","additionalProperties":true}},"usage":{"type":"object","additionalProperties":true}}}},"text/event-stream":{"schema":{"type":"string","description":"stream=true 时返回 OpenAI 风格 SSE"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/agent/v1/search":{"get":{"tags":["search"],"summary":"SearXNG 代理搜索","description":"透传 SearXNG 实例,支持 q(必填)、format(默认 json)、language、pageno、time_range、categories 等。响应内容由 SearXNG 决定。","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","default":"json"}},{"name":"language","in":"query","schema":{"type":"string","default":"en"}},{"name":"pageno","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"time_range","in":"query","schema":{"type":"string","enum":["day","week","month","year"]}},{"name":"categories","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"SearXNG 原始响应(透传)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"缺少 q 参数","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"未配置 SEARXNG 环境变量","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/u/{slug}":{"get":{"tags":["public"],"summary":"公开 profile","description":"visibility=public → 200;visibility=unlisted/private → 404。","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProfile"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/u/{slug}/memory-table":{"get":{"tags":["public"],"summary":"公开 memory table","description":"仅当 user.memoryPublic=true 时返回 200;否则 404。","security":[],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryTable"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}