E EmDash CMS Everything Guides, use cases, plugins, templates
Português

Referência da API REST

Nesta página

O EmDash expõe uma API REST em /_emdash/api/ para gestão de conteúdo, envio de media e operações de esquema.

Autenticação

Os pedidos à API requerem autenticação via Bearer token:

Authorization: Bearer <token>

Gere tokens através da interface de administração ou programaticamente.

Formato de Resposta

Todas as respostas seguem um formato consistente:

// Sucesso
{
  "success": true,
  "data": { ... }
}

// Erro
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": { ... }
  }
}

Endpoints de Conteúdo

Listar Conteúdo

GET /_emdash/api/content/:collection

Parâmetros

ParâmetroTipoDescrição
collectionstringSlug da coleção (path)
cursorstringCursor de paginação (query)
limitnumberItens por página (query, padrão: 50)
statusstringFiltrar por status (query)
orderBystringCampo para ordenar (query)
orderstringDireção da ordenação: asc ou desc (query)

Resposta

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "type": "posts",
        "slug": "hello-world",
        "data": { "title": "Hello World", ... },
        "status": "published",
        "createdAt": "2025-01-24T12:00:00Z",
        "updatedAt": "2025-01-24T12:00:00Z"
      }
    ],
    "nextCursor": "eyJpZCI6..."
  }
}

Obter Conteúdo

GET /_emdash/api/content/:collection/:id

Resposta

{
  "success": true,
  "data": {
    "item": {
      "id": "01HXK5MZSN...",
      "type": "posts",
      "slug": "hello-world",
      "data": { "title": "Hello World", ... },
      "status": "published",
      "createdAt": "2025-01-24T12:00:00Z",
      "updatedAt": "2025-01-24T12:00:00Z"
    }
  }
}

Criar Conteúdo

POST /_emdash/api/content/:collection
Content-Type: application/json

Corpo do Pedido

{
  "data": {
    "title": "New Post",
    "content": [...]
  },
  "slug": "new-post",
  "status": "draft"
}

Resposta

{
  "success": true,
  "data": {
    "item": { ... }
  }
}

Atualizar Conteúdo

PUT /_emdash/api/content/:collection/:id
Content-Type: application/json

Corpo do Pedido

{
	"data": {
		"title": "Updated Title"
	},
	"status": "published"
}

Eliminar Conteúdo

DELETE /_emdash/api/content/:collection/:id

Resposta

{
	"success": true,
	"data": {
		"success": true
	}
}

Endpoints de Media

Listar Media

GET /_emdash/api/media

Parâmetros

ParâmetroTipoDescrição
cursorstringCursor de paginação
limitnumberItens por página (padrão: 20)
mimeTypestringFiltrar por prefixo de tipo MIME

Resposta

{
	"success": true,
	"data": {
		"items": [
			{
				"id": "01HXK5MZSN...",
				"filename": "photo.jpg",
				"mimeType": "image/jpeg",
				"size": 102400,
				"width": 1920,
				"height": 1080,
				"url": "https://cdn.example.com/photo.jpg",
				"createdAt": "2025-01-24T12:00:00Z"
			}
		],
		"nextCursor": "eyJpZCI6..."
	}
}

Obter Media

GET /_emdash/api/media/:id

Criar Media

POST /_emdash/api/media
Content-Type: application/json

Corpo do Pedido

{
	"filename": "photo.jpg",
	"mimeType": "image/jpeg",
	"size": 102400,
	"width": 1920,
	"height": 1080,
	"storageKey": "uploads/photo.jpg"
}

Atualizar Media

PUT /_emdash/api/media/:id
Content-Type: application/json

Corpo do Pedido

{
	"alt": "Photo description",
	"caption": "Photo caption"
}

Eliminar Media

DELETE /_emdash/api/media/:id

Obter Ficheiro de Media

GET /_emdash/api/media/file/:key

Serve o conteúdo do ficheiro propriamente dito. Apenas para armazenamento local.

