Referência de endpoints

Visão geral

URL base: https://api.harumi.io/api/external/projects

Todos os endpoints precisam de uma chave de API no header Authorization. Substitua <PROJECT_ID> e <RUN_ID> pelos ids de um dos projetos da chave e de uma de suas execuções.

Encontre seus projetos

GET /api/external/projects

Os projetos que a chave pode alcançar agora, com seus ids. Projetos aos quais você perdeu o acesso ficam de fora.

curl https://api.harumi.io/api/external/projects \
  -H "Authorization: Bearer pk_..."

[{ "id": "223e4567-e89b-12d3-a456-426614174000", "name": "Routing" }]

Leia execuções

curl "https://api.harumi.io/api/external/projects/<PROJECT_ID>/runs?status=completed&limit=10" \
  -H "Authorization: Bearer pk_..."

Execução

Os endpoints de listagem e de última execução retornam objetos de execução:

Buscar uma única execução acrescenta a saída capturada:

Arquivos

O endpoint de arquivos retorna id, status, started e ended da execução, mais uma lista files:

{
  "id": "01J...",
  "status": "completed",
  "started": "2026-08-01T12:00:00Z",
  "ended": "2026-08-01T12:03:14Z",
  "files": [
    {
      "name": "results/output.csv",
      "extension": "csv",
      "size": 4021,
      "url": "https://...s3...&X-Amz-Expires=3600"
    }
  ]
}

O url de cada arquivo é um link de download pré-assinado válido por 1 hora. Se a execução não produziu arquivos de saída, files é uma lista vazia.

Inicie uma execução

POST /api/external/projects/{project_id}/runs

Enfileira uma execução do harumi.toml commitado do projeto, cobrada do criador da chave. O comando e o kernel vêm desse arquivo; não podem ser substituídos.

curl -X POST https://api.harumi.io/api/external/projects/<PROJECT_ID>/runs \
  -H "Authorization: Bearer pk_..." \
  -H "Content-Type: application/json" \
  -d '{"branch": "main"}'

Uma chamada bem-sucedida retorna 202 Accepted. Use project_run_id para acompanhar a execução com os endpoints de leitura acima:

{
  "status": "queued",
  "project_run_id": "01J...",
  "workflow_run_id": "wf_...",
  "execution_log_id": "01J..."
}

execution_log_id repete project_run_id para clientes mais antigos; use project_run_id.

Uma execução pode ser recusada antes de começar: 402 se o espaço de trabalho não tem plano ativo ou um limite foi atingido, 429 se você já tem uma execução em andamento, e 422 se o harumi.toml está ausente ou inválido nesse ref. Veja Erros.

Cancele uma execução

POST /api/external/projects/{project_id}/runs/{run_id}/cancel

Para uma execução que está na fila ou rodando e retorna a execução. Uma chave pode cancelar as execuções que o seu criador iniciou, ou qualquer execução em um projeto do qual o criador é dono. 403 caso contrário; 409 se a execução já terminou.

curl -X POST https://api.harumi.io/api/external/projects/<PROJECT_ID>/runs/<RUN_ID>/cancel \
  -H "Authorization: Bearer pk_..."