OpenAPI 시작하기

Lynx OpenAPI는 에이전트 실행 기록, 런타임 설정 조회, 이슈 후보 접수, 방화벽 승인 요청, Run 타임라인 조회를 제공하는 언어 독립 통합 인터페이스입니다.

Lynx는 현재 파일럿 단계입니다. 파일럿 참여 또는 OpenAPI 연동 개발을 원하면 partners@hvnn.me로 연락해 주세요.

TypeScript 환경에서는 공식 SDK를 사용할 수 있습니다. 다른 언어 SDK를 만들거나 아직 지원하지 않는 실행 환경을 연결하려면 OpenAPI를 직접 사용합니다.

기본 URL과 인증

모든 공개 API는 아래와 같은 경로를 사용합니다.

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

직접 운영하는 Lynx는 도메인만 바꾸고 /openapi/v1 경로는 유지합니다. 기계 판독이 가능한 OpenAPI 3.0 문서는 인증 없이 https://api.lynxops.co/openapi.json에서 조회할 수 있습니다. 코드 생성 방법은 OpenAPI 스키마에서 확인합니다. 모든 요청에 워크스페이스 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`	현재 프롬프트 버전과 활성 정책을 조회합니다.
`POST`	`/firewall-approvals`	`events:write`	보호된 도구 호출의 승인을 요청합니다.
`GET`	`/firewall-approvals/{approvalId}`	`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를 사용하는 런타임 설정 캐시
도구 실행 직전에 동작하는 로컬 정책 판단
REQUIRE_APPROVAL 결정을 처리하는 제한된 승인 흐름
안전한 프로세스 종료를 위한 flush와 shutdown

일반 이벤트 전송은 fail-open으로 구현합니다. Lynx에 일시적으로 접근할 수 없어도 고객 요청은 계속 처리되어야 합니다. 고위험 로컬 정책은 별도로 fail-closed 동작을 선택할 수 있습니다. REQUIRE_APPROVAL에서는 안정적인 clientRequestId로 요청을 한 번 생성하고 설정된 제한 시간까지만 상태를 조회합니다. APPROVED 응답을 받은 경우에만 보호된 도구를 실행합니다. 네트워크 오류, 잘못된 응답, 거절, 만료는 도구 실행을 허용하지 않습니다.

공통 HTTP 처리

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

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

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

다음 단계

OpenAPI 스키마 받기

공개된 기계 판독 계약에서 HTTP 클라이언트를 생성합니다.

이벤트 기록

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

런타임 설정 조회

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

방화벽 승인 요청

운영자가 결정할 때까지 보호된 도구 호출을 대기시킵니다.

이슈 후보 접수

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

Run 조회

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

​기본 URL과 인증

​엔드포인트

​첫 번째 요청

​다른 언어 SDK 구현하기

​공통 HTTP 처리

​다음 단계

OpenAPI 스키마 받기

이벤트 기록

런타임 설정 조회

방화벽 승인 요청

이슈 후보 접수

Run 조회

기본 URL과 인증

엔드포인트

첫 번째 요청

다른 언어 SDK 구현하기

공통 HTTP 처리

다음 단계