moteva/server/API.md

# img-infinite-canvas API

Base path: `/api`

## Health

`GET /api/health`

```json
{
  "status": "ok",
  "service": "img_infinite_canvas-api",
  "time": "2026-07-04T03:20:00Z"
}
```

## Dashboard

`GET /api/dashboard`

Returns credits, quick actions, recent projects, and inspiration items for the Moteva-style home screen.

## Auth

Global mode is enabled in `etc/config.yaml`. Email verification codes are stored through the cache abstraction for 10 minutes; with `Cache.Driver: redis`, the code only lives in Redis until TTL or successful consumption.

SMTP is configured under `Auth.Email`:

```yaml
Auth:
  Turnstile:
    Enabled: true
    SiteKey: 1x00000000000000000000AA
    SecretKey: 1x0000000000000000000000000000000AA
    SecretKeyEnv: TURNSTILE_SECRET_KEY
    SiteVerifyURL: https://challenges.cloudflare.com/turnstile/v0/siteverify
    TimeoutSeconds: 5
  Email:
    Driver: smtp # none|smtp
    Host: smtp.example.com
    Port: 587
    Username: user@example.com
    Password: app-password
    FromName: hello
    FromEmail: hello@example.com
    BrandName: Moteva
    UseTLS: false
    StartTLS: true
    TimeoutSeconds: 10
```

When `Auth.Turnstile.Enabled` is `false`, `/api/auth/options` returns `turnstile.enabled=false`; the frontend hides the Cloudflare Turnstile widget and sends email-code requests without a Turnstile token. When enabled, the frontend must submit `turnstileToken`, and the API validates it before creating or emailing a verification code.

`POST /api/auth/global/email-code`

```json
{
  "email": "user@example.com",
  "turnstileToken": "client-widget-token"
}
```

Development response includes an email preview so the frontend can render the same verification flow without a mail provider:

```json
{
  "target": "user@example.com",
  "expiresIn": 600,
  "devCode": "263081",
  "email": {
    "fromName": "hello",
    "fromEmail": "hello@auth.moteva.local",
    "toEmail": "user@example.com",
    "subject": "Welcome to Moteva!",
    "code": "263081"
  }
}
```

`POST /api/auth/global/email-login`

```json
{
  "email": "user@example.com",
  "code": "263081"
}
```

Returns an authenticated session with `accessToken`, `refreshToken`, and the user profile. Project creation, generation, upload, save, and deletion require this login token.

`POST /api/auth/global/google-login`

```json
{
  "idToken": "google-id-token"
}
```

`POST /api/auth/china/wechat-login`

First QR callback:

```json
{
  "code": "wechat-oauth-code",
  "state": "signed-state"
}
```

If the WeChat identity is already bound to a phone number, the response is authenticated. If not, the response has `status: "phone_binding_required"` and a short-lived `bindingToken`.

Phone binding step:

```json
{
  "bindingToken": "signed-binding-token",
  "phone": "13800138000",
  "countryCode": "+86",
  "smsCode": "123456"
}
```

After binding succeeds, later QR logins use only `code` and `state`.

## Account

All account endpoints require the bearer token returned by login. Account profile state is owned by the auth module and persisted in PostgreSQL or the configured in-memory store.

`GET /api/account/profile`

Returns the current authenticated user.

`PATCH /api/account/profile`

```json
{
  "name": "Xu Liang",
  "avatarUrl": "https://cdn.example.com/avatar.webp"
}
```

Updates account display name and avatar URL. The frontend uploads avatar files through `/api/assets/upload-url` first, then stores the returned public URL on the profile.

`GET /api/account/devices`

Returns the current local web session. This version does not maintain a multi-device session registry yet, so the current device is read-only and cannot be removed.

`DELETE /api/account/devices`

Removes non-current devices when a future server-side session registry exists. In the current local-only implementation, it returns `{"removed": 0}`.

`POST /api/account/logout`

Records a logout request server-side and returns `{"removed": 0}`. The frontend then clears its local access token and cookies.

## Projects

`GET /api/projects`

Returns all project summaries, sorted by `updatedAt` descending.

`POST /api/projects`

```json
{
  "title": "still day 官网",
  "prompt": "为 still day 品牌服装独立站设计官网视觉方向",
  "imageModel": "gpt-image-2",
  "imageSize": "1024x1024",
  "enableWebSearch": true
}
```

`enableWebSearch` only opens the web-search capability. The agent model still decides per request whether search is actually needed; if it is not needed, no web-search step is recorded.

`GET /api/projects/:id`

Returns the full project, including viewport, nodes, connections, and agent messages.

`PATCH /api/projects/:id/title`

```json
{
  "title": "夏季活动主视觉"
}
```

Renames the infinite canvas project and updates `updatedAt`.

`DELETE /api/projects/:id`

Deletes the project record. PostgreSQL cascades canvas nodes, chat messages, history, and connections; after the database delete succeeds, image assets referenced by the canvas and generated-file history are queued for asynchronous OSS deletion.

## Agent Chat

`POST /api/projects/:id/agent/chat`

```json
{
  "messages": [
    {
      "role": "user",
      "contents": [{ "type": "text", "text": "继续优化首页首屏，但保留品牌色" }]
    }
  ],
  "enableWebSearch": false,
  "imageModel": "gpt-image-2",
  "imageSize": "1024x1024",
  "mode": "design"
}
```

The harness builds short memory from the current turn, recent messages, and visible canvas state, and long memory from durable project decisions, prior artifacts, and previous research records. Image titles and assistant language are generated from the request context instead of fixed model labels.

## Generate

`POST /api/projects/:id/generate`

```json
{
  "prompt": "继续扩展产品详情页模块",
  "mode": "design"
}
```

Returns the updated project, the assistant message, and generated nodes.

The generation path uses the configured design agent runner. The default is the `sky-valley/pi` Go agent adapter, with local desktop/MCP agent behavior disabled.

## Chat History Replay

`GET /api/projects/:id/history`

Returns replayable assistant/user chat history for the project.

```json
{
  "projectId": "project-id",
  "messages": []
}
```

## Save Canvas

`PATCH /api/projects/:id/canvas`

```json
{
  "viewport": { "x": 420, "y": 260, "k": 0.72 },
  "nodes": [],
  "connections": []
}
```

Saves canvas layout changes. The frontend uses this after dragging or zooming.

When a canvas image node disappears from the saved node list, its backing OSS asset is queued for asynchronous deletion after the canvas save succeeds.

## Image Asset Upload

`POST /api/assets/upload-url`

```json
{
  "fileName": "reference.png",
  "contentType": "image/png",
  "size": 123456
}
```

Returns a signed upload URL for the configured storage backend.

Supported drivers:

- `memory`
- `minio`
- `s3` / `aws`
- `r2`
- `aliyun`

## Errors

JSON error response:

```json
{
  "error": "project not found",
  "code": 404
}
```

Common status codes:

- `400`: invalid input
- `404`: project not found
- `500`: internal server error