Endpoints de Revisão

Listar Revisões

GET /_emdash/api/content/:collection/:entryId/revisions

Parâmetros

ParâmetroTipoDescrição
limitnumberMáximo de revisões a retornar (padrão: 50)

Resposta

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "collection": "posts",
        "entryId": "01HXK5MZSN...",
        "data": { ... },
        "createdAt": "2025-01-24T12:00:00Z"
      }
    ],
    "total": 5
  }
}

Obter Revisão

GET /_emdash/api/revisions/:revisionId

Restaurar Revisão

POST /_emdash/api/revisions/:revisionId/restore

Restaura o conteúdo para o estado desta revisão e cria uma nova revisão.

Endpoints de Esquema

Listar Coleções

GET /_emdash/api/schema/collections

Resposta

{
	"success": true,
	"data": {
		"items": [
			{
				"id": "01HXK5MZSN...",
				"slug": "posts",
				"label": "Posts",
				"labelSingular": "Post",
				"supports": ["drafts", "revisions", "preview"]
			}
		]
	}
}

Obter Coleção

GET /_emdash/api/schema/collections/:slug

Parâmetros

ParâmetroTipoDescrição
includeFieldsbooleanIncluir definições de campos (query)

Criar Coleção

POST /_emdash/api/schema/collections
Content-Type: application/json

Corpo do Pedido

{
	"slug": "products",
	"label": "Products",
	"labelSingular": "Product",
	"description": "Product catalog",
	"supports": ["drafts", "revisions"]
}

Atualizar Coleção

PATCH /_emdash/api/schema/collections/:slug
Content-Type: application/json

Eliminar Coleção

DELETE /_emdash/api/schema/collections/:slug

Parâmetros

ParâmetroTipoDescrição
forcebooleanEliminar mesmo que a coleção tenha conteúdo (query)

Listar Campos

GET /_emdash/api/schema/collections/:slug/fields

Criar Campo

POST /_emdash/api/schema/collections/:slug/fields
Content-Type: application/json

Corpo do Pedido

{
	"slug": "price",
	"label": "Price",
	"type": "number",
	"required": true,
	"validation": {
		"min": 0
	}
}

Atualizar Campo

PATCH /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug
Content-Type: application/json

Eliminar Campo

DELETE /_emdash/api/schema/collections/:collectionSlug/fields/:fieldSlug

Reordenar Campos

POST /_emdash/api/schema/collections/:slug/fields/reorder
Content-Type: application/json

Corpo do Pedido

{
	"fieldSlugs": ["title", "content", "author", "publishedAt"]
}

Exportação de Esquema

Exportar Esquema (JSON)

GET /_emdash/api/schema
Accept: application/json

Exportar Esquema (TypeScript)

GET /_emdash/api/schema?format=typescript
Accept: text/typescript

Retorna interfaces TypeScript para todas as coleções.

Endpoints de Plugins

Listar Plugins

GET /_emdash/api/plugins

Obter Plugin

GET /_emdash/api/plugins/:pluginId

Ativar Plugin

POST /_emdash/api/plugins/:pluginId/enable

Desativar Plugin

POST /_emdash/api/plugins/:pluginId/disable

Códigos de Erro

CódigoStatus HTTPDescrição
NOT_FOUND404Recurso não encontrado
VALIDATION_ERROR400Dados de entrada inválidos
UNAUTHORIZED401Token ausente ou inválido
FORBIDDEN403Permissões insuficientes
CONTENT_LIST_ERROR500Falha ao listar conteúdo
CONTENT_CREATE_ERROR500Falha ao criar conteúdo
CONTENT_UPDATE_ERROR500Falha ao atualizar conteúdo
CONTENT_DELETE_ERROR500Falha ao eliminar conteúdo
MEDIA_LIST_ERROR500Falha ao listar media
MEDIA_CREATE_ERROR500Falha ao criar media
SCHEMA_ERROR400Operação de esquema falhou
DUPLICATE_SLUG409O slug já existe
RESERVED_SLUG400O slug é reservado

