개발자 문서

사전에 실린 표현을 다른 프로그램에서 불러올 수 있는 API예요. 키를 받아 HTTPS로 요청하면 JSON으로 답해요. 지금은 읽기만 할 수 있어요.

시작하기

  1. 회원으로 가입하고 로그인해요.
  2. 내 정보 › API 키에서 키를 만들어요. 키는 만들 때 한 번만 보여 주니 바로 복사해 두세요. 한 계정에 5개까지 만들 수 있어요.
  3. 요청 헤더에 키를 넣어 아래 주소를 불러요.
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혐오 유형 코드. 분류 목록 참고전체
sortmatch(맞는 정도) 또는 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뜻
401missing_key키를 보내지 않았어요.
401invalid_key키가 틀렸거나 폐기됐어요.
403owner_restricted키를 만든 계정의 이용이 제한됐어요.
404not_found항목이 없거나 공개되지 않았어요.
429minute_limit, daily_limit사용 한도를 넘었어요. Retry-After 헤더의 초만큼 기다린 뒤 다시 부르세요.
429too_many_invalid_keys틀린 키로 너무 자주 요청했어요. 10분 동안 막혀요.
503maintenance사이트를 점검하는 중이에요.
500server_error서버에서 문제가 생겼어요.

콘텐츠 경고를 지켜 주세요

content_warnings가 비어 있지 않은 항목에는 성폭력, 자해처럼 읽는 사람에게 힘들 수 있는 내용이 들어 있어요. 사이트에서는 이런 항목을 펼치기 전에 경고를 먼저 보여 줘요. 여러분의 프로그램에서도 표제어와 설명을 바로 보여 주지 말고 경고 분류를 먼저 알린 뒤 읽을지 고르게 해 주세요.

이 사전은 차별·혐오 표현이 어떻게 집단을 깎아내리고 차별을 굳히는지 알리려고 만들었어요. 받은 내용을 놀림거리로 쓰거나 표현을 퍼뜨리는 데 쓰지 말아 주세요.

라이선스와 출처

사전의 내용은 CC BY-SA 4.0 라이선스를 따라요. 다시 쓸 때는 사전 이름과 항목 주소(url)를 출처로 밝히고 고쳐 쓴 결과물도 같은 조건으로 공유해 주세요. API를 쓰면 이용약관의 API 조항에 동의한 것으로 봐요.