API Documentation version 1 deprecated


The HipChat API requires you to pass an auth_token variable with each request containing one of your API tokens. If the token is not provided or invalid you will receive a 401 response.

Where do I get a token?

Group admins may create them on the API Tokens page. They come in two flavors:

  • Admin - Has access to all API methods. Warning Note that admin tokens can't update the group owner's profile.
  • Notification - Only has access to the rooms/message and rooms/topic methods. Use for integrations with other sites.

Wire format

For example, if your token were 'YOUR_TOKEN', a request would look like:

GET /v1/rooms/list?auth_token=YOUR_TOKEN HTTP/1.1
Host: api.hipchat.com

Which would generate the response:

HTTP/1.1 200 OK
Date: Tue, 13 Apr 2010 22:16:11 GMT
Content-Type: application/json
Vary: Accept-Encoding
Content-Length: 90
Connection: close

  "rooms": [{
    "room_id": 5,
    "name": "Engineering",
    "last_active": 1271190087,
    "owner_user_id": 10

Note: auth_token may be passed in the POST data when making a POST request.

Usage examples


curl https://api.hipchat.com/v1/rooms/list?auth_token=YOUR_TOKEN


import urllib2

url = "https://api.hipchat.com/v1/rooms/list?auth_token=YOUR_TOKEN"
request = urllib2.Request(url)
response = urllib2.urlopen(request)

print response.read()


require 'net/http'
require 'uri'

url = "https://api.hipchat.com/v1/rooms/list?auth_token=YOUR_TOKEN"
puts Net::HTTP.get(URI.parse(url))


// using standard curl extension

$url = "https://api.hipchat.com/v1/rooms/list?auth_token=YOUR_TOKEN";
$c = curl_init();
curl_setopt($c, CURLOPT_URL, $url);
curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);

echo curl_exec($c);


use strict;
use warnings;
use WWW::Curl::Easy;

my $url = "https://api.hipchat.com/v1/rooms/list?auth_token=token";
my $response;
my $result;

my $curl = new WWW::Curl::Easy;
$curl->setopt(CURLOPT_URL, $url);
open (my $fileb, ">", \$response);
$curl->setopt(CURLOPT_WRITEDATA, $fileb);
$result = $curl->perform();


Note: We suggest using an existing client library to work with the API.

Testing a token

To test if an auth token has access to a given method, include auth_test=true. The method's normal actions (messaging a room, listing users, etc) will not be performed. So, given the request:

GET /v1/rooms/list?auth_token=YOUR_TOKEN&auth_test=true HTTP/1.1
Host: api.hipchat.com

If the token is valid a HTTP 202 response will be returned:

HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 101

  "success": {
    "code": 202,
    "type": "Accepted",
    "message": "This auth_token has access to use this method."

If the token does not have access to the method, a standard HTTP 401 error will be returned:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Content-Length: 131

  "error": {
    "code": 401,
    "type": "Unauthorized",
    "message": "Auth token invalid. Please see: https:\/\/www.hipchat.com\/docs\/api\/auth"