퍼즐 REST API 참고 자료

Bearer API 키를 사용합니다. 만든 결과 전체를 내 퍼즐에 저장하고 파일 자체가 아닌 브라우저 페이지 주소를 돌려줍니다.

인증

Authorization: Bearer YOUR_API_KEY를 보냅니다. 외부 접속 지점은 쿠키를 받지 않습니다. 키는 서버에 보관하세요.

요청 예시

curl -X POST https://puzzlegenio.com/api/v1/puzzles \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: task-000000000001' \
  -H 'Content-Type: application/json' \
  -d '{ "type": "wordsearch", "preset": "word-search-for-kids", "title": "Animal word search", "input": { "words": [ "CAT", "DOG", "LION", "TIGER" ] }, "options": { "gridSize": 10, "allowDiagonal": false } }'

만들기 성공 응답 예시

{
  "data": {
    "savedId": "123456789",
    "shareId": "AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "type": "wordsearch",
    "preset": "word-search-for-kids",
    "viewUrl": "https://puzzlegenio.com/puzzles/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "exportPageUrl": "https://puzzlegenio.com/puzzles/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "editUrl": "https://puzzlegenio.com/word-search-for-kids?id=123456789",
    "playUrl": "https://puzzlegenio.com/word-search-maker/play/AbCdEfGhIjKlMnOpQrStUvWxYz012345",
    "expiresAt": "2026-11-01T00:00:00.000Z",
    "shareState": "active",
    "savedCount": 1,
    "limit": 20,
    "formats": [
      "pdf",
      "answer-pdf"
    ],
    "itemCount": 1,
    "warnings": []
  },
  "requestId": "00000000-0000-4000-8000-000000000000"
}

식별자와 날짜는 응답 구조를 보여 주는 예시입니다. data에 저장 결과가 있고 requestId는 이번 요청을 식별합니다.

viewUrl: 공개 미리 보기 페이지입니다. 링크를 가진 사람은 정답도 볼 수 있습니다.
exportPageUrl: 브라우저에서 내려받기 형식을 고르는 페이지입니다. viewUrl과 같을 수 있으며 파일 직접 주소가 아닙니다.
editUrl: 소유자 전용 수정 페이지입니다. 로그인과 소유권 확인이 필요합니다.
playUrl: 지원하는 모드에만 게임 페이지가 있습니다. 그 밖에는 null입니다.

REST 접속 지점

POST	/api/v1/puzzles
GET	/api/v1/puzzles
GET	/api/v1/puzzles/{savedId}
DELETE	/api/v1/puzzles/{savedId}
POST	/api/v1/puzzles/{savedId}/share
GET	/api/v1/capabilities
GET	/api/v1/results/{shareId}
POST	/api/v1/assets
POST	/api/v1/assets/import
GET	/api/v1/openapi.json

기계 판독용 OpenAPI 명세

멱등성과 응답

만들기에는 Idempotency-Key가 필요합니다. 같은 키와 내용으로 다시 요청하면 같은 저장 퍼즐이 반환됩니다. 같은 키로 다른 내용을 보내면 409가 반환됩니다. 처음 만들 때는 201, 재요청 때는 200입니다.

오류

오류 형식은 {error:{code,message,details},requestId}입니다. 400은 잘못된 요청, 401은 인증, 403은 한도나 권한, 404는 없거나 타인 소유인 항목, 409는 키 충돌, 410은 무효화된 공유, 413은 크기 초과, 415는 매체 형식, 422는 입력이나 생성 실패, 429는 Retry-After가 있는 빈도 제한, 503은 만들기 중단을 뜻합니다.