페이지 이동경로

문서>
REST API>
레퍼런스

REST API

레퍼런스

이 문서는 카카오디벨로퍼스에서 제공하는 REST API의 규격 정보를 안내합니다.

요청

카카오 플랫폼의 API 요청 규격을 구성하는 요소는 아래와 같습니다.

구성 요소	설명
메서드(Method)	카카오 API 호출 시 사용해야 할 HTTP 요청 메서드입니다. (예: `GET`, `POST`, `PUT`, `DELETE`)
호스트(Host)	요청을 받는 카카오 API 서버의 도메인입니다. (예: `kapi.kakao.com`)
URL	API로 제공하는 리소스마다 지정된 요청 경로입니다. 호스트와 함께 각 API의 엔드포인트(Endpoint)를 구성합니다. (예: `/v2/user/me`)
헤더(Header)	카카오 API 호출 시 필요한 인증 정보(Authorization)나 기타 추가 정보를 전달하는 데 사용합니다. 인증 정보는 액세스 토큰 또는 앱 키를 사용합니다. 일부 카카오모먼트 API는 인증 정보와 함께 광고계정 ID를 헤더에 포함하여 호출해야 합니다. (예: `Authorization: Bearer ${ACCESS_TOKEN}`)
경로 변수(Path variable)	카카오 API 호출 시, 사용자가 전달한 값을 포함해 URL을 구성할 때 사용합니다. 카카오모먼트 등 일부 카카오 API는 URL에 경로 변수를 포함합니다. (예: `/openapi/v4/campaigns/${id}`)
파라미터(Parameter)	요청 처리에 필요한 데이터를 전달하는 데 사용합니다. 파라미터는 키와 값의 쌍으로 구성되며, 쿼리 문자열(Query string) 또는 본문으로 전달합니다. 각 파라미터는 자료형(Data type)과 필수 전달 여부가 지정돼 있습니다.

각 API의 요청 규격이 다르므로, API별 개발 문서에서 상세 정보를 확인하고 호출해야 합니다. 요구 사양을 함께 참고합니다.

참고: 보안 설정

서비스의 필요에 따라 보안 강화 요소로 호출 허용 IP 주소나 클라이언트 시크릿(Client Secret) 설정을 사용할 수 있습니다.

응답

응답 형식

카카오 플랫폼은 API 요청에 대해 응답 코드와 응답 필드로 구성된 응답을 제공합니다. 응답 필드는 각 API의 호스트 및 요청 성공 여부에 따라 구성이 다릅니다.

요청 성공 시: HTTP 상태 코드 및 API별 성공 응답 필드 반환
요청 실패 시: HTTP 상태 코드 및 JSON 형식의 에러 응답 필드 반환, 에러 응답 필드에 에러 코드 및 메시지 포함

아래는 주요 호스트의 에러 응답 필드 구성 및 예시입니다.

kauth.kakao.com

이름	타입	설명	필수
error	`String`	에러 코드 에러 코드에서 상세 정보 확인 가능	X
error_description	`String`	실패 원인을 나타내는 에러 메시지 에러 원인에 대한 참고 정보로써 변경될 수 있으므로, 예외 처리 시에는 에러 코드를 사용해야 함	X

kapi.kakao.com

이름	타입	설명	필수
code	`Int`	에러 코드	X
msg	`String`	에러 메시지 에러 원인에 대한 참고 정보로써 변경될 수 있으므로, 예외 처리 시에는 에러 코드를 사용해야 함	X

예: [앱] > [어드민 키] > [사용 가능 API]에서 허용하지 않은 API를 호출한 경우

HTTP/1.1 403 Forbidden
{
  "msg": "This api is not allowed by using app_key(${APP_KEY}).",
  "code": -3
}

예: 토큰이 잘못되었을 경우

HTTP/1.1 401 Unauthorized  
WWW-Authenticate: Bearer error=invalid_token
{
  "code":-401,
  "msg":"InvalidTokenException"
}

예: API의 허용된 요청 회수 초과

HTTP/1.1 400 Bad Request  
{
  "code":-10,
  "msg":"API limit has been exceeded."
}

예: 카카오톡 메시지 발송 기능 접근 권한이 없어 전송 실패

HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "TALK_MEMO_DEFAULT_SEND",
  "required_scopes": [
    "talk_message"
  ],
  "allowed_scopes": [
    "profile",
    "account_email"
  ]
}

참고: 에러 코드와 에러 메시지

