Desenvolva com a Eyivo através de uma única API estruturada.

1. Visão geral

A API REST da Eyivo permite controlar programaticamente sites estruturados. Usa HTTPS e JSON, tem versões em /api/v1 e aplica as mesmas regras de titularidade, limites do plano, validação e auditoria do painel.

Versionamento: mudanças incompatíveis no contrato exigem uma nova versão base. Objetos JSON existentes podem ganhar campos adicionais; os clientes devem ignorar campos que não reconheçam.

2. Início rápido

1. 1
   Crie um token.

   Inicie sessão na aplicação, abra Tokens de API, escolha apenas os âmbitos necessários e copie o ey_ segredo quando for apresentado.

2. 2
   Liste os seus sites.

   Confirme a autenticação e obtenha o ID numérico do site usado pelos endpoints subordinados.

3. 3
   Envie pedidos de escrita idempotentes.

   Atribua a cada pedido POST, PATCH e DELETE uma Idempotency-Key.

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

Uma resposta bem-sucedida de uma coleção inclui os registos em 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. Autenticação

Cada pedido a /api/v1 exige um token Bearer:

Authorization: Bearer <token>

Fluxo de autorização PKCE

1. Crie um code_verifier de alta entropia e seu code_challenge SHA-256.
2. Redirecione o utilizador para /oauth/authorize com response_type=code, o client_id público, o redirect_uri registado exatamente, os âmbitos solicitados em scope separados por espaços, state, code_challenge e code_challenge_method=S256.
3. Verifique state após o redirecionamento e troque o código de autorização recebido em /oauth/token usando o code_verifier original.
4. Guarde os tokens de acesso e renovação em segurança. Renove-os antes de expirarem e substitua atomicamente as credenciais alteradas.

4. Âmbitos

Os pedidos exigem o âmbito exato indicado abaixo. Um token pessoal com * passa todas as verificações de âmbito; as aplicações devem ainda assim solicitar apenas os âmbitos necessários.

REST exige a permissão do endpoint, não mcp:use. Mídia usa media:read ou media:write.

5. Operações de escrita idempotentes

Envie Idempotency-Key nas alterações JSON para repetir a mesma solicitação com segurança. Uploads multipart e emissão de tickets ficam de fora; confira o resultado antes de tentar novamente.

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

Para corresponderem, os pedidos têm de ter o mesmo método HTTP, caminho e corpo original. Ao tentar novamente, reutilize o JSON serializado original.

6. Respostas e estrutura dos recursos

Operações de conteúdo retornam um envelope data. MCP fornece structuredContent e uma cópia JSON em texto; REST retorna JSON. Consulte os esquemas para IDs, prontidão e paginação. Siga as informações de página de blogs, mídia e envios.

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

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

Os formatos das coleções variam. Siga a paginação documentada de cada endpoint; nem todos os resultados são listas simples ou sem paginação.

7. Sites

Criar um 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"
  }'

Resposta: 201 Created com um recurso de site. Durante a preparação, o estado pode não estar ativo inicialmente. Os limites de sites e do plano devolvem 422.

Campos do recurso de site: id, platform_subdomain_key, template_key, status, native_locale, english_enabled, content_version, search_visibility, runtime opcional e datas de criação e atualização.

8. Páginas

Criar uma página

{
  "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."
}

Resposta à criação: 201. Resposta à atualização: 200. Resposta à eliminação: 204 sem corpo.

Salve um rascunho, confira se está pronto e publique o item no idioma desejado quando o usuário quiser torná-lo público. Outros rascunhos não são publicados.

9. Itens do catálogo

Criar um item do catálogo

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

Salve um rascunho, confira se está pronto e publique o item no idioma desejado quando o usuário quiser torná-lo público. Outros rascunhos não são publicados.

Estes são exemplos por família de conteúdo. Descubra todos os esquemas e permissões em tools/list ou OpenAPI. Os caminhos REST são relativos a /api/v1/sites/{site}.

Capacidades e contrato de edição

Selecione um site e leia suas capacidades: idiomas ativos, campos do tema, esquemas dos componentes, menus e painéis dos plugins. Leia o recurso content-workflow antes de escrever. Sem recursos, use get-site-capabilities-tool. Siga nextCursor de tools/list até concluir a descoberta.

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

Use o idioma solicitado e a version ou revision atual. Salvar um blog substitui o documento completo e cancela o agendamento. Menus usam revision numérica; atribuições usam um hash menu_revision separado. Preserve os itens das listas substituídas. Em conflitos, releia e combine as alterações.

A navegação principal continua automática. Menus adicionais têm seus próprios rascunhos e publicação. Salvar conteúdo prepara suas atribuições; publicar o item aplica essas atribuições sem publicar outros menus. Publicar um menu nunca publica o conteúdo vinculado. source_hash rejeita traduções baseadas em texto de origem desatualizado.

O corpo das páginas e os campos richtext aceitam HTML sanitizado. Use list-page-links-tool para links estáveis /__eyivo/pages/{id}, resolvidos no idioma do visitante após a publicação. Blogs usam document JSON estruturado com media_id do mesmo site e destinos de página/post, não body_html.

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

Envio de imagens e vídeos

upload-media-tool abre um seletor de arquivos em clientes MCP Apps como Claude. ChatGPT também pode fornecer sua referência de anexo; um anexo Claude não é uma referência OpenAI. Não invente URLs nem envie arquivos base64 como argumentos.

Codex e Claude Code podem chamar prepare-media-upload-tool e enviar o arquivo multipart para upload_url com o upload_token de uso único em até cinco minutos. Mantenha o token em segredo. Clientes REST podem usar seu próprio bearer media:write. Só o envio concluído retorna o ID da mídia; emitir um ticket não envia arquivos.

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. Domínios personalizados

Solicitar um domínio

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"}'

Um recurso de domínio pendente inclui verification_token. Adicione o registo DNS necessário para comprovar a titularidade com o valor devolvido para o seu domínio, aguarde a propagação do DNS e chame o endpoint de ativação. Depois de ativo, chame o endpoint do domínio principal se quiser que se torne o nome de host público canónico.

Campos do recurso de domínio: id, domain, site_id, is_primary, status, verification_token quando aplicável e datas de criação e atualização. Os limites do plano para domínios personalizados e os erros de validação do domínio devolvem 422.

11. Erros

Resposta de validação

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

Resposta de autenticação ou autorização

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

12. Limites atuais e lista de verificação para integrações

REST v1 disponibiliza intencionalmente um subconjunto definido de funcionalidades da Eyivo. A ausência de um endpoint é um limite da interface pública, não uma autorização para chamar APIs internas.

Antes de entrar em produção

• Use HTTPS e confirme que o host esperado é app.eyivo.com.
• Mantenha os tokens Bearer no servidor e oculte os cabeçalhos de autorização nos registos.
• Solicite apenas os âmbitos necessários e, quando possível, prefira tokens pessoais restritos a um site.
• Use uma chave de idempotência única para cada operação lógica de escrita e mantenha-a nas tentativas seguintes.
• Considere 401, 403, 404 e 422 erros não transitórios, exceto se o pedido ou a credencial mudar.
• Para falhas transitórias, use uma espera exponencial com variação aleatória e respeite qualquer futuro cabeçalho Retry-After.
• Os formatos das coleções variam. Siga a paginação documentada de cada endpoint; nem todos os resultados são listas simples ou sem paginação.