Endpoints de Pesquisa

Pesquisa Global

GET /_emdash/api/search?q=hello+world

Parâmetros

ParâmetroTipoDescrição
qstringConsulta de pesquisa (obrigatório)
collectionsstringSlugs de coleções separados por vírgula
statusstringFiltrar por status (padrão: published)
limitnumberMáximo de resultados (padrão: 20)
cursorstringCursor de paginação

Resposta

{
  "results": [
    {
      "collection": "posts",
      "id": "01HXK5MZSN...",
      "slug": "hello-world",
      "title": "Hello World",
      "snippet": "...this is a <mark>hello</mark> <mark>world</mark> example...",
      "score": 0.95
    }
  ],
  "nextCursor": "eyJvZmZzZXQiOjIwfQ"
}

Sugestões de Pesquisa

GET /_emdash/api/search/suggest?q=hel&limit=5

Retorna títulos com correspondência de prefixo para autocompletar.

Reconstruir Índice de Pesquisa

POST /_emdash/api/search/rebuild

Reconstrói o índice FTS para todas ou coleções específicas.

Estatísticas de Pesquisa

GET /_emdash/api/search/stats

Retorna contagens de documentos indexados por coleção.

Endpoints de Secções

Listar Secções

GET /_emdash/api/sections
GET /_emdash/api/sections?source=theme
GET /_emdash/api/sections?search=newsletter

Obter Secção

GET /_emdash/api/sections/:slug

Criar Secção

POST /_emdash/api/sections
Content-Type: application/json

{
  "slug": "my-section",
  "title": "My Section",
  "keywords": ["keyword1"],
  "content": [...]
}

Atualizar Secção

PUT /_emdash/api/sections/:slug

Eliminar Secção

DELETE /_emdash/api/sections/:slug

Endpoints de Configurações

Obter Todas as Configurações

GET /_emdash/api/settings

Atualizar Configurações

POST /_emdash/api/settings
Content-Type: application/json

{
  "siteTitle": "My Site",
  "tagline": "A great site",
  "postsPerPage": 10
}

Endpoints de Menu

Listar Menus

GET /_emdash/api/menus

Obter Menu

GET /_emdash/api/menus/:name

Criar Menu

POST /_emdash/api/menus
Content-Type: application/json

{
  "name": "footer",
  "label": "Footer Navigation"
}

Atualizar Menu

PUT /_emdash/api/menus/:name

Eliminar Menu

DELETE /_emdash/api/menus/:name

Adicionar Item de Menu

POST /_emdash/api/menus/:name/items
Content-Type: application/json

{
  "type": "page",
  "referenceCollection": "pages",
  "referenceId": "page_about",
  "label": "About Us"
}

Reordenar Itens de Menu

POST /_emdash/api/menus/:name/reorder
Content-Type: application/json

{
  "items": [
    { "id": "item_1", "parentId": null, "sortOrder": 0 },
    { "id": "item_2", "parentId": null, "sortOrder": 1 },
    { "id": "item_3", "parentId": "item_2", "sortOrder": 0 }
  ]
}

Endpoints de Taxonomia

Listar Definições de Taxonomia

GET /_emdash/api/taxonomies

Criar Taxonomia

POST /_emdash/api/taxonomies
Content-Type: application/json

{
  "name": "genre",
  "label": "Genres",
  "labelSingular": "Genre",
  "hierarchical": true,
  "collections": ["books", "movies"]
}

Listar Termos

GET /_emdash/api/taxonomies/:name/terms

Criar Termo

POST /_emdash/api/taxonomies/:name/terms
Content-Type: application/json

{
  "slug": "tutorials",
  "label": "Tutorials",
  "parentId": "term_abc",
  "description": "How-to guides"
}

Atualizar Termo

PUT /_emdash/api/taxonomies/:name/terms/:slug

Eliminar Termo

