개발자 문서
사전에 실린 표현을 다른 프로그램에서 불러올 수 있는 API예요. 키를 받아 HTTPS로 요청하면 JSON으로 답해요. 지금은 읽기만 할 수 있어요.
시작하기
- 회원으로 가입하고 로그인해요.
- 내 정보 › API 키에서 키를 만들어요. 키는 만들 때 한 번만 보여 주니 바로 복사해 두세요. 한 계정에 5개까지 만들 수 있어요.
- 요청 헤더에 키를 넣어 아래 주소를 불러요.
curl -H "Authorization: Bearer hdk_여기에_키" \
"https://hate.ssogari.dev/api/v1/expressions?q=%EB%A7%98%EC%B6%A9"JavaScript로 부를 때는 이렇게 써요.
const res = await fetch('https://hate.ssogari.dev/api/v1/expressions?q=' + encodeURIComponent('맘충'), {
headers: { Authorization: `Bearer ${process.env.HATEDICT_API_KEY}` },
});
const { data, meta } = await res.json();키 보내기
키는 Authorization: Bearer 키 헤더로 보내요. X-API-Key: 키 헤더도 받아요. 주소 뒤에 붙이면 받지 않아요. 주소는 접속 기록과 브라우저 기록에 남기 때문이에요.
키는 비밀번호처럼 다뤄 주세요. 웹 페이지의 자바스크립트나 공개 저장소에 넣으면 누구나 가져다 쓸 수 있어요. 서버에서 부르세요. 새어 나갔다면 내 정보에서 바로 폐기한 뒤 새로 만드세요.
주소와 응답
모든 주소는 https://hate.ssogari.dev/api/v1로 시작해요. 응답에는 사전에 실린(공개된) 항목만 들어가요.
GET /expressions: 찾기와 목록
표제어와 다른 이름, 설명에서 찾아요. 검색어 없이 부르면 최근에 실린 순서로 보여 줘요.
| 값 | 뜻 | 기본값 |
|---|---|---|
q | 검색어(200자까지) | 없음 |
type | 혐오 유형 코드. 분류 목록 참고 | 전체 |
sort | match(맞는 정도) 또는 alpha(가나다순) | match |
page | 쪽 번호(1~500) | 1 |
per_page | 한 쪽에 담을 수(1~100) | 20 |
{
"data": [
{
"id": 12,
"term": "맘충",
"aliases": [],
"type": {
"code": "dehumanization",
"label": "비인격적 비유"
},
"summary": "…",
"description": "…",
"content_warnings": [],
"url": "https://hate.ssogari.dev/dict/12"
}
],
"meta": {
"total": 1,
"page": 1,
"per_page": 20,
"total_pages": 1
},
"license": {
"name": "CC BY-SA 4.0",
"url": "https://creativecommons.org/licenses/by-sa/4.0/deed.ko"
}
}GET /expressions/{id}: 항목 하나
목록에 없는 뜻풀이, 생겨난 배경, 쓰임, 바꿔 쓸 말까지 담아요. summary는 AI가 만들고 편집자가 다듬는 한 줄 요약이에요(없으면 null). 본문은 마크다운이에요. context_needed가 true면 맥락에 따라 문제가 되는 표현이에요.
{
"data": {
"id": 12,
"term": "맘충",
"aliases": [],
"type": {
"code": "dehumanization",
"label": "비인격적 비유",
"description": "사람을 동물·곤충 등에 빗대어 부르며 생명의 위계를 나누는 표현"
},
"summary": "…",
"description": "…",
"origin": "…",
"usage": "…",
"alternatives": "…",
"context_needed": false,
"content_warnings": [],
"url": "https://hate.ssogari.dev/dict/12",
"created_at": "2026-11-01T00:00:00+00:00",
"updated_at": "2026-11-01T00:00:00+00:00"
},
"license": {
"name": "CC BY-SA 4.0",
"url": "https://creativecommons.org/licenses/by-sa/4.0/deed.ko"
}
}GET /categories: 분류
혐오 유형 6가지와 콘텐츠 경고 분류의 코드, 이름, 설명을 돌려줘요.
사용 한도
한도는 키를 만든 계정의 역할에 따라 달라요. 하루 사용량은 한국 시간 오전 9시(UTC 자정)에 다시 채워져요.
| 계정 | 1분에 | 하루에 |
|---|---|---|
| 회원 | 60번 | 1,000번 |
| 편집자 | 120번 | 5,000번 |
같은 항목을 자주 부른다면 응답을 저장해 두고 쓰세요. 더 많이 써야 한다면 admin@ssogari.dev로 쓰임새를 알려 주세요.
오류
실패하면 HTTP 상태 코드와 함께 아래 모양으로 답해요. 분기는 code로 하고 message는 사람에게 보여 줄 한국어 안내예요.
{
"error": {
"code": "invalid_key",
"message": "API 키가 맞지 않거나 폐기됐어요."
}
}| 상태 | code | 뜻 |
|---|---|---|
| 401 | missing_key | 키를 보내지 않았어요. |
| 401 | invalid_key | 키가 틀렸거나 폐기됐어요. |
| 403 | owner_restricted | 키를 만든 계정의 이용이 제한됐어요. |
| 404 | not_found | 항목이 없거나 공개되지 않았어요. |
| 429 | minute_limit, daily_limit | 사용 한도를 넘었어요. Retry-After 헤더의 초만큼 기다린 뒤 다시 부르세요. |
| 429 | too_many_invalid_keys | 틀린 키로 너무 자주 요청했어요. 10분 동안 막혀요. |
| 503 | maintenance | 사이트를 점검하는 중이에요. |
| 500 | server_error | 서버에서 문제가 생겼어요. |
콘텐츠 경고를 지켜 주세요
content_warnings가 비어 있지 않은 항목에는 성폭력, 자해처럼 읽는 사람에게 힘들 수 있는 내용이 들어 있어요. 사이트에서는 이런 항목을 펼치기 전에 경고를 먼저 보여 줘요. 여러분의 프로그램에서도 표제어와 설명을 바로 보여 주지 말고 경고 분류를 먼저 알린 뒤 읽을지 고르게 해 주세요.
이 사전은 차별·혐오 표현이 어떻게 집단을 깎아내리고 차별을 굳히는지 알리려고 만들었어요. 받은 내용을 놀림거리로 쓰거나 표현을 퍼뜨리는 데 쓰지 말아 주세요.
라이선스와 출처
사전의 내용은 CC BY-SA 4.0 라이선스를 따라요. 다시 쓸 때는 사전 이름과 항목 주소(url)를 출처로 밝히고 고쳐 쓴 결과물도 같은 조건으로 공유해 주세요. API를 쓰면 이용약관의 API 조항에 동의한 것으로 봐요.