{"api":{"base_url":"/api/v1","name":"Open-AaaS","version":"0.1.0"},"auth":{"header":"Authorization: Bearer {api_key}","type":"bearer"},"design_principles":{"progressive_disclosure":"信息渐进式披露：API 设计遵循'先摘要筛选，再按需详情'的原则。list_services 返回轻量列表（name + description + status），不占用上下文；get_service_usage 按需获取单个服务的详细用法说明。调用方应先浏览列表筛选候选，再对目标服务获取 usage，避免一次性加载大量长文本。"},"endpoints":[{"body":{"files":"binary (可选，可多个) - 输入文件","output_prompt":"string (必需) - 输出格式要求","service_id":"string (必需) - 服务ID","task_prompt":"string (必需) - 任务描述"},"content_type":"multipart/form-data","method":"POST","name":"create_task","path":"/client/tasks","response":{"created_at":"ISO8601","id":"string","input":{"input_files":["string"],"output_prompt":"string","task_prompt":"string"},"status":"pending"}},{"method":"GET","name":"list_tasks","path":"/client/tasks?status=&service_id=&limit=20&offset=0"},{"method":"GET","name":"get_task","path":"/client/tasks/{id}"},{"limitation":"只能取消pending或running状态","method":"POST","name":"cancel_task","path":"/client/tasks/{id}/cancel"},{"body":{"name":"string (必需) - Client 名称，1-64字符，trim后不能为空"},"method":"POST","name":"register","note":"无需认证，首次调用生成 API Key","path":"/client/auth/register","response":{"api_key":"string - 保存好，后续请求需要使用","id":"string - Client ID"}},{"method":"GET","name":"list_services","note":"返回轻量列表（不含 usage 长文本），用于快速浏览和筛选服务。如需了解服务详细能力，请使用 get_service_usage 按需获取。public 服务自动可用；restricted 服务需要 has_permission=true 才能使用。","path":"/client/services","response":{"services":[{"access_type":"public|restricted","agent_status":"online|offline|busy","description":"string|null","has_permission":"true|false","id":"string","name":"string"}]}},{"method":"GET","name":"get_service_usage","note":"渐进式披露的关键步骤：在 list_services 筛选出候选服务后，调用此接口获取目标服务的详细 usage（能力范围、调用规范、返回格式、限制条件）。usage 内容通常较长，只应在确定使用该服务时获取，避免占用上下文。","path":"/client/services/{id}/usage","response":{"id":"string","name":"string","usage":"string - 服务使用说明/用法"}},{"auth":"需要管理员权限","body":{"user_id":"string (必需) - 要授权的 Client ID"},"method":"POST","name":"grant_permission","path":"/client/services/{id}/grant","response":{"success":"true|false"}},{"method":"GET","name":"download_file","path":"/client/files/{id}/download"},{"method":"GET","name":"list_files","path":"/client/files/list/{task_id}"},{"body":{"name":"string (必需) - 新用户名"},"method":"PUT","name":"update_profile","path":"/client/profile","response":{"api_key":"string","created_at":"ISO8601","id":"string","name":"string","role":"string"}},{"auth":"需要管理员权限","body":{"description":"string (必需) - 服务描述","is_public":"boolean (可选) - 是否公开服务，默认true","name":"string (必需) - 服务名称","usage":"string (必需) - 服务使用说明/用法"},"example":{"request":{"description":"示例智能体","is_public":true,"name":"example-agent","usage":"通用AI助手，可以：\n1. 代码编写与调试\n2. 文档处理\n3. 数据分析"}},"method":"POST","name":"create_service","path":"/api/v1/admin/services","response":{"access_type":"public|restricted","agent_status":"online|offline|busy","description":"string","id":"string","name":"string","usage":"string - 服务使用说明/用法"}}],"errors":{"400":"请求参数错误","401":"认证失败","404":"资源不存在","409":"状态冲突"},"types":{"ServiceListItem":{"access_type":"public|restricted","agent_status":"online|offline|busy","description":"string","has_permission":"true|false","id":"string","name":"string"},"ServiceUsage":{"id":"string","name":"string","usage":"string - 服务使用说明/用法"},"TaskInput":{"input_files":["string"],"output_prompt":"string","task_prompt":"string"}},"workflows":{"client_register":{"env_example":"OPEN_AAAS_API_KEY={api_key}","note":"这里的 .env 是调用 Open-AaaS API 的 client 项目配置，和 server、agent-core 的部署配置无关。","steps":["1. POST /api/v1/client/auth/register - 注册获取 API Key","2. 保存返回的 api_key，用于后续请求认证","3. 建议在调用方项目目录写入 .env，例如 OPEN_AAAS_API_KEY={api_key}","4. GET /client/services - 获取轻量服务列表浏览可用服务","5. GET /client/services/{id}/usage - 按需获取目标服务的详细 usage","6. 如需使用受限服务，联系管理员授权"]},"submit_task":{"note":"任务执行时间从几分钟到几小时不等，提交后立即返回。**请勿轮询**。推荐使用 Dashboard 实时监控，或任务完成后再查询结果。","steps":["1. GET /client/services - 获取轻量服务列表（name/description/status），浏览筛选候选","2. GET /client/services/{id}/usage - 对筛选出的候选服务，按需获取详细 usage（能力范围、调用规范）","3. 根据 usage 说明，构造正确的 task_prompt 和 output_prompt","4. POST /client/tasks - 创建任务（multipart/form-data，可带文件）","5. 保存返回的 task_id，任务在后台异步执行","6. 使用 Dashboard 查看进度，或稍后主动查询任务状态","7. GET /client/files/list/{task_id} - 获取结果文件列表","8. GET /client/files/{id}/download - 下载结果"]}}}