API Harumi

Leia as execuções e saídas dos seus projetos, e inicie ou cancele execuções, a partir dos seus próprios sistemas usando uma chave de API.

Visão geral

A API Harumi permite que um sistema seu trabalhe com os seus projetos sem que uma pessoa precise entrar: um job agendado que traz os resultados mais recentes para um dashboard, um pipeline que inicia uma execução quando chegam dados novos, ou um serviço que espera uma execução terminar e então baixa seus arquivos.

Você se autentica com uma chave de API que você cria na plataforma. Cada chave alcança só os projetos que você escolher, só faz o que você permitir, e nunca faz mais do que você mesmo pode fazer.

Procurando acesso interativo?

Esta API é para sistemas chamando com uma chave estática. Se você é um usuário da plataforma executando código e buscando seus próprios resultados, use a CLI harumi — ela autentica como você e não tem relação com as chaves de API descritas aqui. As chaves dos seus próprios modelos de IA (OpenAI, Anthropic) são outra coisa, em Configurações → Seus modelos.

Crie uma chave

Ative a autenticação em duas etapas. Criar, editar e rotacionar uma chave pede um código do seu aplicativo autenticador. Em Configurações → Minha Conta, abra Autenticação em duas etapas e clique em Ativar. Se você pular isso, a Harumi guia você na primeira vez que criar uma chave.

Abra Configurações → Chaves de API e clique em Criar chave de API.

Dê um Nome à chave, marque as Permissões, escolha o Espaço de trabalho, marque os Projetos que ela pode alcançar e escolha quando ela Expira.

Clique em Criar chave e copie a chave. Ela é mostrada uma única vez: não pode ser recuperada de novo, apenas rotacionada.

De volta à aba Chaves de API, cada chave mostra seus projetos, permissões, validade e quando foi usada pela última vez. Você pode alterar uma chave a qualquer momento:

Editar o nome, as permissões e os projetos. O segredo, a validade e o espaço de trabalho continuam os mesmos.
Rotacionar para obter um novo segredo. O antigo para de funcionar imediatamente, então atualize tudo o que o usa.
Revogar para encerrar o acesso da chave de vez.

O que uma chave pode fazer

Uma chave tem uma ou mais permissões:

Permissão	Permite que a chave	Endpoints
Ler saídas de execuções	Liste execuções, leia o status e os logs de uma execução e baixe seus arquivos de saída.	Endpoints `GET`
Iniciar e cancelar execuções	Inicie uma execução do `harumi.toml` commitado do projeto em uma branch, e cancele uma execução em andamento.	Endpoints `POST`

Toda chave também lista os projetos que alcança, todos em um único espaço de trabalho: uma organização, ou os seus projetos pessoais. Uma chave pode alcançar até 50 projetos, e você pode ter até 25 chaves ativas.

Uma chave age como você

Uma chave é você, sem navegador. Isso define seus limites:

Ela nunca excede o seu acesso. Se você perder o acesso a um projeto — sair da organização, virar visualizador, ou o projeto for excluído — a chave para de funcionar nele, sem precisar encontrá-la e revogá-la.
As execuções são cobradas de você e contam para o seu plano como as que você inicia por conta própria. Um espaço de trabalho sem plano ativo é somente leitura, então suas chaves podem ler, mas não iniciar execuções.
Uma execução por vez. O limite de uma execução em andamento por pessoa vale para a plataforma e a API juntas.
Uma execução usa o harumi.toml como commitado. Uma chave não pode substituir o comando nem o kernel, então só executa o que o projeto já manda executar.

Autenticação

Toda requisição precisa de um header Authorization com uma chave prefixada com pk_:

Authorization: Bearer pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requisições sem esse header, com um valor malformado, ou com uma chave desconhecida, expirada ou revogada recebem 401 Unauthorized. As chaves expiram — 30, 90, 180 ou 365 dias depois de criadas — então rotacione uma chave antes da data.

Limites

Os limites valem por chave, não por endereço IP.

Requisições	Limite
Leituras (`GET`)	120 por minuto
Iniciar ou cancelar uma execução (`POST`)	20 por minuto

Passar de um limite retorna 429 Too Many Requests.

Mantendo as chaves seguras

Guarde uma chave como uma senha: no cofre de segredos do seu sistema, nunca no código nem em um repositório.
Dê a cada integração a sua própria chave, só com as permissões e os projetos de que ela precisa. Assim, uma chave vazada custa uma integração, não tudo.
Se uma chave vazar, Revogue em Configurações → Chaves de API. Revogar não pede autenticação em duas etapas, então está sempre a um clique.

Erros

Status	Significado
`401`	Chave ausente, malformada, desconhecida, expirada ou revogada.
`402`	O espaço de trabalho não tem plano ativo, ou um limite do plano foi atingido.
`403`	A chave não tem a permissão que o endpoint exige.
`404`	O projeto ou a execução não existe, não é um dos projetos da chave, ou você não tem mais acesso a ele. Os casos são indistinguíveis de propósito.
`409`	O projeto ainda não tem repositório.
`422`	O `harumi.toml` está ausente ou inválido nessa branch ou commit.
`429`	Requisições demais, ou você já tem uma execução em andamento.
`500`	Erro ao ler arquivos do armazenamento.

Veja a referência de endpoints para cada requisição e resposta.

On this page