wehub-resource-sync
98e40dac97
CLI Smoke Test / smoke-test-linux (20) (push) Has been cancelled
CLI Smoke Test / smoke-test-linux (24) (push) Has been cancelled
CLI Smoke Test / smoke-test-windows (20) (push) Has been cancelled
CLI Smoke Test / smoke-test-windows (24) (push) Has been cancelled
Expo App TypeScript typecheck / typecheck (push) Has been cancelled
111 lines
3.4 KiB
Markdown
111 lines
3.4 KiB
Markdown
# API
|
|
|
|
This document covers the HTTP API surface and authentication flows. For WebSocket updates and event payloads, see `protocol.md`. For encryption boundaries and encoding details, see `encryption.md`.
|
|
|
|
## Method conventions
|
|
- **GET** is used for reads.
|
|
- **POST** is used for mutations or actions, even when the operation doesn't map cleanly to a single entity.
|
|
- **DELETE** is used when intent is unambiguous (e.g., removing a token or deleting a session/artifact).
|
|
|
|
We intentionally avoid the full REST verb palette because many operations span multiple entities or have non-CRUD semantics.
|
|
|
|
## Authentication
|
|
Most endpoints require `Authorization: Bearer <token>`.
|
|
|
|
Auth flows:
|
|
- `POST /v1/auth`
|
|
- Body: `{ publicKey, challenge, signature }` (base64 strings)
|
|
- Verifies signature using the provided public key.
|
|
- Upserts account by public key and returns `{ success, token }`.
|
|
|
|
- `POST /v1/auth/request`
|
|
- Body: `{ publicKey, supportsV2? }`
|
|
- Creates or returns a terminal auth request.
|
|
- Response: `{ state: "requested" }` or `{ state: "authorized", token, response }`.
|
|
|
|
- `GET /v1/auth/request/status?publicKey=...`
|
|
- Response: `{ status: "not_found" | "pending" | "authorized", supportsV2 }`.
|
|
|
|
- `POST /v1/auth/response`
|
|
- Body: `{ response, publicKey }` (requires Bearer auth)
|
|
- Approves a terminal auth request.
|
|
|
|
- `POST /v1/auth/account/request`
|
|
- Body: `{ publicKey }`
|
|
- Similar to terminal auth, but for account linking.
|
|
|
|
- `POST /v1/auth/account/response`
|
|
- Body: `{ response, publicKey }` (requires Bearer auth)
|
|
|
|
## Endpoint catalog
|
|
### Sessions
|
|
- `GET /v1/sessions`
|
|
- `GET /v2/sessions/active?limit=...`
|
|
- `GET /v2/sessions?cursor=cursor_v1_<id>&limit=...&changedSince=...`
|
|
- `POST /v1/sessions` (create or load by `tag`)
|
|
- `GET /v1/sessions/:sessionId/messages`
|
|
- `DELETE /v1/sessions/:sessionId`
|
|
|
|
### Machines
|
|
- `POST /v1/machines` (create or load by id)
|
|
- `GET /v1/machines`
|
|
- `GET /v1/machines/:id`
|
|
|
|
### Artifacts
|
|
- `GET /v1/artifacts`
|
|
- `GET /v1/artifacts/:id`
|
|
- `POST /v1/artifacts`
|
|
- `POST /v1/artifacts/:id` (versioned update)
|
|
- `DELETE /v1/artifacts/:id`
|
|
|
|
### Access keys
|
|
- `GET /v1/access-keys/:sessionId/:machineId`
|
|
- `POST /v1/access-keys/:sessionId/:machineId`
|
|
- `PUT /v1/access-keys/:sessionId/:machineId`
|
|
|
|
### Key-value store
|
|
- `GET /v1/kv/:key`
|
|
- `GET /v1/kv?prefix=...&limit=...`
|
|
- `POST /v1/kv/bulk`
|
|
- `POST /v1/kv` (batch mutate)
|
|
|
|
### Account and usage
|
|
- `GET /v1/account/profile`
|
|
- `GET /v1/account/settings`
|
|
- `POST /v1/account/settings`
|
|
- `POST /v1/usage/query`
|
|
|
|
### Push tokens
|
|
- `POST /v1/push-tokens`
|
|
- `DELETE /v1/push-tokens/:token`
|
|
- `GET /v1/push-tokens`
|
|
|
|
### Connect (GitHub + vendor tokens)
|
|
- `GET /v1/connect/github/params`
|
|
- `GET /v1/connect/github/callback`
|
|
- `POST /v1/connect/github/webhook`
|
|
- `DELETE /v1/connect/github`
|
|
- `POST /v1/connect/:vendor/register` (`vendor` in `openai | anthropic | gemini`)
|
|
- `GET /v1/connect/:vendor/token`
|
|
- `DELETE /v1/connect/:vendor`
|
|
- `GET /v1/connect/tokens`
|
|
|
|
### Users, friends, feed
|
|
- `GET /v1/user/:id`
|
|
- `GET /v1/user/search?query=...`
|
|
- `POST /v1/friends/add`
|
|
- `POST /v1/friends/remove`
|
|
- `GET /v1/friends`
|
|
- `GET /v1/feed`
|
|
|
|
### Version and voice
|
|
- `POST /v1/version`
|
|
- `POST /v1/voice/token`
|
|
|
|
### Dev-only
|
|
- `POST /logs-combined-from-cli-and-mobile-for-simple-ai-debugging` (only if enabled)
|
|
|
|
## Implementation references
|
|
- API routes: `packages/happy-server/sources/app/api/routes`
|
|
- Auth module: `packages/happy-server/sources/app/auth/auth.ts`
|