API 문서

세 단계면 랜덤 데이터가 나옵니다:

1. 레이아웃 만들기 — 필드 이름과 타입으로 데이터 스키마를 정의합니다
2. API 키 발급 — API Keys 페이지에서 하나 만듭니다
3. 요청 보내기 — 레이아웃 슬러그로 API를 호출합니다

요청 예시:

curl -H "X-API-Key: ak_your_key_here" \
  "https://api.apiryner.com/v1/layouts/user-profile?count=2&locale=ko"

응답 예시:

[
  {
    "id": 1,
    "name": "김서연",
    "email": "[email protected]",
    "age": 28,
    "is_active": true
  },
  {
    "id": 2,
    "name": "박준호",
    "email": "[email protected]",
    "age": 45,
    "is_active": true
  }
]

Apiryner는 두 가지 인증 방식을 지원합니다:

curl -H "X-API-Key: ak_your_key_here" \
  https://api.apiryner.com/v1/layouts/my-layout

# OAuth PKCE로 로그인 (브라우저가 열립니다)
npx apiryner login

# 토큰 사용
curl -H "Authorization: Bearer oat_your_token" \
  -X POST https://api.apiryner.com/v1/layouts \
  -H "Content-Type: application/json" \
  -d '{"name": "Users", "slug": "users", "schema": {"id": {"type": "uuid"}}}'

조건부 필드

어떤 필드든 condition을 달 수 있습니다. 같은 레코드에서 먼저 생성된 필드를 보고, 레코드마다 이 필드를 포함할지 말지를 정합니다:

{
  "status": { "type": "enum", "options": { "values": ["active", "banned"] } },
  "banned_reason": {
    "type": "sentence",
    "condition": { "field": "status", "equals": "banned" }
  }
}

조건이 맞지 않으면 그 레코드에서는 필드가 아예 빠집니다. condition의 field는 같은 객체 안의 필드를 가리켜야 합니다.

스냅샷

스냅샷은 생성된 데이터 한 벌을 고정해서, 호출할 때마다 똑같은 응답을 돌려줍니다. 데모·스크린샷·바뀌면 안 되는 픽스처에 씁니다.

curl -X POST https://api.apiryner.com/v1/snapshots \
  -H "Authorization: Bearer oat_your_token" \
  -H "Content-Type: application/json" \
  -d '{"layout_slug": "users", "name": "Demo users",
       "slug": "demo-users", "count": 20, "seed": 42}'

• GET /v1/snapshots/:slug가 저장된 데이터를 서빙하고, ?format=csv도 레이아웃과 똑같이 동작합니다.
• shape — auto(기본), object, array — 는 스냅샷이 객체 하나로 답할지 배열로 답할지를 정합니다. auto는 레이아웃 설정을 따릅니다.
• PUT /v1/snapshots/:slug로 name이나 data를 교체할 수 있어, 고정된 레코드를 직접 손볼 수 있습니다.
• 스냅샷 서빙도 월 레코드 한도에 그대로 반영됩니다. 고정된 데이터도 API가 내보내는 데이터이기 때문입니다.

전송과 검증

전송은 JSON POST이고 헤더 두 개가 붙습니다. X-Apiryner-Event에는 이벤트 이름이, X-Apiryner-Signature에는 원본 요청 본문을 시크릿으로 HMAC-SHA256 해서 16진수로 인코딩한 값이 담깁니다. 페이로드를 믿기 전에 먼저 검증하세요:

const expected = crypto
  .createHmac("sha256", secret)
  .update(rawBody)          // the raw body, before JSON.parse
  .digest("hex");

if (expected !== req.headers["x-apiryner-signature"]) {
  return res.status(401).end();
}

전송 타임아웃은 10초입니다. 네트워크 오류와 408·429·5xx 응답은 5초, 30초 뒤 두 번 재시도하고, 그 밖의 4xx는 재시도하지 않습니다. 모든 시도가 기록되며 GET /v1/webhooks/:id/deliveries로 확인할 수 있습니다.

