Build on Eyivo through one structured API.

1. Overview

The Eyivo REST API is the programmatic control plane for structured websites. It uses HTTPS and JSON, is versioned under /api/v1, and applies the same ownership, plan limits, validation, and audit boundaries as the dashboard.

Versioning: breaking contract changes require a new base version. Additive fields may appear in existing JSON objects, so clients should ignore fields they do not recognize.

2. Quick start

1. 1
   Create a token.

   Sign in to the App, open API tokens, choose the smallest necessary scopes, and copy the ey_ secret when it is shown.

2. 2
   List your sites.

   Confirm authentication and obtain the numeric site ID used by nested endpoints.

3. 3
   Send idempotent writes.

   Give every POST, PATCH, and DELETE request a unique Idempotency-Key.

curl --request GET \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token'

A successful collection response wraps records in data:

{
  "data": [
    {
      "id": 42,
      "platform_subdomain_key": "7kr9mp2x",
      "template_key": "corporate-01",
      "status": "active",
      "native_locale": "en",
      "english_enabled": false,
      "content_version": 1,
      "search_visibility": "platform_noindex"
    }
  ]
}

3. Authentication

Every /api/v1 request requires a bearer token:

Authorization: Bearer <token>

PKCE authorization flow

1. Create a high-entropy code_verifier and its SHA-256 code_challenge.
2. Redirect the user to /oauth/authorize with response_type=code, the public client_id, exact registered redirect_uri, requested space-separated scope, state, code_challenge, and code_challenge_method=S256.
3. Verify state after the redirect, then exchange the returned authorization code at /oauth/token using the original code_verifier.
4. Store access and refresh tokens securely. Refresh before expiration and replace rotated credentials atomically.

4. Scopes

Requests need the exact scope shown below. A personal token containing * passes all scope checks; applications should still request the smallest practical scope set.

REST requires the endpoint scope, not mcp:use. Media endpoints use media:read or media:write.

5. Idempotent writes

Send an Idempotency-Key with JSON mutations so the same request can be retried safely. Multipart media uploads and upload-ticket issuance are excluded; verify the transfer result before retrying.

Idempotency-Key: site-42-page-create-01J7M6Y8RRF3ZE6WB4Z0Y9XJXC

A request match includes the HTTP method, request path, and exact raw request body. Reuse the original serialized JSON when retrying.

6. Responses and resource shapes

Content operations return a data envelope. MCP supplies structuredContent plus a JSON text mirror; REST returns JSON. Read each output schema for IDs, publication readiness and pagination. Blogs, media and submissions paginate; follow their returned page information.

{ "data": { "id": 42, "status": "active" } }

{ "data": [{ "id": 42 }, { "id": 43 }] }

Collection shapes vary. Follow each endpoint’s documented pagination metadata; do not assume every result is a flat or unpaginated list.

7. Sites

Create a site

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: site-create-01J7M6Y8' \
  --data '{
    "display_name": "Northstar Studio",
    "template_key": "corporate-01",
    "native_locale": "en"
  }'

Response: 201 Created with a site resource. Provisioning can initially report a non-active status while placement completes. Site and plan limits return 422.

Site resource fields: id, platform_subdomain_key, template_key, status, native_locale, english_enabled, content_version, search_visibility, optional runtime, and timestamps.

8. Pages

Create a page

{
  "type": "page",
  "sort_order": 300,
  "locale": "en",
  "slug": "our-story",
  "title": "Our story",
  "body": "<p>How the company began.</p>",
  "meta_title": "Our story | Northstar Studio",
  "meta_description": "Learn about Northstar Studio."
}

Create response: 201. Update response: 200. Delete response: 204 with no body.

Save a draft, inspect its readiness, then publish that item and language when the user wants the change live. Publishing does not publish unrelated drafts.

9. Catalog items

Create a catalog item

