Sign In

Project-scope endpoint reference

Compact table of every project-scope endpoint. Either (ProjectAccess) means the endpoint accepts owner JWT or a jg_p_* project key. For project-key calls, an optional X-USER-ID header partitions per end-user where the route's data model supports it.

Base URL: https://api.juglans.ai (prod) / http://localhost:3002 (dev).

Project CRUD

Method Path Auth Purpose Section
POST /api/projects JWT Create a project Authentication
GET /api/projects JWT List projects you own Authentication
GET /api/projects/{id} Either (ProjectAccess) Fetch one project + member list Invites & members
PATCH /api/projects/{id} JWT Update name/description/avatar Authentication
DELETE /api/projects/{id} JWT Delete a project (cascades) Authentication

Conversations

Method Path Auth Purpose Section
POST /api/projects/{id}/chat Project key SSE streaming chat Conversations
POST /api/projects/{id}/conversations Project key Create a conversation Conversations
GET /api/projects/{id}/conversations Project key List conversations (auto-partitioned by X-USER-ID) Conversations
GET /api/projects/{id}/conversations/{cid} Project key Fetch one + messages Conversations
PATCH /api/projects/{id}/conversations/{cid} Project key Update title / archive Conversations
DELETE /api/projects/{id}/conversations/{cid} Project key Delete Conversations

Members (agents)

Method Path Auth Purpose Section
GET /api/projects/{id}/members Either (ProjectAccess) List agent members Invites & members
POST /api/projects/{id}/members Either (ProjectAccess) Add an owned agent Invites & members
DELETE /api/projects/{id}/members/{agent_id} Either (ProjectAccess) Remove an agent Invites & members

Humans + invites

Method Path Auth Purpose Section
GET /api/projects/{id}/humans Either (ProjectAccess) List human members Invites & members
POST /api/projects/{id}/invites Either (ProjectAccess) Issue invite (link shown once) Invites & members
GET /api/projects/{id}/invites Either (ProjectAccess) List active invites Invites & members
DELETE /api/projects/{id}/invites/{invite_id} Either (ProjectAccess) Revoke invite Invites & members
POST /api/invites/{code}/redeem JWT (invitee's) Redeem invite as existing user Invites & members

External users

Method Path Auth Purpose Section
GET /api/projects/{id}/external-users Either (ProjectAccess) List end-users External users
DELETE /api/projects/{id}/external-users/{user_id} Either (ProjectAccess) Force-offboard end-user External users

Settings + project keys

Method Path Auth Purpose Section
GET /api/projects/{id}/settings JWT Read webhook URL, secret prefix, rate limit Webhooks & rate limits
PATCH /api/projects/{id}/settings JWT Update webhook URL or rate limit Webhooks & rate limits
POST /api/projects/{id}/settings/webhook/rotate-secret JWT Rotate webhook signing secret (returned once) Webhooks & rate limits
POST /api/projects/{id}/api-keys JWT Mint jg_p_* key (plaintext returned once) Webhooks & rate limits
GET /api/projects/{id}/api-keys JWT List active project keys Webhooks & rate limits
DELETE /api/projects/{id}/api-keys/{key_id} JWT Revoke a project key Webhooks & rate limits

Channels

Method Path Auth Purpose Section
POST /api/projects/{id}/channels JWT Create a Telegram or WeChat channel Channels
GET /api/projects/{id}/channels JWT List channels Channels
GET /api/projects/{id}/channels/{channel_id} JWT Fetch one channel Channels
PATCH /api/projects/{id}/channels/{channel_id} JWT Update channel Channels
DELETE /api/projects/{id}/channels/{channel_id} JWT Delete channel Channels
POST /api/projects/{id}/channels/{channel_id}/wechat/qr JWT Start WeChat QR login Channels
GET /api/projects/{id}/channels/{channel_id}/wechat/status JWT Poll WeChat binding status Channels
DELETE /api/projects/{id}/channels/{channel_id}/wechat JWT Unbind WeChat session Channels
GET /api/projects/{id}/channels/{channel_id}/messages JWT Recent message log Channels

Errors

All errors return a flat envelope: {"error": "<message>"} — branch on the HTTP status, not on the body. The chat endpoint additionally adds two fields on 429 so retries can be paced.

Status Typical cause
400 Malformed JSON, missing required field, or a field that fails validation (e.g. non-existent agent on POST /members).
401 Missing/invalid Authorization header, or jg_p_* key revoked / not found.
403 Caller is authenticated but not permitted (e.g. project key for the wrong project, or non-owner editing settings).
404 Resource doesn't exist, or isn't visible to the caller's partition (deliberately indistinguishable).
410 Invite already redeemed, revoked, or expired.
429 Project's rate_limit_rpm exceeded. Body includes retry_after_seconds and limit_rpm (in addition to error).
502 / 503 / 504 Upstream LLM, channel bridge, or WeChat login service unreachable.