Skip to content

REST API Reference

Jump to bottom
wody edited this page May 24, 2026 · 24 revisions

REST API Reference

Complete endpoint catalog as of v0.34.0. All routes are defined as constants in shared/.../ApiPath.kt; copy them into your client to stay wire-compatible.

Wire changes since the original v0.10.0 baseline

  • v0.13.0 — claudeConsoleCancel(projectId) + Prompt Template GET
  • v0.16.0 — Conversation history GET (per-project + scratch)
  • v0.18.0 — gitCommit(projectId) + templateId field on register
  • v0.19.0 — Emulator diagnostics (page-only; JSON API on roadmap)
  • v0.20.0 — PROMPT_TEMPLATES constant + PromptTemplateDto / PromptTemplateListResponseDto promoted to shared/
  • v0.21.0 — ClaudeStatusDto gains usagePercent: Int? and resetAt: String? (additive; default null)
  • v0.22.0 / v0.23.0 — Play Console + TestFlight upload (SSR only)
  • v0.24.0 — Emulator AVD lifecycle (SSR POSTs; no REST wire)
  • v0.26.0 — LoginRequestDto.totpCode: String? (additive). 2FA- enabled users get 401 totp_required; bad code returns invalid_totp.
  • v0.28.0 — APK signer inspection (SSR-only)
  • v0.29.0 — GET /projects/{id}/zip source download (SSR streaming)
  • v0.30.0 — /history cross-project search (SSR), build history chart (SSR), keyboard shortcuts (static JS); no REST wire
  • v0.31.0 — GET /api/projects/{id}/claude/prompt-suggestions?prefix=… added (additive — server-only, no Dto in shared/). GET /projects/{id}/history/export + POST .../history/import (SSR). /agents CRUD (SSR only).
  • v0.32.0 — /projects/{id}/deps, /projects/{id}/env-files, /logs (all SSR; no REST wire)
  • v0.33.0 — POST /api/webhooks/build/{projectId} external trigger (admin-auth-free, multi-secret); /projects/{id}/automation SSR
  • v0.34.0 — /backup SSR + GET /backup/download (application/gzip)

Authentication

