# 메타모아 공간 운영자 API · metamoa operator API

메타모아(https://metamoa.com)에 올라간 웹 메타버스 공간의 운영자가 쓰는 API예요. 공간 키 하나로 두 가지를 할 수 있어요.
For operators of spaces listed on metamoa. One space key does both:

1. 업데이트 소식 올리기 · Post an update — `POST /api/update/{space_id}`
2. 접속자 수 보내기 · Send the visitor count — `POST /api/live/{space_id}`

- 기본 주소 · Base URL: `https://metamoa.com`
- 공간 id · Space id: 공간 페이지 주소 `https://metamoa.com/s/{space_id}`의 끝부분 (the last part of your space page URL)
- 형식 · Format: JSON, UTF-8

## 키 받기 · Getting a key

- contact@float.do 로 공간 주소를 적어 「키 주세요」라고 보내 주세요. 확인한 뒤 공간 전용 키를 메일로 보내 드려요. 가입·비용 없음.
- Email contact@float.do with your space URL and "key please". We reply with your space key. No sign-up, no fee.
- 공간 페이지의 「내 공간이에요」에서 운영자 확인을 받으면 키를 직접 발급·재발급할 수 있어요: https://metamoa.com/owner · Verified operators can issue the key themselves from 「내 공간이에요」 on the space page.
- 키를 새로 받으면 예전 키는 바로 멈춰요. · A new key stops the old one at once.
- 키는 비밀로 보관하세요. 서버에서만 쓰고 브라우저 코드에 넣지 마세요. · Keep it secret; use it from your server, never in browser code.

## 인증 · Authentication

모든 요청에 이 헤더를 붙여요. · Every request carries:

```
Authorization: Bearer {space_key}
Content-Type: application/json
```

## 1. 업데이트 소식 올리기 · Post an update

```
POST https://metamoa.com/api/update/{space_id}
```

요청 · Request

```json
{"text": "겨울 맵이 열렸어요. 같이 걸어요!"}
```

성공 · Success — `201`

```json
{"ok": true, "space_id": "{space_id}", "posted_at": "2026-11-01T09:00:00.000Z", "shown_until": "2026-11-08T09:00:00.000Z"}
```

보이는 곳 · Where it shows

- 공간 상세 페이지에 소식 · The note on your space page
- 목록 카드에 U 표시 · A U mark on your card
- 첫 화면 「New·업데이트」 줄 (무작위로 돌아가며) · A turn in the New & Update row on the home page
- 7일 동안 보여요 · Shown for 7 days

규칙 · Rules

- 하루(24시간)에 한 번 · Once per 24 hours
- `text` 200자, 3줄까지 · up to 200 characters and 3 lines
- 링크는 그 공간 자기 사이트 주소만 · Links only to your own site
- 금지어가 있으면 받지 않아요. 문제가 있는 글은 운영팀이 내릴 수 있어요. · Banned words are refused; the team may hide a note.

## 2. 접속자 수 보내기 · Send the visitor count

```
POST https://metamoa.com/api/live/{space_id}
```

요청 · Request

```json
{"count": 12}
```

성공 · Success — `204` (본문 없음 · no body)

- 지금 접속자 수를 보내면 랭킹과 첫 화면 합계에 반영돼요. · Feeds the ranking and the home total.
- 10분에 한 번 보내 주세요. 같은 공간에서 9분 안에 다시 보내면 받지 않아요. · Send every 10 minutes; a second send within 9 minutes is refused.
- `count`는 0 이상 100000 이하 정수 · an integer from 0 to 100000
- 기준 · What to count: 지금 함께 있는 사람(모든 방 합계, 최근 몇 분 안에 신호가 있는 사람, 봇·테스트 제외). 이용자 정보는 보내지 않아요. · People there right now (all rooms together, active in the last few minutes, no bots or tests). Send the number only.

## 오류 · Errors

| 코드 · Status | 본문 · Body | 뜻 · Meaning |
|---|---|---|
| 400 | `{"error":"invalid","fields":["text"],"reason":"..."}` | 글이 비었거나 길거나, 금지어·다른 사이트 링크 · empty, too long, banned words or a foreign link |
| 400 | `{"error":"invalid","fields":["count"]}` | count가 정수가 아니거나 범위 밖 · count not an integer in range |
| 401 | `{"error":"unauthorized"}` | 키가 없거나 틀리거나 다른 공간 키 · missing, wrong or another space's key |
| 404 | `{"error":"not_found"}` | 목록에 없는 공간 · space not listed |
| 413 | `{"error":"too large"}` | 본문이 너무 큼 · body too large |
| 429 | `{"error":"too_soon","retry_after":3600}` | 너무 빨리 다시 보냄. `retry_after`초 뒤에 다시 · too soon; retry after `retry_after` seconds (also in the `Retry-After` header) |
| 429 | `{"error":"too_many"}` | 같은 IP에서 너무 많이 보냄 · too many requests from one IP |

## 예시 · Example (curl)

```
curl -X POST https://metamoa.com/api/update/{space_id} \
  -H "Authorization: Bearer $METAMOA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "새 맵이 열렸어요!"}'

curl -X POST https://metamoa.com/api/live/{space_id} \
  -H "Authorization: Bearer $METAMOA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 12}'
```

## 문의 · Contact

contact@float.do · 메타모아 · 플로트 주식회사 (FLOAT Co., Ltd.)
이 문서 · This page: https://metamoa.com/api (HTML) · https://metamoa.com/api.md (Markdown)