개요

Ephemeral API는 HTTPS 위에서 JSON을 주고받습니다. 실행, 워크플로, 파일, 연결, 모델은 엔진이 제공합니다. 호스팅 서비스에서는 조직, 멤버, 키, 결제를 별도의 조직 API가 제공합니다.

기본 URL

이 문서의 예제에서는 /v1을 뺀 엔진 기본 URL을 $EPHEMERAL_URL로 나타냅니다.

인증

모든 엔진 요청에 조직 API 키를 Bearer 토큰으로 보냅니다.

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

호스팅 키는 eak_로, 셀프 호스팅 키는 eph_로 시작합니다. 키는 하나의 조직에 속하므로 엔진에 조직 ID를 전달할 필요가 없습니다. 키로 엔드포인트를 호출할 수 있는지는 키의 역할에 따라 달라지며, 역할과 키를 참고하세요. 조직 API는 관리 작업에서 API 키를 거부하고 로그인한 소유자나 관리자를 요구합니다. 조직을 참고하세요.

사람을 대신해 동작하는 애플리케이션(예: MCP 클라이언트)은 대신 OAuth 2.1로 로그인할 수 있습니다(호스팅 서비스 전용). PKCE를 사용하는 인증 코드 흐름, 동적 클라이언트 등록, 스코프 member와 admin을 지원합니다. 액세스 토큰(eoa_…, 유효 기간 1시간)은 같은 Authorization: Bearer 헤더로 보내며, 사용자가 선택한 조직에서 동작합니다. 디스커버리: 인증 서버 메타데이터와 보호 리소스 메타데이터. 자세한 내용은 MCP를 참고하세요.

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

요청

• JSON은 Content-Type: application/json과 함께 보냅니다. 파일 업로드는 예외로, multipart 폼 데이터를 사용합니다.
• 알 수 없는 필드는 400으로 거부되므로, 필드 이름을 잘못 쓰면 오류가 반환됩니다.
• 타임스탬프는 UTC 기준 RFC 3339 문자열입니다.
• _micros로 끝나는 금액 필드는 미국 달러의 100만분의 1을 정수로 나타낸 값입니다. _cents로 끝나는 필드는 센트 단위 정수입니다.

오류

오류는 HTTP 상태와, error에 읽을 수 있는 메시지가 담긴 JSON 본문으로 반환됩니다.

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

속도 제한

엔진 요청에는 분당 한도가 있습니다. 베어러 토큰이 있는 요청은 해당 자격 증명 기준으로 집계되며 분당 600건까지 허용됩니다. GET /v1/models처럼 토큰이 없는 요청은 클라이언트 주소 기준으로 집계되며 분당 120건까지 허용됩니다. 윈도우는 1분이고 매분 시작 시점에 초기화됩니다.

오류를 포함한 모든 엔진 응답에 현재 상태가 표시됩니다. RateLimit-Policy와 RateLimit는 IETF RateLimit 헤더 초안을 따릅니다(q는 한도, w는 초 단위 윈도우, r은 남은 요청 수, t는 윈도우가 초기화될 때까지의 초). X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset은 많은 클라이언트가 이미 읽는 이름으로 같은 값을 제공합니다.

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

한도를 넘으면 엔진은 일반적인 JSON 오류(코드 rate_limited)와 함께 429를 반환하고, 기다려야 할 초를 Retry-After 헤더에 담습니다. 곧바로 재시도하지 말고 그만큼 기다리세요. GET /v1/runs/{id}/events로 실행을 따라가는 것은 이벤트마다가 아니라 연결당 한 번만 집계됩니다.

멱등한 실행 생성

네트워크 장애로 실행이 만들어졌는지 알 수 없을 때가 있습니다. POST /v1/runs에 최대 200자의 Idempotency-Key 헤더를 함께 보내세요. 조직에 같은 키로 만든 실행이 이미 있으면 Ephemeral이 새로 만들지 않고 그 실행을 상태 200으로 반환합니다. 새 실행은 202를 반환합니다.

페이지네이션

GET /v1/runs는 limit(1~100)이나 cursor를 전달하면 페이지 단위로 응답합니다. 응답은 {"items": [...], "next_cursor": "..."} 형태입니다. next_cursor를 cursor로 다시 전달하면 다음 페이지를 받고, next_cursor가 비어 있으면 마지막 페이지입니다. 커서는 불투명한 값이며 같은 status 필터와 함께일 때만 유효합니다. limit이나 cursor가 없으면 가장 최근 실행 100개의 일반 배열이 반환됩니다.

버전과 지원 중단

API 버전은 경로에 포함됩니다. 여기의 모든 엔드포인트는 /v1 아래에 있습니다. 한 버전 안에서는 추가만 합니다. 새 엔드포인트, 새 선택 요청 필드, 새 응답 필드, 새 이벤트 유형이 생길 수 있습니다. 기존 필드의 이름과 의미는 바뀌지 않으므로 클라이언트는 모르는 필드를 무시해야 합니다.

기존 클라이언트를 깨뜨리는 변경은 새 경로의 새 버전으로 나옵니다. 이전 버전은 새 버전이 공개된 뒤 최소 6개월 동안 계속 동작합니다. 지원 중단 기간에는 응답에 Deprecation 헤더와 중단 날짜를 알리는 Sunset 헤더가 붙고, 조직 소유자에게 이메일로 알립니다.

레퍼런스

엔진 API는 OpenAPI 3.1 문서(https://app.ephemer.al/openapi.json)로도 공개되며, 각 작업에 필요한 키 역할이 포함됩니다. 키 역할인 member와 admin은 보호된 리소스 메타데이터의 scopes_supported에 기계가 읽을 수 있는 형태로 나열됩니다.