Referência da API REST

EmDash expõe a sua interface de programação de aplicações (API) suportada em /_emdash/api/. Use o documento OpenAPI 3.1 gerado para parâmetros de pedido, corpos, esquemas de resposta, códigos de estado e geração de clientes:

GET /_emdash/api/openapi.json

O documento é gerado a partir dos mesmos esquemas Zod usados pela API. Também reflete o tamanho máximo configurado para carregamento de media.

Limite do contrato público

O documento OpenAPI delimita a API REST suportada. O EmDash também tem rotas para a interface de administração e fluxos de protocolo. Uma rota presente no código-fonte mas ausente do OpenAPI não é uma operação REST suportada para clientes externos.

Esta distinção aplica-se a rotas de backup, administração de bylines, travessia de relações, gestão de plugins, configuração, importação e autenticação. Use o guia de backups para backups e as ferramentas MCP de bylines para gestão de bylines suportada. Os endpoints OAuth são endpoints de protocolo; descubra-os a partir dos metadados descritos na secção OAuth do MCP em vez de os tratar como endpoints REST de aplicação.

Autenticação e autorização

A maioria das operações aceita um cookie de sessão EmDash ou um token Bearer. Envie um personal access token ou um OAuth access token no cabeçalho Authorization:

Authorization: Bearer $EMDASH_TOKEN

Os tokens Bearer são limitados pelos respetivos scopes e pelo papel do utilizador associado. Pedidos com sessão usam o papel do utilizador. Consulte papéis de utilizador e scopes de token para o modelo de autorização.

GET e POST /_emdash/api/comments/{collection}/{contentId} são públicos. A operação GET devolve comentários aprovados; a operação POST submete um comentário para moderação. As restantes operações de moderação de comentários exigem autenticação.

Proteção contra falsificação de pedidos entre sites

Para um pedido que altera o estado autenticado com cookie de sessão, inclua este cabeçalho:

X-EmDash-Request: 1

Pedidos com token Bearer não exigem o cabeçalho porque não usam credenciais implícitas do browser. Pedidos do browser a uma operação de escrita pública devem enviar o cabeçalho ou ter um Origin que corresponda à origem pública ou de pedido do site EmDash.

Envelopes de resposta

Uma resposta JSON bem-sucedida define success como true e coloca o resultado específico da operação em data:

{
	"success": true,
	"data": {
		"items": []
	}
}

Em caso de erro, success é false e inclui um código estável legível por máquina e uma mensagem. Alguns erros incluem também details estruturados:

{
	"success": false,
	"error": {
		"code": "NOT_FOUND",
		"message": "Content item not found"
	}
}

Use os códigos de estado e esquemas de erro de cada operação OpenAPI. Estados comuns são 400 para entrada inválida, 401 para credenciais em falta ou inválidas, 403 por scope ou permissão insuficiente, 404 para recurso inexistente, 409 por conflito de estado, 413 por carregamento demasiado grande, 422 quando um plugin rejeita o guardar e 500 por falha interna.

Inventário de endpoints

O ID de operação é estável no contrato gerado e é frequentemente usado como nome de método pelos geradores de clientes OpenAPI. O inventário seguinte é verificado contra o documento OpenAPI gerado.

Conteúdo

Media

Schema

Comentários

Taxonomias

Menu

Secções

Widgets

Definições

Pesquisa

Redirecionamentos

Utilizadores

Transferência

Ciclo de vida do conteúdo e bylines

A referência do ciclo de vida do conteúdo define estado, revisão, permissões, conflitos e comportamento de hooks partilhados por REST, MCP, CLI e painel de administração.

Leituras de conteúdo devolvem um token _rev opaco quando disponível. Envie _rev com PUT /content/{collection}/{id} para evitar sobrescrever uma alteração feita desde a leitura. Um token obsoleto produz conflito; volte a ler a entrada antes de repetir. A CLI torna esta verificação obrigatória para content update, enquanto o campo REST permanece opcional para clientes que escolhem deliberadamente uma escrita incondicional.

