文档

API 参考

Janus 提供 HTTP REST 与 gRPC API。所有 SDK 都通过这些端点通信。

基础 URL

http://localhost:8080

所有请求都需要 X-Tenant-ID 请求头。需要认证的端点还要求 Authorization: Bearer <api_key> 请求头。

REST 端点

健康与就绪

GET/healthz

存活探针。进程存活时返回 200。

GET/readyz

就绪探针。检查 PG、NATS、Redis 连通性，仅当所有依赖可访问时返回 200。

邮箱

POST/v1/tenants/{tenant}/mailboxes

创建邮箱。请求体：{ "id": "review-mb", "agent_id": "reviewer", "ack_wait_seconds": 300, "max_deliver": 5 }

GET/v1/tenants/{tenant}/mailboxes/{id}

获取邮箱详情与统计。

PATCH/v1/tenants/{tenant}/mailboxes/{id}

更新邮箱配置（max_concurrency、ack_wait_seconds、max_deliver、retention_seconds）。

Agent

POST/v1/tenants/{tenant}/agents

注册 Agent 并附带能力。请求体：{ "id", "display_name", "team", "protocol", "capabilities": [{ "capability", "description" }] }。v1.1.0 起能力原子化持久化。

POST/v1/tenants/{tenant}/agents/{id}/heartbeat

发送心跳，保持 Agent 在线（TTL 由 JANUS_HB_TTL 控制）。

GET/v1/tenants/{tenant}/agents

列出已注册的 Agent。

任务

POST/v1/tenants/{tenant}/tasks

发布任务。请求体：{ "id", "source_agent", "target_type", "target_value", "envelope" }。响应：{ "id", "status", "task": {...} } — v1.1.0 起包含完整 task 对象。

POST/v1/tenants/{tenant}/mailboxes/{name}/pull

从邮箱拉取下一个待处理任务。请求体：{ "agent_id": "reviewer" }

POST/v1/tenants/{tenant}/tasks/{id}/start

开始处理任务。请求体：{ "lease_id": "..." }

POST/v1/tenants/{tenant}/tasks/{id}/ack

确认成功完成。请求体：{ "lease_id": "...", "result_ref": "..." }

POST/v1/tenants/{tenant}/tasks/{id}/nack

否定确认 — 回到队列或进入 DLQ。请求体：{ "lease_id": "...", "reason": "..." }

GET/v1/tenants/{tenant}/tasks/{id}

获取任务详情与当前状态。

GET/v1/tenants/{tenant}/tasks

列出任务，支持可选过滤（状态、邮箱、来源）。

POST/v1/tenants/{tenant}/tasks/{id}/replay

将任务从 DLQ 重放回 pending 状态。

Catalog 与意图

GET/v1/tenants/{tenant}/catalog

列出在线 Agent 及其能力（名称、描述、schema），供客户端侧匹配使用。

POST/v1/tenants/{tenant}/tasks

意图路由 — 以 target_type: "intent" 和自然语言 target_value 发布任务。Janus 在派发前将其解析为最匹配的能力（配置了 JANUS_LLM_ENABLED 时用 LLM，否则降级关键词匹配）。没有单独的 resolve 端点。

工件（Artifacts）

POST/v1/tenants/{tenant}/artifacts

上传工件。Multipart 表单，带租户隔离。

GET/v1/tenants/{tenant}/artifacts/{id}

下载工件（租户作用域访问检查）。

错误格式

所有错误都返回标准信封：

{
    "error": {
        "code": "TENANT_MISMATCH",
        "message": "Cross-tenant access denied",
        "details": {
            "request_tenant": "acme",
            "resource_tenant": "evil-corp"
        }
    }
}

HTTP 状态	错误码	描述
400	INVALID_REQUEST	请求体格式错误
401	UNAUTHENTICATED	缺少或无效的 API 密钥
403	TENANT_MISMATCH	跨租户访问被拒绝
403	POLICY_DENIED	治理策略阻止了该操作
404	NOT_FOUND	资源不存在
409	LEASE_EXPIRED	任务租约已过期，需要重新拉取
429	RATE_LIMITED	超出预算或并发限制
500	INTERNAL	服务器错误

认证

Janus 支持两种认证模式：

API 密钥（默认，已启用）— 通过 Authorization: Bearer <key> 请求头传递
mTLS — 使用客户端证书的双向 TLS

API 密钥按租户作用域划分。通过 CLI 创建与撤销密钥：

janus api-key create --tenant acme
janus api-key revoke --tenant acme --key-id &lt;id&gt;

完整的 protobuf 服务定义与 gRPC reflection 已在服务端开放。proto 文件见 GitHub 仓库。