Descripción general

La API de Ephemeral es JSON sobre HTTPS. Las ejecuciones, los flujos de trabajo, los archivos, las conexiones y los modelos los sirve el motor. En el servicio alojado, las organizaciones, los miembros, las claves y la facturación los sirve una API de organizaciones independiente.

URL base

Los ejemplos de estas páginas usan $EPHEMERAL_URL para la base del motor, sin el /v1.

Autenticación

Envía una clave de API de la organización como token bearer en cada solicitud al motor.

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

Las claves del servicio alojado empiezan por eak_; las autoalojadas empiezan por eph_. Una clave pertenece a una organización, así que nunca pasas un ID de organización al motor. Que una clave pueda llamar a un endpoint depende de su rol; consulta roles y claves. La API de organizaciones rechaza las claves de API para las acciones de gestión y exige un propietario o administrador con la sesión iniciada; consulta organizaciones.

Las aplicaciones que actúan en nombre de una persona, como los clientes MCP, pueden iniciar sesión con OAuth 2.1 en su lugar (solo en el servicio alojado): flujo de código de autorización con PKCE, registro dinámico de clientes y los ámbitos member y admin. El token de acceso (eoa_…, válido una hora) va en la misma cabecera Authorization: Bearer y actúa en la organización que eligió la persona. Descubrimiento: metadatos del servidor de autorización y metadatos del recurso protegido. Consulta MCP.

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

Solicitudes

• Envía JSON con Content-Type: application/json. La subida de archivos es la excepción y usa datos de formulario multipart.
• Los campos desconocidos se rechazan con 400, así que un campo mal escrito devuelve un error.
• Las marcas de tiempo son cadenas RFC 3339 en UTC.
• Los campos de dinero que terminan en _micros son millonésimas de dólar estadounidense, como enteros. Los campos que terminan en _cents son centavos, como enteros.

Errores

Los errores devuelven un estado HTTP y un cuerpo JSON con un mensaje legible en error.

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

Límites de uso

Las solicitudes al motor tienen un límite por minuto. Una solicitud con token de portador cuenta contra esa credencial, con 600 solicitudes por minuto. Una solicitud sin token, como GET /v1/models, cuenta contra la dirección del cliente, con 120 solicitudes por minuto. La ventana dura un minuto y se reinicia al comienzo de cada minuto.

Cada respuesta del motor, también las de error, indica cómo vas. RateLimit-Policy y RateLimit siguen el borrador de cabeceras RateLimit de la IETF (q es la cuota, w la ventana en segundos, r las solicitudes restantes y t los segundos hasta que la ventana se reinicia). X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset traen los mismos números con los nombres que muchos clientes ya leen.

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

Si superas el límite, el motor responde 429 con el error JSON habitual, el código rate_limited y una cabecera Retry-After con los segundos de espera. Espera ese tiempo en lugar de reintentar de inmediato. Seguir una ejecución con GET /v1/runs/{id}/events cuenta una vez por conexión, no por evento.

Creación idempotente de ejecuciones

Los fallos de red pueden dejarte con la duda de si se creó una ejecución. Envía una cabecera Idempotency-Key, de hasta 200 caracteres, con POST /v1/runs. Si ya existe en tu organización una ejecución con esa clave, Ephemeral la devuelve con el estado 200 en lugar de crear otra. Una ejecución nueva devuelve 202.

Paginación

GET /v1/runs pagina cuando pasas limit (de 1 a 100) o cursor. La respuesta es {"items": [...], "next_cursor": "..."}. Devuelve next_cursor como cursor para obtener la página siguiente; un next_cursor vacío significa que has llegado a la última. Los cursores son opacos y solo son válidos con el mismo filtro status. Sin limit ni cursor, la respuesta es un array simple con las 100 ejecuciones más recientes.

Versiones y retirada

La API se versiona en la ruta: todos los endpoints de aquí están bajo /v1. Dentro de una versión los cambios solo añaden: endpoints nuevos, campos opcionales nuevos en las solicitudes, campos nuevos en las respuestas y tipos de evento nuevos. Los campos existentes conservan su nombre y su significado, así que los clientes deben ignorar los campos que no conozcan.

Un cambio que rompería a los clientes existentes se publica como una versión nueva con una ruta nueva. La versión anterior sigue funcionando al menos seis meses después de publicarse la nueva. Mientras está en retirada, sus respuestas llevan una cabecera Deprecation y una cabecera Sunset con la fecha en que dejará de funcionar, y avisamos por correo a los propietarios de las organizaciones.

Referencia

La API del motor también se publica como una descripción OpenAPI 3.1 (https://app.ephemer.al/openapi.json) con el rol de clave que necesita cada operación. Los roles de clave, member y admin, figuran como scopes_supported legibles por máquina en los metadatos del recurso protegido.