# Veldon Edit quickstart

Create a working site from your terminal with one request. No browser, no signup
form. Works the same for humans, scripts, CI, and AI agents.

## 1. Bootstrap a free workspace and site

```sh
curl -sS -X POST https://api.veldon.cz/v1/bootstrap/free \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: my-first-site-$(whoami)" \
  -d '{"workspaceName":"My Studio","siteAddress":"my-first-site"}'
```

The response (HTTP 201) contains everything you need. Save it:

```json
{
  "tenantId": "ten_...",
  "siteId": "site-...",
  "siteAddress": "my-first-site",
  "management": { "id": "cred_...", "token": "vapi_...", "scopes": ["site:read", "site:content:write", "site:definition:write", "site:publish", "site:admin"] },
  "project":    { "id": "cred_...", "token": "vapi_...", "scopes": ["site:read", "site:content:write", "site:definition:write", "site:publish"] },
  "urls": {
    "currentDelivery": "https://api.veldon.cz/public/sites/my-first-site/current",
    "mediaTemplate": "https://api.veldon.cz/public/sites/my-first-site/media/{assetId}",
    "mcp": "https://api.veldon.cz/mcp",
    "dashboard": "https://api.veldon.cz/dashboard"
  }
}
```

Two keys come back:

- **management** token (`site:admin`, can issue delegated tokens) — keep it in your
  password manager or secret store. Never commit it.
- **project** token (read, write content, change structure, publish) — this is the
  one your site's build and tools use. Put it in `.env` (gitignored) as
  `VELDON_API_TOKEN`.

## 1a. Claim the browser login (open the dashboard)

A bootstrapped workspace starts credential-owned: you drive it entirely from the
terminal and the API. To also sign in to the browser dashboard, claim the owner
account — set a real email and password on it with your **management** token:

```sh
curl -sS -X POST https://api.veldon.cz/v1/bootstrap/claim \
  -H "Authorization: Bearer $MANAGEMENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"a-strong-password"}'
```

A `204` means done — log in at https://api.veldon.cz/login with that email and
password. For a new account, the password becomes its login. If the email already
belongs to your Veldon account, enter that account's current password: a
compatible claim attaches the workspace's existing owner membership to the
account instead of creating a second member, so the free one-user limit remains
untouched. Passwords are 10–200 characters.

Claiming is one-time. After the owner is attached to an account, password changes
go through the normal recovery flow, not this endpoint. A `409` is intentionally
opaque: the proof may be wrong, the owner may already be claimed incompatibly, or
the target account may already have an incompatible association with this
workspace. It does not disclose whether an email has a Veldon account. This step
is optional — skip it if you only need API/MCP access.

Once signed in, every site card has an **Edit site** button — a visual editor
that edits your real draft in place and publishes real revisions. See
[Browser editing](editing.md).

### Replay is your recovery

The same `Idempotency-Key` with the same body returns the **same response,
including the tokens**. Lost the tokens after a crash? Repeat the exact request.
The same key with a *different* body returns `409` and never creates a second
workspace. Pick keys that are stable per project (`provision-<project>`), not
random.

## 2. Put content and publish

```sh
TOKEN='vapi_...'   # the project token
SITE='site-...'

# write content (first write uses baseRevisionId: null)
curl -sS -X PUT "https://api.veldon.cz/v1/sites/$SITE/content" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  --data @content.json

# publish the returned revision
curl -sS -X POST "https://api.veldon.cz/v1/sites/$SITE/publish" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"revisionId":"rev_..."}'
```

Your published content is now served at the delivery URL from step 1. Wire your
frontend to it: see [existing-site.md](existing-site.md).

## 3. Connect an AI assistant (optional)

```sh
claude mcp add --transport http veldon-edit --scope user \
  'https://api.veldon.cz/mcp' \
  --header 'Authorization: Bearer vapi_...'
```

Then ask: "what sites do I have?" Details: [mcp.md](mcp.md).

## Notes

- The free tier is one live site, one user, with quotas that an ordinary site
  will not hit — see [quotas-and-errors.md](quotas-and-errors.md).
- A bootstrap-created workspace is **credential-owned** until you claim it: whoever
  holds the management token controls it. Run the claim step above to attach a
  human email + password and open the browser dashboard.
- When public registration is enabled, browser signup at
  https://api.veldon.cz/signup creates the same kind of workspace with a human
  login attached. Deployments may intentionally keep signup closed while
  retaining account sign-in and recovery.
- One account can access several workspaces and accept customer invitations; see
  [Accounts, workspaces, and invitations](accounts-and-workspaces.md).