스키마의 각 필드는 type과 선택적인 options 객체를 가집니다.

스키마 필드 구조:

{
  "field_name": {
    "type": "integer",
    "options": {
      "min": 1,
      "max": 100
    }
  }
}

풀에서 값을 뽑는 모든 타입 — name, email, phone, 주소 계열, 텍스트 계열, slug — 은 locale 옵션도 받습니다. 그 필드에서만 요청 로케일을 덮어씁니다. 로케일을 덮어쓴 필드는 레코드의 인물을 공유하지 않고 자기 인물을 따로 만듭니다:

{
  "name": {"type": "name"},
  "korean_name": {"type": "name", "options": {"locale": "ko"}}
}

중첩 객체 예시:

{
  "address": {
    "type": "object",
    "properties": {
      "street": {"type": "street"},
      "city": {"type": "city"},
      "zipcode": {"type": "zipcode"}
    }
  }
}

배열 예시:

{
  "tags": {
    "type": "array",
    "items": {"type": "word"},
    "options": {"min_items": 2, "max_items": 5}
  }
}

enum 예시:

{
  "status": {
    "type": "enum",
    "options": {
      "values": ["active", "inactive", "pending"]
    }
  }
}

속도 제한과 사용량

모든 응답에 분당 사용 한도가 함께 실립니다:

• X-RateLimit-Limit — 플랜의 분당 허용 요청 수
• X-RateLimit-Remaining — 현재 창에서 남은 요청 수
• X-RateLimit-Reset — 창이 리셋되는 시각 (Unix 타임스탬프)
• Retry-After — 기다릴 초. 429일 때만 붙습니다

월 사용량은 요청 수와 레코드 수 두 축으로 집계합니다. 번들 호출은 요청 1건에 더해 응답에 담긴 레코드 전부가 반영됩니다. 이번 기간 사용량은 GET /v1/account/usage로 확인합니다:

{
  "requests": 128,
  "records": 4210,
  "limit_requests": 1000,
  "limit_records": 10000,
  "period": "2026-08"
}

플랜의 요청당 최대 레코드 수를 넘는 count는 거절되지 않고 잘립니다. 너무 많이 요청했다는 이유로 실패하지는 않습니다. 레이아웃 개수·API 키 개수·중첩 깊이 한도도 같은 방식으로 사용 시점에 적용됩니다.

인증

validate_schema, infer_schema, quick_generate는 전부 로컬에서 돕니다 — 계정도 네트워크도 필요 없습니다. 가입 전에도 에이전트가 픽스처를 만들거나 OpenAPI 파일을 레이아웃 스키마로 바꿀 수 있습니다.

list_types는 에이전트가 없는 필드 타입을 지어내지 않게 막아 줍니다. 인증된 상태면 이 페이지의 타입 카탈로그를 설명과 지원 로케일까지 담아 돌려주고, 인증이 없으면 실패하는 대신 패키지에 내장된 타입 이름 목록으로 폴백합니다.

원격 서버는 브라우저로 인증합니다. 에이전트가 스스로 등록하고, 한 번 승인하면, 발급된 토큰은 이 엔드포인트 전용으로 묶입니다. X-API-Key 헤더도 쓸 수 있고, 이때는 API 키의 읽기 전용 제한이 그대로 적용됩니다.

로컬 서버의 크리덴셜은 API가 필요한 첫 툴 호출 때 다음 순서로 해석됩니다.

1. apiryner mcp 뒤에 붙인 --key <key>, 또는 $APIRYNER_API_KEY
2. apiryner login으로 만든 OAuth 세션 (만료되면 자동 갱신)
3. apiryner config set api-key <key>로 저장한 API 키

인증 없이 서버를 띄워도 괜찮습니다. 계정이 필요한 툴은 무엇이 빠졌는지 알려주고, 로그인하는 순간부터 재시작 없이 동작합니다. create_layout, update_layout, delete_layout은 계정에 쓰고, 삭제는 되돌릴 수 없다는 점만 유의하세요.