API Overview

WhookTown provides REST APIs for integrating with your monitoring tools and automation systems.

Base URLs

Service	URL
Sensor API	`https://sensor.whook.town`
UI API	`https://api.whook.town`
Auth API	`https://auth.whook.town`

Authentication

All API requests require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer <your-token>" \
  https://sensor.whook.town/sensors

Getting a Token

Log in to app.whook.town
Go to Settings
Create a new API token
Select the appropriate token type

Token Types

Type	Permissions
`user`	Full access to all APIs
`sensor`	Sensor write only (recommended for integrations)
`viewer`	Read-only access

Available APIs

Sensor API

Send real-time data to update building states.

Endpoint: POST /sensors

Full documentation →

UI API

Manage layouts, camera, and traffic.

Endpoint	Method	Description
`/ui/layout`	POST	Update layout
`/ui/layout/:id`	DELETE	Delete layout
`/ui/traffic/command`	POST	Traffic control
`/ui/camera/command`	POST	Camera control
`/ui/popup/command`	POST	Popup control

Auth API

Account and token management.

Endpoint	Method	Description
`/auth/signup`	POST	Create account
`/auth/login`	POST	Request login link
`/auth/check/:token`	GET	Validate token

Response Format

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided token is invalid or expired"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request (invalid input)
401	Unauthorized (invalid/missing token)
403	Forbidden (insufficient permissions)
404	Not Found
429	Too Many Requests (rate limited)
500	Internal Server Error

Rate Limiting

API requests are rate limited per token:

Plan	Requests/minute
Free	60
Starter	300
Premium	1000

When rate limited, you'll receive a 429 response with a Retry-After header.

Webhooks

WhookTown can send webhooks for certain events. Contact support to configure webhooks for your account.

SDKs

Official

CLI: wt command-line tool (Go)
Go SDK: github.com/whooktown/whooktown-golang-sdk

Community

Check the WhookTown GitHub for community-contributed SDKs.

Best Practices

Use Sensor Tokens

For monitoring integrations, always use sensor type tokens. They have minimal permissions, reducing risk if compromised.

Handle Rate Limits

Implement exponential backoff when you receive 429 responses:

import time

def send_with_retry(data, max_retries=3):
    for attempt in range(max_retries):
        response = send_request(data)
        if response.status_code != 429:
            return response
        wait_time = 2 ** attempt
        time.sleep(wait_time)
    raise Exception("Rate limited")

Batch Updates

If updating multiple buildings, consider spacing requests or using workflows for automatic updates.

Secure Your Tokens

Never commit tokens to version control
Use environment variables
Rotate tokens periodically
Revoke immediately if compromised