DELETE /_emdash/api/taxonomies/:name/terms/:slug

Definir Termos de uma Entrada

POST /_emdash/api/content/:collection/:id/terms/:taxonomy
Content-Type: application/json

{
  "termIds": ["term_news", "term_featured"]
}

Endpoints de Áreas de Widgets

Listar Áreas de Widgets

GET /_emdash/api/widget-areas

Obter Área de Widgets

GET /_emdash/api/widget-areas/:name

Criar Área de Widgets

POST /_emdash/api/widget-areas
Content-Type: application/json

{
  "name": "sidebar",
  "label": "Main Sidebar",
  "description": "Appears on posts"
}

Eliminar Área de Widgets

DELETE /_emdash/api/widget-areas/:name

Adicionar Widget

POST /_emdash/api/widget-areas/:name/widgets
Content-Type: application/json

{
  "type": "content",
  "title": "About",
  "content": [...]
}

Atualizar Widget

PUT /_emdash/api/widget-areas/:name/widgets/:id

Eliminar Widget

DELETE /_emdash/api/widget-areas/:name/widgets/:id

Reordenar Widgets

POST /_emdash/api/widget-areas/:name/reorder
Content-Type: application/json

{
  "widgetIds": ["widget_1", "widget_2", "widget_3"]
}

Endpoints de Gestão de Utilizadores

Listar Utilizadores

GET /_emdash/api/admin/users
GET /_emdash/api/admin/users?role=40
GET /_emdash/api/admin/users?search=john

Obter Utilizador

GET /_emdash/api/admin/users/:id

Atualizar Utilizador

PATCH /_emdash/api/admin/users/:id
Content-Type: application/json

{
  "name": "John Doe",
  "role": 40
}

Ativar Utilizador

POST /_emdash/api/admin/users/:id/enable

Desativar Utilizador

POST /_emdash/api/admin/users/:id/disable

Endpoints de Autenticação

Estado da Configuração

GET /_emdash/api/setup/status

Retorna se a configuração está completa e se existem utilizadores.

Login com Passkey

POST /_emdash/api/auth/passkey/options

Obter opções de autenticação WebAuthn.

POST /_emdash/api/auth/passkey/verify
Content-Type: application/json

{
  "id": "credential-id",
  "rawId": "...",
  "response": {...},
  "type": "public-key"
}

Verificar passkey e criar sessão.

POST /_emdash/api/auth/magic-link/send
Content-Type: application/json

{
  "email": "[email protected]"
}
GET /_emdash/api/auth/magic-link/verify?token=xxx

Terminar Sessão

POST /_emdash/api/auth/logout

Utilizador Atual

GET /_emdash/api/auth/me

Convidar Utilizador

POST /_emdash/api/auth/invite
Content-Type: application/json

{
  "email": "[email protected]",
  "role": 30
}

Gestão de Passkeys

GET /_emdash/api/auth/passkey

Listar passkeys do utilizador.

POST /_emdash/api/auth/passkey/register/options
POST /_emdash/api/auth/passkey/register/verify

Registar nova passkey.

PATCH /_emdash/api/auth/passkey/:id
Content-Type: application/json

{
  "name": "MacBook Pro"
}

Renomear passkey.

DELETE /_emdash/api/auth/passkey/:id

Eliminar passkey.

Endpoints de Importação

Analisar Exportação WordPress

POST /_emdash/api/import/wordpress/analyze
Content-Type: multipart/form-data

file: <WXR file>

Executar Importação WordPress

POST /_emdash/api/import/wordpress/execute
Content-Type: application/json

{
  "analysisId": "...",
  "options": {
    "includeMedia": true,
    "includeTaxonomies": true,
    "includeMenus": true
  }
}

Limitação de Taxa

Os endpoints da API podem estar sujeitos a limitação de taxa com base na configuração de deployment. Quando limitado, as respostas incluem:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

CORS

A API suporta CORS para pedidos do navegador. Configure as origens permitidas no seu deployment.