code는 특별한 규칙을 가지고 있지 않은 음수의 숫자이고, 실패 원인을 나타내는 msg는 요청에 따라 의미가 바뀌지 않는 범위에서 내용이 바뀔 수 있습니다. 예를 들어, code가 -401일 경우 전달되는 msg의 내용은 아래와 같이 다양하게 전달됩니다.

예: 유효하지 않은 앱키나 액세스 토큰으로 요청한 경우

"this access token does not exist", "this access token is already expired", "appKey(xxxxxxxx) is already deactivated"

예: 앱 관리 페이지의 [앱] > [플랫폼 키] > [JavaScript 키] > [JavaScript SDK 도메인]에 등록되지 않은 도메인에서 API를 호출한 경우

"domain mismatched! caller=xxxxxxxx. check out registered web domains."

예: 앱 관리 페이지의 [앱] > [플랫폼 키] > [네이티브 앱 키]에 등록된 정보와 클라이언트의 정보가 맞지 않을 경우

"android keyhash mismatched! caller=xxxxxxxx. check out registered keyhash."
"ios bundle id mismatched! caller=xxxxxxxx. check out registered bundle id."

예: [호출 허용 IP 주소] 설정에 해당하는 IP에서 요청하지 않았을 경우

"ip mismatched! callerIp=xxxxxxxx. check out registered ips."

응답 코드

응답 코드는 요청에 대한 상태를 나타내는 HTTP 상태 코드(Status code), 에러에 대한 정보를 담은 에러 코드(Error code)로 나뉩니다. 요청 성공 시 HTTP 상태 코드 200과 함께 요청에 대한 응답 본문(response body)이 반환되고, 요청이 실패한 경우 code와 msg로 이루어진 에러 코드를 반환합니다.

HTTP 상태 코드

HTTP 상태 코드(HTTP Status code)란 응답 메시지의 첫 번째 줄에 나타나는 세 자리 숫자의 코드로 요청에 대한 상태 정보(성공 또는 실패)를 나타냅니다. 상태 코드는 크게 5가지로 분류되며, 상태 코드의 첫 번째 숫자로 응답의 종류를 파악할 수 있습니다. 자세한 정보는 RFC 2616을 참고합니다.

아래는 카카오 플랫폼이 API 요청에 대해 응답하는 상태 코드의 종류와 의미입니다.

상태 코드	상태	설명
200 OK	성공	서버가 클라이언트의 요청을 성공적으로 수행 응답 본문의 경우 각 API별로 응답 본문의 형식이 다를 수 있으므로, 자세한 내용은 각 API별 상세 설명을 참고합니다.
400 Bad Request	실패	일반적인 오류 주로 API에 필요한 필수 파라미터와 관련하여 서버가 클라이언트 오류를 감지해 요청을 처리하지 못한 상태입니다.
401 Unauthorized	실패	인증 오류(주로 토큰 관련) 해당 리소스에 유효한 인증 자격 증명이 없어 요청에 실패한 상태입니다. 응답은 OAuth 2.0 RFC6750 표준 규격에 따라 헤더에 오류 정보를 포함합니다. 토큰 사용 시: `WWW-Authenticate: Bearer error=invalid_token` 서비스 앱 어드민 키 사용 시: `WWW-Authenticate: KakaoAK error=invalid_token` 상세 오류 정보는 응답 본문에서 확인할 수 있습니다.
403 Forbidden	실패	권한 오류 서버에 요청이 전달되었지만, 권한 때문에 거절된 상태입니다.
429 Too Many Request	실패	쿼터 초과(Daum 검색, 로컬, 모먼트, 키워드광고 API에만 해당) 정해진 사용량이나 초당 요청 한도를 초과한 경우
500 Internal Server Error	실패	시스템 오류 서버 에러를 총칭하는 에러 코드로, 요청을 처리하는 과정에서 서버가 예상하지 못한 상황에 놓인 상태입니다.
502 Bad Gateway	실패	시스템 오류 서로 다른 프로토콜을 연결해주는 게이트웨이가 잘못된 프로토콜을 연결하거나 연결된 프로토콜에 문제가 있어 통신이 제대로 되지 않은 상태입니다.
503 Service Unavailable	실패	서비스 점검중 서버가 요청을 처리할 준비가 되지 않은 상태입니다.

에러 코드

에러 코드를 참고합니다.

API 목록

카카오 플랫폼에서 REST API로 제공하는 API 목록과 기본적인 요청 규격 정보입니다.

카카오 로그인