Ler e atualizar uma entrada

Leia a entrada antes de a alterar:

GET /_emdash/api/content/articles/01JARTICLE0000000000000000
Authorization: Bearer $EMDASH_TOKEN

A resposta contém os campos, o estado de publicação e o token de revisão:

{
	"success": true,
	"data": {
		"item": {
			"id": "01JARTICLE0000000000000000",
			"type": "articles",
			"slug": "launch-notes",
			"status": "published",
			"data": { "title": "Launch notes" }
		},
		"_rev": "opaque-revision-token"
	}
}

Envie apenas os campos a alterar, juntamente com o token obtido nessa leitura:

PUT /_emdash/api/content/articles/01JARTICLE0000000000000000
Authorization: Bearer $EMDASH_TOKEN
Content-Type: application/json

{
	"data": { "title": "Updated launch notes" },
	"_rev": "opaque-revision-token"
}

Alterar uma entrada publicada cria um rascunho enquanto a versão anterior permanece online. Use a operação de comparação para rever ambas as versões e depois publique o rascunho ou descarte-o. Anular a publicação mantém o conteúdo e a data de publicação, cancela agendamentos pendentes e remove a entrada do site em produção.

Corpos de criação e atualização aceitam créditos de byline; respostas de conteúdo incluem a byline principal e créditos ordenados. A listagem de conteúdo pode filtrar por IDs de byline guardados e incluir opcionalmente a byline inferida de um autor. Criar e gerir os registos de byline faz-se através das ferramentas MCP de bylines, não do contrato REST público.

As operações do ciclo de vida distinguem eliminação soft de eliminação permanente. Restaurar devolve conteúdo no lixo como rascunho sem agendamento; eliminação permanente remove uma entrada no lixo e não pode ser revertida. Publicar, anular publicação, agendar, cancelar agendamento, comparar, descartar rascunho e duplicar são operações separadas para os clientes pedirem uma transição de estado de cada vez.

Bloqueio de edição de entradas

As collections podem obter um bloqueio de edição de sete minutos quando um editor abre uma entrada. Use as três operações em /content/{collection}/{id}/lock para ler, obter ou renovar e libertar o lease.

Uma resposta de leitura ou aquisição indica se o bloqueio está ativo, se o chamador detém o lease e quem o detém atualmente:

{
	"success": true,
	"data": {
		"enabled": true,
		"heldByCaller": false,
		"holder": {
			"userId": "01JUSER000000000000000000",
			"userName": "Ada",
			"acquiredAt": "2026-05-01T09:12:04.117Z",
			"expiresAt": "2026-05-01T09:19:04.117Z"
		}
	}
}

Se uma collection tiver o bloqueio de edição desativado, enabled é false e nenhum lease é obtido. Voltar a obter o mesmo bloqueio e guardar a entrada prolongam ambos um lease detido pelo chamador.

O corpo de aquisição pode incluir um token opaco que identifica uma sessão de edição e takeover: true quando o utilizador escolhe substituir o lease de outro editor. Passe o mesmo token como parâmetro de consulta ao libertar o bloqueio. Um segundo separador da mesma conta não pode libertar por engano o lease do primeiro.

Quando outro utilizador detém o lease, escritas protegidas de conteúdo devolvem 409 ENTRY_LOCKED. Os detalhes do erro identificam o detentor e a expiração. Para ignorar o bloqueio, envie "overrideLock": true no corpo JSON de uma escrita com corpo, ou ?overrideLock=true para uma operação DELETE sem corpo.

Seleções de referência

Um campo reference liga uma entrada a entradas noutra collection através de uma relação. O seu valor não faz parte de data e é indexado por grupo de tradução, pelo que cada tradução de uma entrada partilha uma seleção.

