OpenAPI 시작하기

Lynx OpenAPI는 에이전트 실행 기록, 런타임 설정 조회, 이슈 후보 접수, Run 타임라인 조회를 제공하는 언어 독립 통합 인터페이스입니다. TypeScript 환경에서는 공식 SDK를 사용할 수 있습니다. 다른 언어 SDK를 만들거나 아직 지원하지 않는 실행 환경을 연결하려면 OpenAPI를 직접 사용하세요.

기본 URL과 인증

모든 공개 엔드포인트는 다음 경로를 사용합니다.

https://api.lynxops.co/openapi/v1

직접 운영하는 Lynx는 도메인만 바꾸고 /openapi/v1 경로는 유지합니다. 모든 요청에 워크스페이스 API 키를 전달합니다.

X-API-Key: YOUR_WORKSPACE_API_KEY
Content-Type: application/json

사용자 Bearer 토큰을 보내지 마세요. API 키가 워크스페이스와 실행 환경을 결정하므로 요청 본문으로 이 경계를 바꿀 수 없습니다.

엔드포인트

메서드	경로	필요한 권한	용도
`POST`	`/events/batch`	`events:write`	이벤트를 최대 100개까지 기록합니다.
`POST`	`/issue-records`	`events:write`	탐지 또는 복구 기록을 비동기 검토 대상으로 접수합니다.
`GET`	`/runtime-config`	`config:read`, `policies:read`	현재 프롬프트 버전과 활성 정책을 조회합니다.
`GET`	`/runs`	`usage:read`	Run 목록을 커서 방식으로 조회합니다.
`GET`	`/runs/{runId}`	`usage:read`	Run과 첫 이벤트 페이지를 조회합니다.
`GET`	`/runs/{runId}/events`	`usage:read`	나머지 이벤트 타임라인을 조회합니다.

첫 번째 요청

curl --request POST \
  --url https://api.lynxops.co/openapi/v1/events/batch \
  --header "X-API-Key: $LYNX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "eventId": "evt_01JZQ3W8FQ",
      "clientId": "python-worker-01",
      "runId": "run_01JZQ3VY4K",
      "sessionId": "session_customer_42",
      "agentName": "support-agent",
      "eventType": "USER_INPUT",
      "label": "Customer message",
      "timestamp": 1784808000000,
      "payload": {
        "text": "I cannot sign in"
      }
    }
  ]'

다른 언어 SDK 구현하기

운영 환경용 SDK에는 다음 구성이 필요합니다.

runId, sessionId, spanId, parentSpanId를 전달하는 실행 컨텍스트
크기가 제한된 메모리 또는 디스크 큐
짧은 timeout을 사용하는 백그라운드 배치 전송
retryableEventIds만 다시 보내는 재시도 처리
rejectedEventIds를 큐에서 제거하는 처리
재시도해도 변하지 않는 eventId와 clientRecordId
ETag를 사용하는 런타임 설정 캐시
도구 실행 직전에 동작하는 로컬 정책 판단
안전한 프로세스 종료를 위한 flush와 shutdown

일반 이벤트 전송은 fail-open으로 구현하세요. Lynx에 일시적으로 접근할 수 없어도 고객 요청은 계속 처리되어야 합니다. 고위험 로컬 정책은 별도로 fail-closed 동작을 선택할 수 있습니다.

공통 HTTP 처리

400: 공개 요청 형식에 맞지 않습니다.
401: X-API-Key가 없거나 올바르지 않습니다.
403: API 키에 필요한 권한이 없습니다.
413: 요청 본문이 너무 큽니다.
429: 요청 제한을 넘었습니다. Retry-After를 따르세요.
5xx: 별도 근거가 없다면 일시적인 오류로 처리합니다.

네트워크 오류, 429, 5xx에는 jitter가 포함된 지수형 대기를 적용하세요. 장시간 장애가 메모리를 계속 사용하지 않도록 큐 최대 크기도 설정해야 합니다.

프롬프트, 도구 인자, 모델 응답, 로그와 payload에는 민감정보가 들어갈 수 있습니다. 큐에 넣기 전에 비밀값을 마스킹하고, 로컬에서도 크기를 제한하며, API 키를 로그에 남기지 마세요.

다음 단계

이벤트 기록

이벤트 형식, 배치, 재시도 동작을 구현합니다.

런타임 설정 조회

프롬프트 버전과 정책을 로컬에 저장합니다.

이슈 후보 접수

에이전트 실행을 막지 않고 탐지 결과를 전송합니다.

Run 조회

Run과 이벤트 타임라인을 조회합니다.

​기본 URL과 인증

​엔드포인트

​첫 번째 요청

​다른 언어 SDK 구현하기

​공통 HTTP 처리

​다음 단계

이벤트 기록

런타임 설정 조회

이슈 후보 접수

Run 조회

기본 URL과 인증

엔드포인트

첫 번째 요청

다른 언어 SDK 구현하기

공통 HTTP 처리

다음 단계