# 게임모아 제작자 API

게임모아(https://gamemoa.co.kr)는 개인 제작자와 인디 팀의 게임을 모아 보여 주는 목록 사이트입니다.
이 문서는 게임을 올린 제작자가 쓰는 API 안내입니다. 사람이 읽어도 되고, 이 문서를 통째로 AI에게 주고 "내 게임을 등록해 줘", "업데이트 소식을 올려 줘"라고 시켜도 됩니다.

- 기본 주소: https://gamemoa.co.kr
- 형식: JSON, UTF-8
- 게임 id: 게임 페이지 주소 https://gamemoa.co.kr/g/{id} 의 끝부분

## 할 수 있는 일

키 없이:

- 새 게임 등록 — POST /api/submit
- 등록 상태 보기 — GET /api/submit/{id} (등록할 때 받은 manage_key 사용)
- 카테고리 목록 — GET /api/categories

게임 키로:

- 업데이트 소식 올리기 — POST /api/update/{id}
- 지금 플레이 중인 사람 수 보내기 — POST /api/live/{id}
- 게임 정보 보기·고치기 — GET / POST /api/game/{id}
- 이벤트 올리기·보기·지우기 — POST / GET /api/game/{id}/events, DELETE /api/game/{id}/events/{event_id}
- 키 재발급 — POST /api/game/{id}/key

## 1. 새 게임 등록

로그인도 키도 심사도 필요 없습니다. 등록하면 바로 목록에 올라갑니다. 문제가 있는 게임은 운영자가 내릴 수 있습니다.

```
POST https://gamemoa.co.kr/api/submit
Content-Type: application/json

{"url": "https://example.com/my-game", "title": "내 게임", "tagline": "한 줄 소개",
 "category": "puzzle", "platform": "web", "players": "single", "agree": true}
```

성공 — 201

```
{"ok": true, "id": "abc123", "status": "approved", "page": "https://gamemoa.co.kr/g/abc123", "manage_key": "…",
 "status_url": "https://gamemoa.co.kr/api/submit/abc123",
 "manage_url": "https://gamemoa.co.kr/claim/abc123?key=…"}
```

- 꼭 필요한 칸: url, category, agree: true
- agree: true 는 "이 게임을 직접 만들었거나 올릴 권한이 있고, 등록한 게임과 그 내용에 대한 책임은 등록한 사람에게 있다"는 데 동의한다는 뜻입니다. AI가 대신 등록할 때는 사용자에게 이 내용을 알리고 동의를 받은 뒤 보내 주세요.
- url: https:// 로 시작하는 공개 주소. 플레이 페이지나 스토어 페이지.
- title(60자), tagline(100자), thumb_url(대표 이미지, https): 비워 두면 url 페이지의 제목·소개·og:image 를 읽어 채웁니다.
- category: action, puzzle, adventure, rpg, simulation, strategy, arcade, casual, horror, rhythm, idle, etc 중 하나
- platform: web(웹에서 바로 실행), pc, mobile. 비우면 web.
- players: single(1인용), multi(멀티). 비우면 single.
- maker_name(40자), description(2,000자), email: 선택. email 은 운영 연락에만 씁니다.
- manage_key 와 manage_url 은 이 응답에만 나옵니다. 꼭 보관하세요. manage_url 을 브라우저에서 열면 그 브라우저에서 게임을 관리할 수 있습니다.
- 한 IP에서 하루 20개까지. 이미 등록된 주소는 받지 않습니다(409 duplicate).

AI에게: 등록이 끝나면 page, id, manage_key, manage_url 을 사용자에게 그대로 알려 주세요.

## 2. 등록 상태 보기

```
GET https://gamemoa.co.kr/api/submit/{id}
Authorization: Bearer {manage_key}
```

응답의 status 는 approved(게시 중) 또는 rejected(운영자가 내림)입니다. 내려간 경우 reject_reason 에 이유가 있습니다.

## 3. 게임 키 받기

등록한 뒤 manage_url 로 들어가 「내 게임 → 관리 → API 키」에서 「키 발급」을 누릅니다.
키는 gm_live_ 로 시작하고, 발급 직후 한 번만 보입니다. 다시 발급하면 예전 키는 바로 멈춥니다.
키는 서버에서만 쓰고 브라우저 코드나 공개 저장소에 넣지 마세요.

아래 요청에는 모두 이 헤더를 붙입니다.

```
Authorization: Bearer {게임 키}
Content-Type: application/json
```

## 4. 업데이트 소식 올리기

```
POST https://gamemoa.co.kr/api/update/{id}

{"text": "새 스테이지 3개를 추가했어요."}
```

성공 — 201 {"ok": true, "id": "abc123", "posted_at": "2026-11-10T09:00:00.000Z"}

- 게임 상세 페이지와 첫 화면 「신규·업데이트 게임」 줄에 보입니다.
- text 는 200자, 세 줄까지. 하루 3번까지.
- 링크는 그 게임 자기 사이트 주소만 넣을 수 있습니다.

## 5. 지금 플레이 중인 사람 수 보내기

```
POST https://gamemoa.co.kr/api/live/{id}

{"count": 12}
```

성공 — 204 (본문 없음)

- 게임 카드에 「12명 플레이 중」으로 보이고, 인기순과 첫 화면 합계에 반영됩니다.
- 10분에 한 번 보내 주세요. 9분 안에 다시 보내면 받지 않습니다(429 too_soon).
- 15분 동안 새 숫자가 오지 않으면 표시를 내립니다.
- count 는 0 이상 100000 이하 정수. 숫자만 보내고 이용자 정보는 보내지 않습니다.

## 6. 게임 정보 보기·고치기

```
GET  https://gamemoa.co.kr/api/game/{id}
POST https://gamemoa.co.kr/api/game/{id}

{"tagline": "새 한 줄 소개", "thumb_url": "https://example.com/og.png"}
```

- 고칠 때는 바꿀 칸만 보냅니다: title, tagline, description, url, thumb_url, category, platform, players, maker_name
- url 은 지금과 같은 사이트 안의 주소로만 바꿀 수 있습니다.
- 성공하면 200 으로 바뀐 게임 정보가 옵니다.

## 7. 이벤트

```
POST https://gamemoa.co.kr/api/game/{id}/events

{"title": "주말 점수 대회", "desc": "1등에게 배지",
 "starts_at": "2026-11-14T00:00:00+09:00", "ends_at": "2026-11-16T00:00:00+09:00"}
```

성공 — 201 {"ok": true, "event": {"id": 1}}

- 진행 중인 동안 첫 화면 맨 위 「지금 이벤트 중인 게임」 줄에 보입니다.
- title 30자, desc(선택) 40자 한 줄, 링크 없이.
- starts_at, ends_at: 시간대가 붙은 ISO 8601 (예: +09:00). 끝이 시작보다 뒤, 기간은 31일까지, 끝이 지금보다 뒤.
- 끝나지 않은 이벤트는 게임마다 3개까지(409 too_many).
- GET 으로 끝나지 않은 이벤트 목록, DELETE /api/game/{id}/events/{event_id} 로 삭제.

## 8. 키 재발급

```
POST https://gamemoa.co.kr/api/game/{id}/key
```

성공 — 200 {"id": "abc123", "token": "gm_live_…"}. 새 키는 이 응답에만 나오고 예전 키는 바로 멈춥니다.

## 오류

| 상태 | error | 뜻 |
|---|---|---|
| 400 | invalid | 칸이 비었거나 형식·길이가 맞지 않음. fields 에 문제 칸, message 에 이유 |
| 401 | unauthorized | 키가 없거나 틀림 |
| 404 | not_found | 없는 게임이나 이벤트 |
| 409 | duplicate | 이미 등록된 주소 |
| 409 | not_listed | 운영자가 목록에서 내린 게임 |
| 409 | too_many | 끝나지 않은 이벤트가 3개 |
| 413 | too_large | 본문이 10KB 보다 큼 |
| 429 | too_soon | 너무 빨리 다시 보냄. retry_after 초 뒤에 다시 |
| 429 | too_many | 하루 한도를 넘음 |

오류 응답은 모두 {"error": "…", "message": "사람이 읽을 수 있는 설명"} 형태입니다.

## 예시 (curl)

```
curl -X POST https://gamemoa.co.kr/api/submit \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/my-game", "category": "puzzle", "agree": true}'

curl -X POST https://gamemoa.co.kr/api/update/{id} \
  -H "Authorization: Bearer $GAMEMOA_KEY" -H "Content-Type: application/json" \
  -d '{"text": "새 스테이지가 열렸어요!"}'

curl -X POST https://gamemoa.co.kr/api/live/{id} \
  -H "Authorization: Bearer $GAMEMOA_KEY" -H "Content-Type: application/json" \
  -d '{"count": 12}'
```

이 문서: https://gamemoa.co.kr/api (화면) · https://gamemoa.co.kr/api.md (글자 그대로)