API do Origami

A linha de produção, programável

Tudo o que o workspace faz — enviar, avaliar, aprimorar, baixar — controlado a partir dos seus próprios sistemas com uma API JSON simples.

O ciclo

A API reflete o workspace: quatro etapas, repetidas por livro.

Enviar

Você declara o arquivo, faz PUT dos bytes para uma URL pré-assinada e registra a publicação. Os arquivos nunca passam pela API.

Rodar

Você inicia qualquer ferramenta contra a versão de trabalho da publicação. A resposta é um run que você consulta — as ferramentas síncronas terminam na primeira consulta.

Ler

Você obtém o relatório JSON do run: constatações, pontuações, metadados ou a descrição para a página da publicação.

Baixar

As reparações e edições adicionam novas versões do arquivo. Você baixa a versão de trabalho com um link de curta duração.

Autenticação

Cada request carrega uma chave de API de workspace como token Bearer. A chave está atrelada a um workspace: tudo o que você cria e lê com ela vive ali, exatamente como se estivesse trabalhando no app.

As chaves são emitidas por workspace e exibidas uma única vez. O gerenciamento self-service chega em breve às configurações do workspace; enquanto isso, peça sua chave ao seu contato na publica.la.

curl https://origami.publica.la/api/v1/publications \
  -H "Authorization: Bearer ${ORIGAMI_API_KEY}" \
  -H "Accept: application/json"

Início rápido

Seis requests levam um livro do seu disco a um relatório de validação, ida e volta. Substitua o token e o nome do arquivo; o resto é copiar e colar.

1 · Peça um local de upload

curl -X POST https://origami.publica.la/api/v1/uploads \
  -H "Authorization: Bearer ${ORIGAMI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"original_filename": "book.epub", "size_bytes": 4180294}'

2 · PUT dos bytes para a URL pré-assinada

curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: application/epub+zip" \
  --data-binary @book.epub

3 · Registre a publicação

curl -X POST https://origami.publica.la/api/v1/publications \
  -H "Authorization: Bearer ${ORIGAMI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"publication_id": "ID_FROM_STEP_1", "key": "KEY_FROM_STEP_1", "original_filename": "book.epub", "size_bytes": 4180294}'

4 · Rode uma ferramenta

curl -X POST https://origami.publica.la/api/v1/publications/PUBLICATION_ID/runs \
  -H "Authorization: Bearer ${ORIGAMI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"tool": "epub-check"}'

5 · Consulte o run e leia o relatório

curl https://origami.publica.la/api/v1/runs/RUN_ID \
  -H "Authorization: Bearer ${ORIGAMI_API_KEY}"

curl https://origami.publica.la/api/v1/runs/RUN_ID/report \
  -H "Authorization: Bearer ${ORIGAMI_API_KEY}"

6 · Baixe a versão de trabalho

curl https://origami.publica.la/api/v1/publications/PUBLICATION_ID/files/current \
  -H "Authorization: Bearer ${ORIGAMI_API_KEY}"

curl -L -o book-improved.epub \
  https://origami.publica.la/api/v1/files/FILE_ID/download \
  -H "Authorization: Bearer ${ORIGAMI_API_KEY}"

Endpoints

Todos os endpoints vivem sob /api/v1, falam JSON e respondem erros como {error, reason, detail} com um reason estável para máquinas.

Publicações e uploads

GET /api/v1/tools

O catálogo de ferramentas que a API expõe, com seus flags de medição.

POST /api/v1/uploads

Gera um PUT pré-assinado para um arquivo novo (30 minutos).

POST /api/v1/publications

Registra um objeto enviado como publicação.

GET /api/v1/publications

Lista as publicações do workspace (paginação por cursor).

GET /api/v1/publications/{id}

Uma publicação: tipo, estado, título, arquivo de trabalho.

Versões de arquivo

GET /api/v1/publications/{id}/files

O histórico completo de versões: o original imutável mais cada cópia aprimorada.

GET /api/v1/publications/{id}/files/current

A versão de trabalho — sobre a qual a próxima ferramenta atua.

GET /api/v1/files/{id}/download

302 para um link de download de curta duração de qualquer versão.

Execuções de ferramentas

POST /api/v1/publications/{id}/runs

Inicia uma execução (202). Aceita um objeto options e um header Idempotency-Key.

GET /api/v1/publications/{id}/runs

Lista os runs de uma publicação, filtráveis por ferramenta.

GET /api/v1/runs/{id}

Estado, tempos e detalhe de erro do run.

GET /api/v1/runs/{id}/report

O relatório JSON do run concluído.

Convenções

Assíncrono por padrão

Os runs respondem 202 com um recurso que você consulta. Um run é terminal em succeeded, failed ou rejected.

Idempotência

Envie um header Idempotency-Key no POST /runs; uma nova tentativa devolve o run original em vez de gastar duas vezes.

Paginação

As listas respondem {data, next_cursor, has_more}; passe next_cursor como ?cursor= até que has_more seja false.

Limites

Os requests são limitados por chave. As ferramentas medidas compartilham a cota diária de uso justo do seu workspace — um 429 com reason daily_limit_reached significa tentar novamente amanhã, e os uploads consomem a cota de publicações do plano.

Descrições

A ferramenta de descrições devolve o texto para a página da publicação: um único estilo (back_cover) com uma versão longa para o corpo e uma curta para cards e metadados.

Os arquivos vão direto

Os uploads são PUTs pré-assinados e os downloads GETs pré-assinados contra o storage — a API nunca faz proxy dos bytes, então as transferências são rápidas em qualquer tamanho.

Construindo uma integração?

Conte para nós o que você está automatizando — ingestão em massa, um hook do seu DAM, um pipeline de preflight — e ajudamos você a conectar.

Vamos conversar