All /api/* routes (except /api/auth/setup, /api/auth/setup/status, /api/auth/login, and /health) require Bearer authentication:

Authorization: Bearer <token>

Obtain a token with POST /api/auth/login. The same token works with both the header and the vibe_session cookie path.

Base URL

http://<host>:17880

For LAN deployments. HTTPS is the operator's responsibility (reverse proxy recommended for non-LAN exposure).

Auth

POST /api/auth/setup/status

Check whether an admin user exists. Used by clients to decide between login and setup screen.

curl http://localhost:17880/api/auth/setup/status
# → {"adminExists": true}

POST /api/auth/setup

Create the first admin user (only when no admin exists). Returns 409 Conflict if one already exists.

curl -X POST http://localhost:17880/api/auth/setup \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"ChangeMe123","deviceName":"my-laptop"}'
# → {"token":"...","deviceId":"...","serverName":"...","username":"admin"}

POST /api/auth/login

curl -X POST http://localhost:17880/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"ChangeMe123","deviceName":"my-android"}'
# → {"token":"...","deviceId":"...","serverName":"...","username":"admin"}

10 consecutive failures lock the account for 15 minutes (timing-safe).

Two-factor authentication (v0.26.0+)

If the user has TOTP enabled (see Two-Factor Auth) the first call without totpCode returns:

HTTP/1.1 401 Unauthorized
{"code":"totp_required","message":"2단계 인증 코드가 필요합니다."}

Client should prompt the user for the 6-digit code from their Authenticator app and resubmit with totpCode added:

curl -X POST http://localhost:17880/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"ChangeMe123","deviceName":"my-android","totpCode":"123456"}'

Wrong code returns 401 invalid_totp (counts against the brute-force limits). totp_required does not (1단계 통과 = legitimate progress).

Session timeout (v0.26.0+)

The bearer token / vibe_session cookie auto-expires after security.sessionIdleTimeoutMinutes (default 30) of inactivity. SSR redirects to /login?err=session_timeout; JSON API returns plain 401.

POST /api/auth/password

Change password. Requires Bearer auth.

curl -X POST http://localhost:17880/api/auth/password \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"currentPassword":"old","newPassword":"new"}'
# → 204 No Content

Server status

GET /api/server/status

High-level summary.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:17880/api/server/status
{
  "serverName": "Vibe Coder Server",
  "serverVersion": "0.10.0",
  "osName": "Linux 6.x",
  "javaVersion": "17.0.19",
  "workspaceRoot": "/workspace",
  "projectCount": 3,
  "runningTaskCount": 0,
  "claudeAvailable": true,
  "androidSdkAvailable": true,
  "gitAvailable": true,
  "freeDiskSpaceBytes": 102400000000
}

GET /api/server/environment / GET /api/server/environment/check

Detailed per-component diagnostics.

Projects

GET /api/projects

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:17880/api/projects
# → [{"id":"my-app","name":"My App","packageName":"...", ...}]

POST /api/projects/register

Empty project:

curl -X POST http://localhost:17880/api/projects/register \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "projectId": "my-app",
    "appName": "My App",
    "packageName": "com.siamakerlab.myapp"
  }'

Clone from git:

curl -X POST http://localhost:17880/api/projects/register \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "projectId": "my-app",
    "appName": "My App",
    "packageName": "com.siamakerlab.myapp",
    "sourceType": "clone",
    "cloneUrl": "https://github.com/owner/repo.git",
    "cloneBranch": "main"
  }'

Private SSH URL — first register a PAT or generate an SSH key via the Git integrations endpoints below.

Optional templateId field (v0.18.0+)

When neither sourceType=clone nor an uploadedZipId is provided, the server can scaffold the project from a built-in template instead of leaving an empty directory.

curl -X POST http://localhost:17880/api/projects/register \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "projectId": "my-app",
    "appName": "My App",
    "packageName": "com.siamakerlab.myapp",
    "templateId": "compose-mvvm-hilt"
  }'

Template IDs (resolved by ProjectTemplates.byId(...)):

templateId Description
empty Bare CLAUDE.md only (default)
compose-basic Single-activity Compose Material3
compose-mvvm-hilt ViewModel + Hilt skeleton
compose-mvvm-room Hilt + Room database wired
wear-os Wear OS Compose entry point
android-tv Leanback / TV-launcher entry

Each template seeds a starterPrompt that the project's first console turn consumes — so the next user prompt feels like a follow-up to a real conversation. The user can override or ignore it.

Optional keystore field (JSON API only)

RegisterProjectRequestDto.keystore is accepted by the server but is not exposed in the admin SSR project-create form — it is reachable only via this JSON endpoint (curl / mobile client / direct API).

curl -X POST http://localhost:17880/api/projects/register \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "projectId": "my-app",
    "appName": "My App",
    "packageName": "com.siamakerlab.myapp",
    "keystore": {
      "alias": "myapp",
      "password": "at-least-6-chars",
      "dname": "CN=Jangwook Lee, OU=Mobile, O=Sia Makerlab, L=Jecheon, ST=Chungbuk, C=KR",
      "validityDays": 36500
    }
  }'

KeystoreRequestDto fields:

Field Type Required Default Notes
alias String ✅ — Non-blank. Becomes keyAlias in the generated .properties.
password String ✅ — Used for both storePassword and keyPassword. Minimum 6 chars.
dname String? — Sia Makerlab default DName keytool -dname value.
validityDays Int — 36500 (~100 yr) keytool -validity.

Output files (always outside the project folder, in the workspace sidecar):

<workspace>/.vibecoder/keystores/<projectId>/
  <projectId>.keystore               ← keytool -genkeypair output
  <projectId>-keystore.properties    ← Gradle-readable signing config

.properties contents:

storeFile=<workspace>/.vibecoder/keystores/<projectId>/<projectId>.keystore
storePassword=<plain-password>
keyAlias=<alias>
keyPassword=<plain-password>

Security caveat (current implementation). KeystoreGenerator invokes keytool -storepass <plain> -keypass <plain> — the password is therefore briefly visible in ps -ef / /proc/<pid>/cmdline on the host while the command runs (~1 s). Acceptable under vibe-coder's single-operator LAN threat model, but if you share the host with anyone, generate the keystore manually outside the container and only drop the .keystore file in. A future release will migrate to -storepass:env. Tracked in roadmap.

If keystore.password policy is stricter than the 6-char minimum, generate the keystore separately and place the files under <workspace>/.vibecoder/keystores/<projectId>/ yourself.

To skip keystore generation entirely, omit the field or send "keystore": null (current default).

Builds

POST /api/projects/{id}/build/debug

Queue a debug build. Returns immediately with a BuildDto; stream live output via /ws/projects/{id}/builds/{buildId}/logs.

GET /api/projects/{id}/builds

List recent builds.

POST /api/projects/{id}/builds/{buildId}/cancel

Send SIGTERM (then SIGKILL after 5 s) to the build subprocess.

GET /api/projects/{id}/artifacts/{artifactId}/download

Stream the produced APK.

Claude Console (per-project persistent session)

POST /api/projects/{id}/claude/console/prompt

curl -X POST http://localhost:17880/api/projects/my-app/claude/console/prompt \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"text":"Add a settings screen with a dark mode toggle"}'
# → 202 Accepted (response streamed over WebSocket)

POST /api/projects/{id}/claude/console/new

Tear down the current session and start fresh (--resume <id> is dropped).

POST /api/projects/{id}/claude/console/cancel (v0.13.0+)

Send SIGTERM to the running Claude child process and preserve the saved session-id. The next prompt resumes the same conversation via --resume. Use to abort a turn that's heading in the wrong direction.

curl -X POST http://localhost:17880/api/projects/my-app/claude/console/cancel \
  -H "Authorization: Bearer $TOKEN"
# → 202 Accepted (no body)

GET /api/projects/{id}/claude/status

Model, plan, quota remaining (cached 60 s).

{
  "sessionId": "01J...",
  "processAlive": true,
  "model": "claude-opus-4-7-1m",
  "plan": "Max",
  "quotaRemaining": "20% remaining, resets at 2026-05-25T00:00Z",
  "usagePercent": 80,
  "resetAt": "resets at 2026-05-25T00:00Z",
  "updatedAt": "2026-05-24T15:00:00Z"
}

usagePercent and resetAt were added in v0.21.0 and are best-effort (parsed from the CLI's /status plain-text output). Older CLI versions or unfamiliar output formats yield null, in which case the dashboard card gracefully shows "couldn't parse" rather than misleading numbers.

The same value powers the Email Notifications + Webhook Notifications threshold alerts, fired on transition past warnThresholdPercent (default 80) or criticalThresholdPercent (default 95).

Prompt templates (v0.13.0+)

GET /api/prompt-templates

Returns the full user-defined prompt library. The browser console page uses this to populate the ▼ dropdown. Android client may use the same to ship a "templates" picker.

curl http://localhost:17880/api/prompt-templates \
  -H "Authorization: Bearer $TOKEN"
{
  "templates": [
    {
      "id": "t-7a3...",
      "title": "Add a Compose Settings screen",
      "category": "Android",
      "body": "Add a Settings screen using Compose Material3 with a dark-mode Switch...",
      "createdAt": "2026-05-23T12:00:00Z",
      "updatedAt": "2026-05-24T08:11:30Z"
    }
  ]
}

CRUD lives only behind the SSR /prompts page in v0.15.0 — REST CRUD is on the roadmap. The store is a single JSON file at <workspace>/.vibecoder/prompt-templates.json (RW lock).

Audit log (v0.15.0+ — UI only for now)

/audit is SSR. A GET /api/audit JSON endpoint is on Roadmap §9.B.○. For direct querying see the Audit Log page's psql snippet.

Conversation history (v0.16.0+)

Every assistant message + user prompt + tool invocation is persisted to the conversation_turns table for both per-project sessions and the General Chat scratch project.

GET /api/projects/{projectId}/history

curl -H "Authorization: Bearer $TOKEN" \
  'http://localhost:17880/api/projects/my-app/history?limit=50&sessionId=...'
{
  "turns": [
    {
      "id": 1234,
      "sessionId": "01J...",
      "turnIdx": 0,
      "ts": "2026-05-24T10:00:00Z",
      "role": "user",
      "content": "Add a settings screen with dark-mode toggle.",
      "toolName": null,
      "toolUseId": null,
      "tokensIn": null,
      "tokensOut": null
    },
    {
      "id": 1235,
      "sessionId": "01J...",
      "turnIdx": 1,
      "ts": "2026-05-24T10:00:08Z",
      "role": "assistant",
      "content": "I'll add a Settings composable with a Switch wired to DataStore.",
      "toolName": null,
      "toolUseId": null,
      "tokensIn": 712,
      "tokensOut": 134
    }
  ],
  "nextCursor": null
}

Query parameters: limit (default 100, max 500), sessionId (filter to a single Claude session), before (cursor for pagination — pass the turns[0].id from the previous page).

GET /api/chat/history

Same shape as above for the General Chat scratch project (__scratch__). No projectId path segment.

See Conversation History for the page UI and retention strategy.

Git push (v0.18.0+)

Read-only status / diff / log endpoints from v0.10.0 are joined by a single write endpoint: commit + push.

POST /api/projects/{projectId}/git/commit

curl -X POST http://localhost:17880/api/projects/my-app/git/commit \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "message": "feat: settings screen with dark mode",
    "push": true,
    "onlyTracked": false
  }'
{
  "committed": true,
  "pushed": true,
  "sha": "a1b2c3d4...",
  "branch": "main",
  "errorMessage": null
}

Behavior (sequential, fail-fast):

  1. git config user.name vibe-coder / user.email vibe-coder@localhost (only if unset locally).
  2. git add -A (or git add -u when onlyTracked=true).
  3. git diff --cached --quiet — if nothing staged, returns committed=false, pushed=false.
  4. git commit -m <message> with GIT_AUTHOR_* env.
  5. If push=true, git push <upstream-branch> with GIT_TERMINAL_PROMPT=0 and GIT_SSH_COMMAND='ssh -o BatchMode=yes' — no interactive prompts ever appear.
  6. Push failure does not roll back the commit — returns committed=true, pushed=false, errorMessage=.... Retry with the same call is safe.

Auth is the project's existing PAT (~/.git-credentials) or SSH key (~/.ssh/id_ed25519) — register via the Git integrations endpoints in the previous section.

See Git Workflow for the SSR form and roadmap.

Project source zip (v0.29.0+)

GET /projects/{id}/zip

Stream the project's source tree as a application/zip. The response uses Content-Disposition: attachment; filename="<projectId>-source-<yyyyMMdd-HHmm>.zip" so browsers immediately download.

curl -L -OJ -H "Authorization: Bearer $TOKEN" \
  http://localhost:17880/projects/my-app/zip

Excludes (hard-coded for deterministic backups):

  • .git/, .idea/
  • build/, .gradle/, node_modules/ (anywhere in the tree)
  • *.apk, *.aab

This is a SSR route, not under /api/* — same session-cookie / Bearer auth applies. Streamed directly (no temp file), so large source trees are memory-safe.

See Disk Monitor §"directory-level size" for inverse operation (measuring how much you'd be downloading).

Publishing (v0.22.0–v0.23.0, SSR only)

Build detail page has CSRF-protected forms that fire a structured prompt into the project's Claude session — actual upload runs through the respective MCP. No REST-level wire today.

Form Endpoint MCP it delegates to
Play Console upload POST /projects/{id}/builds/{buildId}/play-upload google-play-publisher
TestFlight upload POST /projects/{id}/builds/{buildId}/testflight-upload app-store-connect

See Publishing to Stores for the full flow, prechecks, and tested-tester-group caveats.

Emulator AVD lifecycle (v0.24.0+, SSR only)

Build detail page has these CSRF-protected forms — no REST-level wire:

Action Endpoint
Create default AVD (vibe-default) POST /emulator/avd/create-default
Headless launch POST /emulator/avd/launch (form field name)
Stop a running emulator POST /emulator/avd/stop (form field serial)

See Android Emulator for full lifecycle docs and :full image setup.

2FA TOTP management (v0.26.0+, SSR only)

GET /2fa — show enable / disable page.

Form Endpoint
Enable POST /2fa/enable (form field code)
Disable POST /2fa/disable (form field code)

The pending secret lives in server memory until the user verifies a code. See Two-Factor Auth for the threat model and recovery.

Prompt suggestions (v0.31.0+)

GET /api/projects/{projectId}/claude/prompt-suggestions

LIKE-prefix match against this project's user turns. Used by the browser console (and the Android client) for autocomplete.

curl -H "Authorization: Bearer $TOKEN" \
  'http://localhost:17880/api/projects/my-app/claude/prompt-suggestions?prefix=Add%20a&limit=8'
{ "suggestions": [
  "Add a settings screen with dark mode toggle",
  "Add a unit test for SignInViewModel",
  "Add a release-notes section to CHANGELOG"
] }
Query param Default Notes
prefix (required, ≥ 2 chars) LIKE-escaped; sub-2-char ignored to avoid empty-prefix dumps
limit 8 Clamped to [1, 20]

60-second in-memory cache per (projectId, prefix) to absorb keystroke bursts. No persisted DTO in shared/ yet — the JSON shape is the simple {"suggestions": [...]} map above.

Conversation export / import (v0.31.0+, SSR)

GET /projects/{projectId}/history/export

Streams a JSON envelope of every persisted turn in the project. Content-Disposition: attachment; filename="<id>-conversation-<yyyyMMdd-HHmm>.json".

Envelope (schemaVersion 1):

{
  "schemaVersion": 1,
  "projectId": "my-app",
  "exportedAt": "2026-05-24T15:00:00Z",
  "turnCount": 1234,
  "turns": [
    { "sessionId": "...", "turnIdx": 0, "ts": "...", "role": "user", "content": "...", ... }
  ]
}

POST /projects/{projectId}/history/import

Multipart upload. Query string carries ?_csrf=<session-csrf> because the form is enctype=multipart/form-data and Ktor requireCsrf() reads form fields by default.

Query param Default Notes
_csrf (required) Session CSRF token (sess.csrf)
dryRun true Counts what would be inserted without writing

5 MB body cap. Idempotency is session-id level — sessions already present in the target are skipped wholesale.

See Conversation Search & Archive for the full flow including auto-archive (v0.33.0).

Build automation (v0.33.0+, SSR + 1 external endpoint)

SSR management — /projects/{id}/automation

Form Endpoint
Add schedule POST /projects/{id}/automation/schedules (form: cronExpr, description)
Toggle schedule POST /projects/{id}/automation/schedules/{scheduleId}/toggle (form: enabled)
Delete schedule POST /projects/{id}/automation/schedules/{scheduleId}/delete
Create webhook secret POST /projects/{id}/automation/secrets (form: name)
Delete webhook secret POST /projects/{id}/automation/secrets/{secretId}/delete

External trigger — POST /api/webhooks/build/{projectId}

Admin-auth-free endpoint that lets external systems (GitHub Actions, GitLab CI, monitoring) fire a debug build.

SECRET='<paste>'                          # one-time shown in /automation
SECRET_ID='<from-secret-table>'
BODY='{"ci":"github-actions","sha":"deadbeef"}'
SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "http://<host>:17880/api/webhooks/build/my-app" \
  -H "X-Vibe-Secret-Id: $SECRET_ID" \
  -H "X-Vibe-Secret: $SECRET" \
  -H "X-Vibe-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  --data "$BODY"
Header Required Purpose
X-Vibe-Secret-Id ✅ Row lookup in build_webhook_secrets
X-Vibe-Secret ✅ Plaintext secret; server compares SHA-256(secret) to stored hash (TLS expected)
X-Vibe-Signature optional HMAC-SHA256(secret, body) hex; if present and body non-empty, also verified

Response: 202 Accepted {"projectId":"my-app","triggered":true}.

See Build Automation for the full security discussion and roadmap (rate limiting, HMAC-only mode).

Backup (v0.34.0+, SSR)

GET /backup — page with subdirectory sizes and the download button.

GET /backup/download — streams application/gzip (Content-Disposition vibe-workspace-<yyyyMMdd-HHmm>.tar.gz). Excludes postgres/, dev-tools/gradle/caches+daemon, npm-cache, playwright, .vibecoder/__scratch__/, .vibecoder/*/logs/.

