# Litehost Connect

> Turn files and websites into shareable links (https://<slug>.litepage.site) and manage them.
> REST API at https://connect.litehost.io. Full reference: https://api-docs.litehost.io
> OpenAPI: https://connect.litehost.io/openapi.json

## MCP server (for assistants that support MCP)

URL: https://connect.litehost.io/mcp — Streamable HTTP, OAuth 2.1 with PKCE (dynamic client
registration; discovery at /.well-known/oauth-authorization-server). API keys also work as Bearer.
Tools: publish_site, create_upload_link (a page where the user uploads a file they already have), list_projects, get_project, get_qr_code, get_link_opens, update_project_files,
update_project_settings, delete_project, get_account.

## Pick the path first (REST API)

1. You already have a key (env LITEHOST_API_KEY, or ~/.config/litehost/credentials.json):
   send "Authorization: Bearer <key>". Check it once with GET /v1/auth/session.
   Do NOT sign in again while it works.
2. No key, and the user just wants a link: POST /v1/projects/temp (multipart "files", no auth).
   Give the user "url" (live for 15 minutes) and "claimUrl" (they open it and sign in with Google
   or email in the browser to keep the project). You never need a code or a key for this.
3. No key, and the user wants you to manage their projects over time: sign in ONCE (below),
   save the key, and reuse it in every later session.

## Sign in (path 3 only)

1. POST /v1/auth/otp/request {"email": "..."} emails a 6-digit code. Call it once.
   Calling it again while a code is open sends nothing ("data.codeAlreadySent": true).
2. Ask the user for the code and wait for their answer. Do not call request again while waiting.
3. POST /v1/auth/otp/verify {"email": "...", "code": "123456"} returns "data.apiKey".
   - OTP_INVALID: the user mistyped. Ask them to re-check the same email. Do NOT request a new code.
   - OTP_EXPIRED or OTP_TOO_MANY_ATTEMPTS: request a new code, once.
   - The user says no email arrived (after checking spam): POST /v1/auth/otp/request
     {"email": "...", "resend": true} sends the same code again.
4. Save the key (see below) and tell the user where you saved it.

Sign-in keys renew automatically while in use. They expire only after 90 days without use.
Permanent keys can also be created in https://litehost.io/dashboard (Integrations).

## Storing the key

- With a filesystem: write {"apiKey": "lh_live_...", "email": "..."} to
  ~/.config/litehost/credentials.json (chmod 600) and read it at the start of every session.
- Hosted agents with a secret store: save it as LITEHOST_API_KEY.
- No storage at all: ask the user to keep the key and paste it next time.
Never show the full key again once saved.

## Errors

Every error has "code", "error" and "nextStep". Follow "nextStep".
- API_KEY_MISSING: send the saved key. Sign in only if there is none (and only for path 3).
- API_KEY_INVALID / API_KEY_EXPIRED: delete the saved key, then sign in once.
- FREE_TIER_RESTRICTED: the key is fine; the endpoint needs a paid plan. Do not sign in again.
- PROJECT_LIMIT_REACHED / STORAGE_LIMIT_REACHED: check GET /v1/user; archive or delete projects, or upgrade.
- RATE_LIMITED: wait "retryAfterSeconds".

## Common calls (Bearer key)

- GET /v1/user: plan and quota
- POST /v1/projects (multipart: files, title, slug, access, password, expiresIn, zipIndexHtmlPath): create
- GET /v1/projects: list
- GET /v1/projects/{id}: details and live url
- GET /v1/projects/{id}/analytics: opens (total, last opened, recent opens with country and device; paid plans).
  An open is a person viewing the link in a browser. Link previews (WhatsApp, Slack…), bots, email
  scanners, AI assistants fetching the link and the owner's own views are not opens. Optional fields:
  "visits" (every non-bot page request, previews included) and "ownerOpens" (the owner's own opens).
- PUT /v1/projects/{id} (multipart files): publish a new version (paid plans)
- PATCH /v1/projects/{id}: title, slug, access, password, expiry (paid plans)
- DELETE /v1/projects/{id}
- POST /v1/projects/claim/{claimToken}: keep a temp project in the signed-in account

Always give the user the live "url" after creating or updating a project.