Visão geral

A API do Ephemeral é JSON sobre HTTPS. Execuções, fluxos de trabalho, arquivos, conexões e modelos são atendidos pelo mecanismo. No serviço hospedado, organizações, membros, chaves e faturamento são atendidos por uma API de organizações separada.

URLs base

Os exemplos nestas páginas usam $EPHEMERAL_URL para a base do mecanismo, sem o /v1.

Autenticação

Envie uma chave de API da organização como token bearer em toda requisição ao mecanismo.

curl $EPHEMERAL_URL/v1/me \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY"

As chaves hospedadas começam com eak_; as auto-hospedadas começam com eph_. Uma chave pertence a uma organização, então você nunca passa o ID da organização ao mecanismo. Se uma chave pode chamar um endpoint depende da sua função; veja funções e chaves. A API de organizações recusa chaves de API em ações de gerenciamento e exige um proprietário ou administrador conectado; veja as organizações.

Aplicativos que agem em nome de uma pessoa, como clientes MCP, podem entrar com OAuth 2.1 (somente no serviço hospedado): fluxo de código de autorização com PKCE, registro dinâmico de clientes e os escopos member e admin. O token de acesso (eoa_…, válido por uma hora) vai no mesmo cabeçalho Authorization: Bearer e age na organização que a pessoa escolheu. Descoberta: metadados do servidor de autorização e metadados do recurso protegido. Veja MCP.

{
  "organization_id": "org_5e2b8c91d4a7f03e6b1c9d2a8f4e7b10",
  "role": "member",
  "mode": "hosted",
  "compute_micros_per_second": 200,
  "default_max_cost_micros": 500000
}

Requisições

• Envie JSON com Content-Type: application/json. O envio de arquivos é a exceção e usa multipart form data.
• Campos desconhecidos são rejeitados com 400, então um campo escrito errado retorna um erro.
• Os carimbos de data e hora são strings RFC 3339 em UTC.
• Os campos de valor terminados em _micros são milionésimos inteiros de um dólar americano. Os campos terminados em _cents são centavos inteiros.

Erros

Os erros retornam um status HTTP e um corpo JSON com uma mensagem legível em error.

{ "error": "timeout_seconds must be between 1 and 3600", "code": "invalid_request" }

Limites de taxa

As requisições ao motor têm um limite por minuto. Uma requisição com token bearer conta contra essa credencial, com 600 requisições por minuto. Uma requisição sem token, como GET /v1/models, conta contra o endereço do cliente, com 120 requisições por minuto. A janela dura um minuto e recomeça no início de cada minuto.

Toda resposta do motor, inclusive as de erro, mostra a sua situação. RateLimit-Policy e RateLimit seguem o rascunho da IETF para cabeçalhos RateLimit (q é a cota, w a janela em segundos, r as requisições restantes e t os segundos até a janela reiniciar). X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset trazem os mesmos números com os nomes que muitos clientes já leem.

RateLimit-Policy: "default";q=600;w=60
RateLimit: "default";r=598;t=41
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 41

Ao passar do limite, o motor responde 429 com o erro JSON de sempre, o código rate_limited e um cabeçalho Retry-After com os segundos de espera. Aguarde esse tempo em vez de tentar de novo na hora. Acompanhar uma execução com GET /v1/runs/{id}/events conta uma vez por conexão, não por evento.

Criação idempotente de execuções

Falhas de rede podem deixar você sem saber se uma execução foi criada. Envie um cabeçalho Idempotency-Key, de até 200 caracteres, com POST /v1/runs. Se já existir uma execução com essa chave na sua organização, o Ephemeral a retorna com o status 200 em vez de criar outra. Uma nova execução retorna 202.

Paginação

GET /v1/runs pagina quando você passa limit (de 1 a 100) ou cursor. A resposta é {"items": [...], "next_cursor": "..."}. Passe next_cursor de volta como cursor para obter a próxima página; um next_cursor vazio significa que você chegou à última. Os cursores são opacos e só valem com o mesmo filtro status. Sem limit ou cursor, a resposta é um array simples com as 100 execuções mais recentes.

Versões e descontinuação

A API é versionada no caminho: todos os endpoints aqui ficam em /v1. Dentro de uma versão, as mudanças só acrescentam: novos endpoints, novos campos opcionais de requisição, novos campos de resposta e novos tipos de evento. Os campos existentes mantêm nome e significado, então os clientes devem ignorar campos que não conhecem.

Uma mudança que quebraria clientes existentes sai como uma nova versão em um novo caminho. A versão anterior continua funcionando por pelo menos seis meses depois da publicação da nova. Enquanto estiver descontinuada, as respostas trazem um cabeçalho Deprecation e um cabeçalho Sunset com a data em que ela para de funcionar, e os donos das organizações são avisados por e-mail.

Referência

A API do mecanismo também é publicada como uma descrição OpenAPI 3.1 (https://app.ephemer.al/openapi.json) com o papel de chave que cada operação exige. Os papéis de chave, member e admin, constam como scopes_supported, legível por máquina, nos metadados do recurso protegido.