안정적인 JSON의 증거.

요청 및 캐싱

모든 응답은 application/json이며 Cache-Control: public, s-maxage=60, stale-while-revalidate=300을 포함합니다. 이 헤더를 준수하면 비용이 들지 않고 인덱스를 저렴하게 제공할 수 있으므로 폴링 대신 캐시에서 읽어 주세요. GET과 HEAD만 제공되며 다른 메서드는 Allow 헤더와 함께 405를 반환합니다.

오류는 결코 상태 코드만 반환하지 않습니다. 본문은 항상 분기 기준으로 삼아도 안전한 code와 사람을 위해 작성된 message를 가진 객체입니다:

{ "error": { "code": "invalid_limit", "message": "limit must be an integer from 1 to 100" } }

서버 목록

GET /api/v1/servers

q

제목, registry 이름 및 설명과 대조되는 자유 텍스트입니다.

state

verified, stale, broken, auth_required 또는 unverifiable 중 하나입니다.

package

패키지 레지스트리 유형: npm, pypi 또는 oci.

transport

Registry 레코드에 선언된 전송 방식입니다(예: stdio).

client

Clients에 나열된 클라이언트 슬러그입니다(예: claude-code). 공개 API

limit

1에서 100 사이의 정수입니다. 기본값은 25입니다. 이 범위를 벗어난 값은 잘라내지 않고 거부되므로, 클라이언트는 요청한 행 수와 다른 수를 알림 없이 받는 일이 없습니다.

cursor

이전 응답의 nextCursor입니다. 첫 페이지에서는 생략하며, 마지막 페이지에서는 null입니다.

GET /api/v1/servers?state=verified&package=npm&limit=2

{
  "data": [
    {
      "id": "srv_01J…",
      "registryName": "example/one",
      "title": "Example Server",
      "description": "What the server says it does.",
      "state": "verified",
      "observedAt": "2026-09-15T00:00:00.000Z",
      "toolCount": 3,
      "url": "/servers/example/one"
    }
  ],
  "nextCursor": null
}

서버 세부 정보

GET /api/v1/servers/:namespace/:name

한 서버의 Registry 메타데이터, 실행 가능한 패키지 및 공개 관측 기록을 data 아래에 반환합니다. 이 기록의 각 실행은 테스트한 정확한 패키지 버전을 명시하며, 이는 보통 오늘 게시된 버전이 아닙니다. 알 수 없는 조합은 코드 not_found와 함께 404를 반환합니다.

검증 실행

GET /api/v1/verification-runs/:id

식별자로 지정된 하나의 관측입니다. 확인 규칙을 통과하지 못한 실행은 여기에 없으며 코드 not_found와 함께 404를 반환합니다. 이는 존재한 적 없는 실행과 동일한 응답인데, 둘 사이의 어떤 차이라도 규칙이 숨기려는 실패를 공개하게 되기 때문입니다.

데이터셋 통계

GET /api/v1/stats

{ "data": { "indexedServers": 979, "verifiedServers": 0, "observedAt": null } }

오류 코드

invalid_limit

400 — limit이 1에서 100 사이의 정수가 아니었습니다.

invalid_cursor

400 — 커서가 잘못되었거나 다른 정렬 순서에 대해 생성되었습니다. 첫 페이지부터 다시 시작하세요.

not_found

404 — 해당 서버가 없거나 해당 식별자로 게시할 수 있는 실행이 없습니다.

method_not_allowed

405 — API는 읽기 전용입니다. 응답은 제공되는 메서드를 명시합니다.

공개되지 않는 항목

내부 stderr, 워커 임대 및 대기 중인 확인 세부 정보는 결코 게시되지 않으며, 상태는 항상 요청한 시각이 아니라 설명하는 관측의 타임스탬프를 포함합니다.