Corpos de criação e atualização transportam seleções em references, indexadas por slug do campo, cada uma um array de no máximo 1000 IDs de entrada por ordem de apresentação. O EmDash escreve a seleção na mesma transação que a entrada. A atualização seguinte substitui o autor da entrada:

PUT /_emdash/api/content/articles/01JARTICLE0000000000000000
Authorization: Bearer $EMDASH_TOKEN
Content-Type: application/json

{
	"data": { "title": "Updated launch notes" },
	"references": { "author": ["01JAUTHOR00000000000000000"] },
	"_rev": "opaque-revision-token"
}

Um campo ligado à extremidade filho da relação seleciona as entradas que apontam para a que está a ser escrita, sem ordem própria. Os limites da relação aplicam-se em ambas as extremidades; uma seleção que daria a uma entrada ligada mais pais do que a relação permite é rejeitada tal como uma que liga demasiadas entradas.

Numa collection com revisões, uma seleção alterada numa entrada publicada fica em rascunho com as outras alterações pendentes. Torna-se live na publicação e é descartada com o rascunho. Publicar reverifica a seleção completa face aos limites da relação.

Uma leitura de entrada única devolve references indexadas por slug do campo. Cada campo contém a primeira página das entradas ligadas, 50 elementos, com nextCursor quando há mais, e reporta ID, slug, collection, título de apresentação, locale resolvido e grupo de tradução de cada entrada. Um chamador autorizado a ler rascunhos vê uma seleção em staging quando o rascunho inclui uma. A operação de listagem de conteúdo não inclui referências.

Definições de relação e travessia de ligações são rotas de administração, ausentes do OpenAPI e fora do contrato público. Escreva e leia seleções através das operações de conteúdo acima e renderize-as no site com getEmDashEntry() e getEmDashReferences().

Traduções

O contrato REST público expõe traduções de conteúdo e definições de taxonomia. A criação de conteúdo aceita translationOf; a criação de taxonomia usa o mesmo campo para adicionar uma variante de locale. As operações content-term devolvem atribuições sensíveis ao locale.

GET /taxonomies/{name} devolve a definição do locale predefinido do site quando locale é omitido, recorrendo ao código de locale mais baixo apenas quando o predefinido não tem definição. Uma atualização comporta-se de forma diferente: sem locale, altera a definição com o código de locale mais baixo. Passe locale para que uma atualização de taxonomia traduzida atinja a definição pretendida. Se esse locale não tiver definição, a atualização devolve NOT_FOUND em vez de recorrer a outro locale. A operação translations devolve cada definição no grupo partilhado e os IDs aceites por translationOf.

label e labelSingular pertencem à definição de um locale. hierarchical e collections pertencem à taxonomia: cada locale devolve os mesmos valores e uma atualização que envia um deles altera-o para todos os locales. Criar uma definição para um nome que já existe noutro locale adiciona-a a essa taxonomia, quer o pedido envie translationOf ou não. A nova definição herda hierarchical e collections da taxonomia; uma criação com valores diferentes devolve VALIDATION_ERROR.

Eliminar uma taxonomia remove cada locale da sua definição, todos os termos e todas as atribuições desses termos ao conteúdo. Não elimina as entradas de conteúdo.

A operação de reordenação de termos altera um grupo de irmãos. O array ids pode conter apenas parte desse grupo; termos listados trocam as posições existentes e os omitidos permanecem. Por exemplo, reordenar [A, B, C] com ids: ["C", "A"] produz [C, B, A]. A reordenação não altera relações de pai; uma ordem de termos aplica-se a cada locale no seu grupo de tradução.

Rotas de tradução de menus, termos de taxonomia e bylines não estão no contrato REST público. As listagens suportadas estão disponíveis através de menu_translations, taxonomy_term_translations e byline_translations no servidor MCP.

Endpoints de media

As operações de media cobrem listagem, carregamento, atualização de metadados, substituição de imagem, pastas, informação de utilização e manutenção do índice de utilização. O guia da biblioteca de media explica o fluxo orientado ao utilizador e o significado da cobertura de utilização.