URL	호스트	메서드	기능
/oauth/authorize	kauth.kakao.com	GET	인가 코드 요청 동의항목 추가 동의 요청 서비스 약관 선택해 동의 요청 카카오톡에서 자동 로그인
/oauth/token	kauth.kakao.com	POST	토큰 요청, 토큰 갱신
/.well-known/openid-configuration	kauth.kakao.com	GET	OIDC: 메타데이터 조회
/.well-known/jwks.json	kauth.kakao.com	GET	OIDC: 공개키 목록 조회
/oauth/tokeninfo	kauth.kakao.com	POST	OIDC: ID 토큰 정보 조회
/v1/user/logout	kapi.kakao.com	POST	로그아웃
/v1/user/signup	kapi.kakao.com	POST	수동 연결
/v1/user/unlink	kapi.kakao.com	POST	연결 해제
/v1/user/access_token_info	kapi.kakao.com	GET	액세스 토큰 정보 조회
/v2/user/me	kapi.kakao.com	GET/POST	사용자 정보 조회
/v1/user/update_profile	kapi.kakao.com	POST	사용자 프로퍼티 저장
/v1/user/shipping_address	kapi.kakao.com	GET	배송지 조회
/v1/user/ids	kapi.kakao.com	GET/POST	사용자 목록 조회
/v2/app/users	kapi.kakao.com	GET	여러 사용자 정보 조회
/v2/user/scopes	kapi.kakao.com	GET	동의항목 동의 내역 조회
/v2/user/revoke/scopes	kapi.kakao.com	POST	동의항목 동의 철회
/v2/user/service_terms	kapi.kakao.com	GET	서비스 약관 동의 내역 조회
/v2/user/revoke/service_terms	kapi.kakao.com	POST	서비스 약관 동의 철회
/v2/user/upgrade/service_terms	kapi.kakao.com	POST	서비스 약관에 동의
/v1/oidc/userinfo	kapi.kakao.com	GET	OIDC: 사용자 정보 조회

카카오톡 소셜

URL	호스트	메서드	기능
/v1/api/talk/profile	`https://kapi.kakao.com`	GET	카카오톡 프로필 조회
/v1/api/talk/friends	`https://kapi.kakao.com`	GET	카카오톡 친구 목록 조회
/v2/api/talk/profiles	`https://kapi.kakao.com`	GET/POST	사용자 목록으로 카카오톡 프로필 조회

카카오톡 메시지

URL	호스트	메서드	기능
/v2/api/talk/memo/default/send	kapi.kakao.com	POST	나에게 기본 템플릿으로 메시지 발송
/v2/api/talk/memo/send	kapi.kakao.com	POST	나에게 사용자 정의 템플릿으로 메시지 발송
/v2/api/talk/memo/scrap/send	kapi.kakao.com	POST	나에게 스크랩 메시지 발송
/v1/api/talk/friends/message/default/send	kapi.kakao.com	POST	기본 템플릿으로 메시지 발송
/v1/api/talk/friends/message/send	kapi.kakao.com	POST	사용자 정의 템플릿으로 메시지 발송
/v1/api/talk/friends/message/scrap/send	kapi.kakao.com	POST	스크랩 메시지 발송

카카오톡 채널

URL	호스트	메서드	기능
/v2/api/talk/channels	kapi.kakao.com	GET	카카오톡 채널 관계 조회
/v2/api/talk/channels/multi	kapi.kakao.com	GET	여러 사용자 카카오톡 채널 관계 조회
/v1/talkchannel/create/target_user_file	kapi.kakao.com	POST	고객 관리: 고객파일 등록
/v1/talkchannel/target_user_file	kapi.kakao.com	GET	고객 관리: 고객파일 조회
/v1/talkchannel/update/target_users	kapi.kakao.com	POST	고객 관리: 고객파일에 사용자 추가
/v1/talkchannel/delete/target_users	kapi.kakao.com	POST	고객 관리: 고객파일의 사용자 삭제

비즈니스 인증

URL	호스트	메서드	기능
/oauth/business/authorize	kauth.kakao.com	GET	비즈니스 인가 코드 요청
/oauth/business/token	kauth.kakao.com	POST	비즈니스 토큰 요청
/oauth/business/tokeninfo	kauth.kakao.com	GET	비즈니스 토큰 정보 조회
/oauth/business/userinfo	kauth.kakao.com	GET	비즈니스 사용자 정보 조회
/oauth/business/revoke	kauth.kakao.com	POST	비즈니스 토큰 발급 철회

카카오모먼트

카카오모먼트 API 레퍼런스를 참고합니다.

카카오 키워드광고

카카오 키워드광고 API 레퍼런스를 참고합니다.

푸시 알림

