# Siteio LLM API (v1)

Siteio lets external coding agents (Claude Code, OpenAI Codex, other terminal agents) run a full autonomous website loop.

Base URL:
- https://siteio.com

Authentication:
- Header: Authorization: Bearer <SITEIO_API_KEY>
- API keys are organization-scoped.

OpenAPI:
- https://siteio.com/api/llm/v1/openapi.json

Primary endpoints (v1):
1) POST https://siteio.com/api/llm/v1/websites
   - Create draft website from prompt + optional checklist
   - Generates theme, hybrid imagery pack (AI + stock), and landing sections

2) GET https://siteio.com/api/llm/v1/websites/{id}/structure
   - Read full editable website structure + revision token

3) GET https://siteio.com/api/llm/v1/websites/{id}/revision
   - Cheap revision token only (no full structure) for re-sync

4) POST https://siteio.com/api/llm/v1/websites/{id}/snapshots
   - Create a rollback snapshot

5) POST https://siteio.com/api/llm/v1/websites/{id}/patch
   - Apply patch ops against content-hash revision (scoped rebase for non-overlapping concurrent edits)

6) POST https://siteio.com/api/llm/v1/websites/{id}/validate
   - Run content + screenshot validation, return score/issues/suggestions

7) POST https://siteio.com/api/llm/v1/websites/{id}/restore
   - Restore from a snapshot

8) POST https://siteio.com/api/llm/v1/websites/{id}/publish/request
   - Generate one-time publish approval token

9) POST https://siteio.com/api/llm/v1/websites/{id}/publish/confirm
   - Publish using approval token (explicit confirm step)

10) GET https://siteio.com/api/llm/v1/websites/{id}/report
   - Fetch run summary and iteration history

11) POST https://siteio.com/api/llm/v1/feedback
   - Store user/agent feedback for run tuning

Imagery (dashboard session auth):
- POST https://siteio.com/api/ai/image/resolve — hybrid pack (OpenAI hero/product/abstract + Unsplash avatars/lifestyle)
- POST https://siteio.com/api/ai/image/generate — single AI image

Taste / quality (read before patching JSX):
- Domain-first design: do not default non-SaaS briefs to purple glass SaaS chrome
- Prefer real Image URLs from resolve_images / project assets — never invent stock CDN URLs; gray placeholders only as last resort
- JSX contract: no map/conditionals, ShadCN theme tokens, font-heading on headings, hardcoded list items
- Build section-by-section (never one giant page compose)

Loop contract (agent-side orchestration):
1) Create website and run.
2) Resolve images if refining visuals (MCP: resolve_images).
3) Read structure + revision.
4) Snapshot before each edit.
5) Patch with revision token (API creates pre and post snapshots automatically).
6) Validate and score.
7) If score regresses or critical failures appear, restore snapshot and retry.
8) Stop when target score + all critical checklist items pass, or max loops is reached.
9) Keep draft by default and return report.
10) Publish only after /publish/request + /publish/confirm.

Patch contract:
- revision is a deterministic content-hash ETag (identical persisted content => identical token).
  Reads and failed writes do not advance it. Timestamps are not part of the hash.
- conflict detection is scoped to entities each op touches; non-overlapping concurrent
  writes (e.g. editor autosave on another page vs updateProject) auto-rebase server-side.
- optional force=true for last-writer-wins; optional idempotencyKey for replay-safe tools.
- request shape:
  {
    "revision": "v1.<global>.<entity-digests>",
    "commitMessage": "Improve hero CTA contrast and pricing cards",
    "ops": [
      { "op": "updateProject", "payload": { "name": "..." } },
      { "op": "upsertPage", "pagePublicId": "...", "payload": { "name": "...", "url": "/", "blocks": [] } },
      { "op": "upsertComponent", "componentPublicId": "...", "payload": { "name": "...", "blocks": [] } },
      { "op": "deletePage", "pagePublicId": "..." },
      { "op": "deleteComponent", "componentPublicId": "..." }
    ],
    "force": false,
    "idempotencyKey": "optional-tool-key"
  }
- on overlapping revision conflict, API returns HTTP 409 with currentRevision + overlappingKeys.
- success response includes:
  {
    "success": true,
    "revision": "next-revision",
    "preSnapshotId": 123,
    "postSnapshotId": 124,
    "rebased": false,
    "stats": { ... }
  }
- patch failures auto-restore the pre snapshot.

Validation contract:
- response shape:
  {
    "score": 0-100,
    "pass": true|false,
    "criticalFailures": ["..."],
    "issues": ["..."],
    "suggestions": ["..."],
    "artifacts": { "desktopPngUrl": "...", "mobilePngUrl": "..." }
  }

Stop criteria defaults:
- targetScore: 95
- maxLoops: 12
- fail early after repeated non-improvement can be implemented agent-side using iteration scores

Backward compatibility:
- Legacy endpoints remain available:
  - POST https://siteio.com/api/llm/websites
  - GET https://siteio.com/api/llm/websites
  - GET https://siteio.com/api/llm/websites/{id}

Key management (dashboard-authenticated, admin only):
- POST https://siteio.com/api/llm/api-keys
- GET https://siteio.com/api/llm/api-keys
- DELETE https://siteio.com/api/llm/api-keys/{id}

# Siteio MCP (Claude custom connectors)

Remote MCP lets Claude create and edit Siteio websites through tools that wrap the LLM v1 loop.

MCP endpoint:
- https://siteio.com/api/mcp

OAuth (required for Claude Advanced settings Client ID + Secret):
- Authorization server metadata: https://siteio.com/.well-known/oauth-authorization-server
- Protected resource metadata: https://siteio.com/.well-known/oauth-protected-resource
- Authorize: https://siteio.com/oauth/mcp/authorize
- Token: https://siteio.com/oauth/mcp/token
- Revoke: https://siteio.com/oauth/mcp/revoke
- Scopes: mcp:websites:read mcp:websites:write mcp:websites:publish

Create OAuth client (dashboard-authenticated, admin only):
- POST https://siteio.com/api/mcp/oauth/clients
- GET https://siteio.com/api/mcp/oauth/clients
- DELETE https://siteio.com/api/mcp/oauth/clients/{id}

Connect Claude:
1) Dashboard → Settings → Claude / MCP → Generate credentials (Client ID + Client Secret shown once)
2) Claude → Settings → Connectors → Add custom connector
3) MCP Server URL: https://siteio.com/api/mcp
4) Advanced → paste Client ID and Client Secret
5) Complete Siteio consent, then enable the connector in chat

MCP resources (read before building):
- siteio://taste/design
- siteio://taste/jsx
- siteio://taste/imagery
- siteio://taste/workflow

MCP prompt:
- build_modern_website (brief → create → resolve images → patch → validate)

MCP tools:
- list_websites
- create_website
- get_website_structure
- get_website_revision
- create_snapshot
- patch_website
- validate_website
- restore_snapshot
- resolve_images
- generate_image
- search_stock_images
- request_publish
- confirm_publish
- get_deployment_status
- get_deployment_logs
- get_build_errors
- validate_deploy
- get_website_report

Agent loop via MCP mirrors the HTTP contract above (snapshot → patch → validate → restore on regress).
Always prefer resolved asset URLs over gray placeholders.