Listar e inspecionar media

GET /media suporta paginação por cursor ou por páginas numeradas, filtros de tipo MIME e nome de ficheiro, pastas e resumos de utilização opcionais. Omita folderId para incluir todas as pastas ou passe folderId=unfiled para obter apenas a biblioteca principal. Defina includeUsage=1 numa listagem ou leitura individual para incluir informação de utilização; qualquer outro valor é inválido.

usage.count conta linhas de conteúdo ativas distintas ou locales cuja fonte indexada atual referencia o media, mais cada definição do site que o seleciona (logo, favicon, seo.defaultOgImage). Referências repetidas numa entrada contam uma vez; entradas no lixo não contam. O número só é visível para chamadores que podem ler rascunhos; outros leitores de media autorizados recebem count: null porque a contagem poderia revelar conteúdo em rascunho.

GET /media/{id}/usage devolve as entradas de conteúdo que referenciam o media, paginadas. Cada página inclui também siteSettings, as definições do site que selecionam o media, por exemplo [{ "setting": "favicon" }]. As definições do site são lidas das definições guardadas em cada pedido e não dependem da indexação de utilização.

Cada resultado de utilização inclui um estado de cobertura:

Apenas com complete se pode tratar uma contagem zero como completa nos tipos de campo indexados. As contagens são indicativas durante escritas concorrentes; não bloqueiam o media nem garantem que a eliminação é segura. A indexação de utilização cobre campos de imagem e ficheiro, campos repeater de imagem, blocos de imagem e galeria Portable Text e media declarados por versões de bloco retidas em collections EmDash. Também são reportados logo do site, favicon e imagem social predefinida. A utilização não inclui blocos Portable Text personalizados, código de aplicação, HTML renderizado, outras definições, menus, widgets, dados de plugins, sites externos ou assets exclusivos do fornecedor.

Carregamento multipart direto

Envie um ficheiro através do EmDash publicando-o como campo file de um pedido multipart:

curl --request POST \
	--header "Authorization: Bearer $EMDASH_TOKEN" \
	--form "file=@./cover.jpg;type=image/jpeg" \
	https://example.com/_emdash/api/media

curl adiciona o boundary multipart. Não defina manualmente o cabeçalho Content-Type. O esquema OpenAPI MediaDirectUploadBody lista os campos de metadados opcionais e os esquemas de resposta distinguem um novo carregamento de um item existente deduplicado.

O corpo multipart pode incluir também width e height da imagem, um fieldId cuja allowlist de tipos MIME deve ser aplicada e uma thumbnail reduzida usada como placeholder de baixa qualidade. Um ficheiro novo devolve 201 Created e fica imediatamente pronto. Bytes idênticos devolvem o media existente com 200 OK e deduplicated: true.

Fluxo de destino de carregamento

Use o fluxo de destino de carregamento quando o cliente pode carregar diretamente para armazenamento compatível com S3. O media permanece pending e não aparece na biblioteca padrão até a confirmação ter sucesso.

Armazenamento local e R2 nativo devolvem um destino de carregamento EmDash same-origin. Armazenamento compatível com S3 pode devolver um URL externo assinado. Itens pending ficam fora da lista de media padrão até a confirmação ter sucesso.

Erros de carregamento

Os seguintes erros exigem uma ação de recuperação diferente:

Pastas de media

Nomes de pastas são trimados, limitados a 200 caracteres e comparados após normalização Unicode e minúsculas. Nomes como Photos, photos e ＰＨＯＴＯＳ entram por isso em conflito. Eliminar uma pasta devolve o media à biblioteca principal; não elimina media, não altera IDs ou URLs de media nem registos de utilização.

Reparar utilização de media

Ativação, progresso, filas de trabalho, limpeza de eliminações e reparação de utilização de media são operações de operador em /_emdash/api/admin/media-usage/. Utilizadores com sessão precisam de schema:manage; tokens Bearer também precisam do scope admin.