PostgreSQL is not in the tar — use pg_dump separately (the page renders the command). See Backup & Restore.

Cross-project tools (v0.30.0–v0.32.0, SSR)

  • /history — global conversation search (LIKE + role filter, 200-hit cap, ±100 char excerpt with <mark> highlight).
  • /logs — build-log grep across .vibecoder/<projectId>/logs/*.log (last 2 MB per file scanned, 200-match cap, optional project filter).
  • /projects/{id}/deps — Gradle dependency tree (90 s timeout, raw output 200 KB cap) + group:name:version coordinate extraction.
  • /projects/{id}/env-files — whitelist editor for 7 env / build property files (256 KB cap each, atomic write).

All four are SSR-only (no REST wire).

Environment setup (v0.10.0)

GET /api/env-setup/components

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:17880/api/env-setup/components
{
  "components": [
    {"id":"java","displayName":"JDK 17","status":"INSTALLED","installable":false, ...},
    {"id":"android-sdk","displayName":"Android SDK","status":"MISSING","installable":true, ...},
    {"id":"claude-auth","displayName":"Claude 로그인","status":"INSTALLED","installable":false, ...}
  ]
}

POST /api/env-setup/install-all

Trigger sequential install of every installable component. Returns {"taskId":"..."}. Subscribe to /ws/env-setup/{taskId}/logs for live output.

POST /api/env-setup/{componentId}/install

Install a specific component (e.g. android-sdk).

Tracking install progress (client-side only)

The ComponentStateDto returned by GET /api/env-setup/components has no installingTaskId (or equivalent) field. Its full shape is:

id, displayName, description, sizeHint, status, message, installable

That means the wire does not tell you which component is currently installing. The contract is:

  1. Client calls POST .../install (or install-all).
  2. Server returns EnvSetupTaskDto{ taskId } once.
  3. Client stores the (componentId → taskId) mapping itself and subscribes to /ws/env-setup/{taskId}/logs.
  4. When WsFrame.Done arrives, the client drops the mapping and may refresh GET /components to confirm the new status.

The server has a lastTask[component] cache internally (used by the SSR template to render "View live progress →" links), but it is intentionally not exposed in any JSON response — different clients can be installing different components concurrently from different sessions, so per-client ownership of the taskId is the right model.

If your UI shows a per-component "installing…" spinner, do it from local state seeded by the install response, not by re-polling /components.

Claude authentication (v0.10.0)

POST /api/env-setup/claude-auth/upload (multipart)

Upload .credentials.json obtained on another machine.

curl -X POST http://localhost:17880/api/env-setup/claude-auth/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@$HOME/.claude/.credentials.json"
# → {"targetPath":"/home/vibe/.claude/.credentials.json", ...}

POST /api/env-setup/claude-auth/api-key

curl -X POST http://localhost:17880/api/env-setup/claude-auth/api-key \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"apiKey":"sk-ant-..."}'
# → 204 No Content

DELETE /api/env-setup/claude-auth/api-key/delete

Remove the API key (also accepts POST for clients that lack DELETE).

Claude semi-automatic web OAuth (v0.10.0)

POST /api/env-setup/claude-login/start

Spawn claude auth login wrapped in script -q. Returns the initial state.

curl -X POST http://localhost:17880/api/env-setup/claude-login/start \
  -H "Authorization: Bearer $TOKEN"
{
  "id":"task-...",
  "state":"STARTING",
  "url":null,
  "startedAt":"2026-05-23T12:00:00Z",
  "updatedAt":"2026-05-23T12:00:00Z",
  "errorMessage":null,
  "lastLines":[]
}

Poll /api/env-setup/claude-login/status every 1 s until state becomes AWAITING_CODE (and url is set).

GET /api/env-setup/claude-login/status

Same shape as above. Returns 204 if no session active.

POST /api/env-setup/claude-login/submit

curl -X POST http://localhost:17880/api/env-setup/claude-login/submit \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"code":"abc...#xyz"}'

State → VERIFYING, then DONE or FAILED.

POST /api/env-setup/claude-login/cancel

Destroy the child process. State → CANCELED.

MCP catalog (v0.10.0)

GET /api/env-setup/mcp

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:17880/api/env-setup/mcp
{
  "entries": [
    {
      "id":"github",
      "displayName":"GitHub",
      "pkg":"@modelcontextprotocol/server-github",
      "description":"...",
      "category":"Git 호스팅 (GitHub / GitLab / Gitea / Bitbucket)",
      "trust":"VERIFIED",
      "recommended":true,
      "homepage":null,
      "configFields":[
        {"key":"GITHUB_PERSONAL_ACCESS_TOKEN","label":"GitHub PAT","placeholder":"ghp_...","isSecret":true,"required":true,"help":"..."}
      ],
      "status":"NOT_INSTALLED",
      "configValues":{},
      "comingSoon":false
    },
    ...
  ]
}

McpConfigFieldDto reference

The configFields[] entries have a fixed shape with these 8 keys (no type, no default — those concepts don't exist in the catalog):

Key Type Required Default Purpose
key String ✅ — Stored verbatim as the env var name in .mcp.json (e.g. GITHUB_PERSONAL_ACCESS_TOKEN).
label String ✅ — Human-readable text for the form label.
placeholder String? — null HTML placeholder attribute, e.g. "ghp_...".
isSecret Boolean — false Render as <input type="password"> / masked field.
required Boolean — true Server rejects install with 400 missing_config if a required field is empty.
help String? — null Tooltip / sub-label describing the field.
isFile Boolean — false v0.11.0+. true → render a file picker and call the multipart upload endpoint below.
acceptMime String? — null When isFile=true, value for HTML <input accept="...">, e.g. ".json,application/json".

Notes:

  • A field's value type is always String at the wire level. Files go through the multipart upload endpoint and the server returns an absolute path which the client then sends back as the String value.
  • There is no default field in the wire. If a catalog entry needs a sensible default (e.g. --workspace-root /workspace for filesystem), it is baked into argsTemplate in McpCatalog.kt, not exposed to the client.

POST /api/env-setup/mcp/install

curl -X POST http://localhost:17880/api/env-setup/mcp/install \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "selections": {
      "filesystem": {},
      "github": {"GITHUB_PERSONAL_ACCESS_TOKEN":"ghp_..."},
      "context7": {}
    }
  }'
# → {"taskId":"..."}    (subscribe to /ws/env-setup/{taskId}/logs)

POST /api/env-setup/mcp/unregister

Removes entries from .mcp.json. The npm package itself stays on disk.

curl -X POST http://localhost:17880/api/env-setup/mcp/unregister \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"ids":["github","slack"]}'
# → 204 No Content

POST /api/env-setup/mcp/{mcpId}/file/{fieldKey} (multipart, v0.11.0+)

Upload a secret file (Service Account JSON, Apple .p8, OAuth client.json) for an MCP entry whose configFields[].isFile is true.

curl -X POST http://localhost:17880/api/env-setup/mcp/google-play-publisher/file/GOOGLE_PLAY_SERVICE_ACCOUNT_JSON \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./play-sa.json"
# → {"path":"/home/vibe/.config/mcp-secrets/google-play-publisher-GOOGLE_PLAY_SERVICE_ACCOUNT_JSON.json"}

Then pass the returned path as the value for that config key in the subsequent POST /api/env-setup/mcp/install:

curl -X POST http://localhost:17880/api/env-setup/mcp/install \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "selections": {
      "google-play-publisher": {
        "GOOGLE_PLAY_SERVICE_ACCOUNT_JSON": "/home/vibe/.config/mcp-secrets/google-play-publisher-GOOGLE_PLAY_SERVICE_ACCOUNT_JSON.json",
        "GOOGLE_PLAY_PACKAGE_NAME": "com.siamakerlab.myapp"
      }
    }
  }'
  • File saved with 0600 permissions in ${CLAUDE_CONFIG_DIR}/mcp-secrets/.
  • 128 KB size cap (normal Service Account / .p8 is a few KB).
  • Filename sanitized — only [A-Za-z0-9._-] in the stored name.
  • Re-upload to replace (atomic move).

Git integrations (v0.10.0)

GET /api/settings/git-integrations

List registered PATs (masked) + SSH public key.

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:17880/api/settings/git-integrations
{
  "tokens": [
    {"provider":"github","host":"github.com","username":"x-access-token","tokenMasked":"••••••••wxyz","createdAt":"2026-05-23T12:00:00Z","note":null}
  ],
  "sshPublicKey": "ssh-ed25519 AAAA... vibe-coder"
}

POST /api/settings/git-integrations

curl -X POST http://localhost:17880/api/settings/git-integrations \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "provider":"github",
    "host":"github.com",
    "username":"x-access-token",
    "token":"ghp_...",
    "note":"vibe-coder PAT, expires 2026-12"
  }'
# → 204 No Content

POST /api/settings/git-integrations/delete

curl -X POST http://localhost:17880/api/settings/git-integrations/delete \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"host":"github.com"}'

POST /api/settings/git-integrations/ssh-keygen

Generate ed25519 key pair if missing. Returns the full state including the public key for the user to copy.

Error response shape

{
  "code": "missing_clone_url",
  "message": "sourceType=clone 일 때 cloneUrl 이 필수입니다.",
  "detail": null
}

HTTP status codes: 400 bad input, 401 no/invalid token, 403 insufficient permission, 404 not found, 409 conflict, 413 payload too large, 502 upstream failed (git clone, npm install), 504 timeout.

Clone this wiki locally