URL	호스트	메서드	기능
/v2/push/register	kapi.kakao.com	POST	푸시 토큰 등록
/v2/push/tokens	kapi.kakao.com	GET	푸시 토큰 조회
/v2/push/deregister	kapi.kakao.com	POST	푸시 토큰 삭제
/v2/push/send	kapi.kakao.com	POST	푸시 알림 발송

톡캘린더

URL	호스트	메서드	기능
/v2/api/calendar/calendars	kapi.kakao.com	GET	사용자 캘린더 > 목록 조회
/v2/api/calendar/create/calendar	kapi.kakao.com	POST	사용자 캘린더 > 서브 캘린더 생성
/v2/api/calendar/update/calendar	kapi.kakao.com	POST	사용자 캘린더 > 서브 캘린더 수정
/v2/api/calendar/delete/calendar	kapi.kakao.com	DELETE	사용자 캘린더 > 서브 캘린더 삭제
/v2/api/calendar/create/event	kapi.kakao.com	POST	일반 일정 > 생성
/v2/api/calendar/events	kapi.kakao.com	GET	일반 일정 > 목록 조회
/v2/api/calendar/event	kapi.kakao.com	GET	일반 일정 > 상세 조회
/v2/api/calendar/update/event/host	kapi.kakao.com	POST	일반 일정 > 수정
/v2/api/calendar/delete/event	kapi.kakao.com	DELETE	일반 일정 > 삭제
/v2/api/calendar/public/create/event	kapi.kakao.com	POST	공개 일정 > 생성
/v2/api/calendar/public/events	kapi.kakao.com	GET	공개 일정 > 목록 조회
/v2/api/calendar/public/event	kapi.kakao.com	GET	공개 일정 > 상세 조회
/v2/api/calendar/public/update/event	kapi.kakao.com	POST	공개 일정 > 수정
/v2/api/calendar/public/delete/event	kapi.kakao.com	DELETE	공개 일정 > 삭제
/v2/api/calendar/public/follow	kapi.kakao.com	POST	공개 일정 > 사용자 캘린더에 추가
/v2/api/calendar/subscribable/calendars	kapi.kakao.com	GET	구독 캘린더 > 구독 가능 캘린더 목록 조회
/v2/api/calendar/subscribe	kapi.kakao.com	POST	구독 캘린더 > 구독
/v2/api/calendar/unsubscribe	kapi.kakao.com	DELETE	구독 캘린더 > 구독 해제
/v2/api/calendar/update/event/guest	kapi.kakao.com	POST	게스트 일정 > 수정
/v2/api/calendar/holidays	kapi.kakao.com	GET	공휴일 및 주요 기념일 조회
/v1/api/calendar/create/task	kapi.kakao.com	POST	할 일 > 생성
/v1/api/calendar/tasks	kapi.kakao.com	GET	할 일 > 조회
/v1/api/calendar/task/records	kapi.kakao.com	GET	할 일 > 도전 기록 조회
/v1/api/calendar/update/task	kapi.kakao.com	POST	할 일 > 수정
/v1/api/calendar/complete/task	kapi.kakao.com	POST	할 일 > 완료 여부 설정
/v1/api/calendar/delete/task	kapi.kakao.com	DELETE	할 일 > 삭제

로컬

URL	호스트	메서드	기능
/v2/local/search/address.{format}	dapi.kakao.com	GET	주소로 좌표 변환
/v2/local/geo/coord2regioncode.{format}	dapi.kakao.com	GET	좌표로 행정구역정보 변환
/v2/local/geo/coord2address.{format}	dapi.kakao.com	GET	좌표로 주소 변환
/v2/local/geo/transcoord.{format}	dapi.kakao.com	GET	좌표계 변환
/v2/local/search/keyword.{format}	dapi.kakao.com	GET	키워드로 장소 검색
/v2/local/search/category.{format}	dapi.kakao.com	GET	카테고리로 장소 검색

Daum 검색

URL	호스트	메서드	기능
/v2/search/web	dapi.kakao.com	GET	웹문서 검색
/v2/search/vclip	dapi.kakao.com	GET	동영상 검색
/v2/search/image	dapi.kakao.com	GET	이미지 검색
/v2/search/blog	dapi.kakao.com	GET	블로그 검색
/v3/search/book	dapi.kakao.com	GET	책 검색
/v2/search/cafe	dapi.kakao.com	GET	카페 검색

사용자 편의 API

URL	호스트	메서드	기능
/v1/system/ips	kapi.kakao.com	GET	카카오 IP 목록 조회
/api/health/current	api-status.kakao.com	GET	현재 상태 조회
api/health/history	api-status.kakao.com	GET	이력 조회

REST API> 레퍼런스

요청
응답
- 응답 형식
- 응답 코드
API 목록

menu

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기