Se o rastreamento estiver desligado, pause escritores diretos da base de dados antes da ativação. O EmDash bloqueia temporariamente escritas de conteúdo e esquema enviadas pelas suas APIs durante a configuração, mas não pode parar outro processo que escreve diretamente na base de dados.

Se um pedido de escrita expirar ou devolver 409 ou 500, leia o estado de ativação e progresso antes de repetir. Lotes concluídos permanecem registados. Quando lastErrorCode estiver definido, mantenha escritores diretos parados, resolva o problema reportado e envie uma repetição confirmada. A ativação não pode ser cancelada nem reposta após arrancar: teste este procedimento numa cópia de staging e mantenha um backup atual da base de dados.

As operações de listagem de trabalho expõem indexações de entradas falhadas ou atrasadas sem devolver conteúdo, referências de media, tokens de lease, erros brutos da base de dados ou uma contagem exata de backlog. Repetir um item é idempotente. 409 WORK_LEASE_ACTIVE significa que um worker ainda processa o item; a resposta inclui details.leaseExpiresAt: aguarde até esse momento e leia novamente antes de repetir. 409 WORK_CHANGED significa que outro pedido alterou o item de trabalho; leia o estado atual em vez de sobrescrever o trabalho mais recente.

A operação de reparação aceita { "scope": "collection", "collection": "articles" } ou { "scope": "all" }. Uma reparação em todas as collections corre de forma síncrona e sequencial e pode demorar muito em sites grandes. Uma resposta 200 pode ainda reportar partial, failed ou stale; inspecione data.status, o estado por collection e as contagens de origem antes de considerar a reparação concluída.

Transferência de site

As operações de transferência em /_emdash/api/admin/transfer/ exportam um site como pacote de site e importam um para um site vazio. O guia de transferência de site descreve exportação, carregamento, análise, execução e fluxo de recibo.

Utilizadores com sessão precisam da permissão transfer:export ou transfer:import, que só administradores têm. Tokens Bearer precisam de admin ou do scope transfer:export, transfer:analyze ou transfer:execute indicado por cada operação. As operações de aprovação aceitam apenas sessões autenticadas. Decidem pedidos feitos pelas ferramentas MCP site_export_start e site_import_start; as operações REST de exportação e execução não exigem aprovação.

Enquanto uma importação está a executar, e após falha ou cancelamento até ser abandonada, a maioria das outras operações de escrita devolve 503 TRANSFER_IMPORT_IN_PROGRESS. O guia lista as operações que permanecem disponíveis.

Paginação

Operações de listagem descrevem os parâmetros de paginação no OpenAPI. A maioria das operações com paginação por cursor aceita um cursor opaco e um limit de 1 a 100, predefinido 50. Devolva o nextCursor da resposta anterior inalterado; não o analise nem o construa. Algumas operações de media também suportam páginas numeradas e algumas listas especializadas usam limites diferentes: clientes gerados devem seguir o esquema de cada operação.

Tokenizers de pesquisa

A operação de ativação de pesquisa guarda um tokenizer para cada collection. Alterá-lo numa collection com pesquisa ativa reconstrói o índice dessa collection.

Desativar a pesquisa preserva o tokenizer guardado para a próxima ativação. A operação de rebuild usa o tokenizer guardado da collection e os pesos dos campos.

Comentários e redirecionamentos

Submissões públicas de comentários entram na fila de moderação. Operações admin de comentários listam todos os estados, devolvem contagens, atualizam um estado, moderam em massa e eliminam permanentemente um comentário. Uma resposta 429 significa que o limite de taxa de submissão foi atingido.

Operações de redirecionamento gerem regras de redirecionamento e o registo 404 separadamente. A poda remove entradas selecionadas pelo corpo do pedido, enquanto DELETE /redirects/404s limpa o registo inteiro. Nenhuma das operações elimina regras de redirecionamento.