{
  "sort_order": 100,
  "locale": "en",
  "slug": "strategy-advisory",
  "title": "Strategy advisory",
  "summary": "Focused advice for consequential decisions.",
  "body": "Talk to our senior advisory team."
}

Save a draft, inspect its readiness, then publish that item and language when the user wants the change live. Publishing does not publish unrelated drafts.

These are examples by content family. Discover the complete input/output schemas and required scopes through tools/list or the canonical OpenAPI document. REST paths below are relative to /api/v1/sites/{site}.

Capabilities and authoring contract

Select a site, then read its capabilities: enabled languages, theme fields, component schemas, menu locations and installed plugin panels. Read the content-workflow resource before writing. Clients without resources can use get-site-capabilities-tool. Follow tools/list nextCursor until discovery is complete.

GET /api/v1/sites/{site}/capabilities
GET /api/v1/sites/{site}/pages/{page_id}/components/schema?locale=en

Use the requested locale and current version or revision. Blog saves replace the complete document and cancel its schedule. Menu edits use integer revision; content assignments use a separate menu_revision hash. Preserve entries in replacement arrays. On a conflict, read again and merge the intended edits before retrying.

Main navigation stays automatic. Additional menus have their own drafts and publication. Saving content stages its menu assignments; publishing that item applies them without publishing other menu drafts. Publishing a menu never publishes its linked content. A page source_hash rejects translations based on outdated source text.

Page body and theme richtext fields accept sanitized HTML. Use list-page-links-tool for stable /__eyivo/pages/{id} links, resolved in the visitor’s language when published. Blog posts use structured document JSON with same-site media_id and page/post link targets, not body_html.

{
  "type": "doc",
  "content": [{
    "type": "paragraph",
    "content": [{ "type": "text", "text": "Our story" }]
  }]
}

Image and video uploads

upload-media-tool opens a file picker in MCP Apps clients such as Claude. ChatGPT can also supply its host attachment reference; a Claude chat attachment is not an OpenAI file reference. Never invent a download URL or send base64 file bytes as tool arguments.

Codex and Claude Code can call prepare-media-upload-tool, then send multipart file bytes to the returned upload_url with its one-use upload_token within five minutes. Keep that token secret. REST clients can upload with their own media:write bearer. Only a completed upload returns the media ID to use in content; issuing a ticket does not upload a file.

POST /api/v1/sites/{site}/media
Authorization: Bearer <media:write token>
Content-Type: multipart/form-data; boundary=<generated by HTTP client>

file: <original file bytes>

10. Custom domains

Request a domain

curl --request POST \
  --url https://app.eyivo.com/api/v1/sites/42/domains \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ey_your_token' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: domain-request-example-com' \
  --data '{"domain":"www.example.com"}'

A pending domain resource includes verification_token. Add the required DNS ownership record using the value returned for your domain, wait for DNS propagation, then call the activation endpoint. Once active, call the primary endpoint if it should become the canonical public hostname.

Domain resource fields: id, domain, site_id, is_primary, status, conditional verification_token, and timestamps. Custom-domain plan limits and domain validation failures return 422.

11. Errors

Validation response

{
  "message": "The title field is required.",
  "errors": {
    "title": ["The title field is required."]
  }
}

Authentication or authorization response

{
  "message": "Missing required scope [content:write]."
}

12. Current boundaries and integration checklist

REST v1 intentionally exposes a focused subset of Eyivo. The absence of an endpoint is a contract boundary, not permission to call internal APIs.

Before production

• Use HTTPS and validate the expected app.eyivo.com host.
• Keep bearer tokens server-side and redact authorization headers from logs.
• Request only necessary scopes and prefer site-restricted personal tokens when possible.
• Use a unique idempotency key for every logical write and preserve it across retries.
• Treat 401, 403, 404, and 422 as non-transient unless the underlying request or credential changes.
• Use exponential backoff with jitter for transient failures and respect any future Retry-After header.
• Collection shapes vary. Follow each endpoint’s documented pagination metadata; do not assume every result is a flat or unpaginated list.