API Documentation

Simple, straightforward API for sending push notifications to your team.

Quick Start

Your API endpoint:

https://www.tinyowl.io/api/webhook/YOUR_TEAM_ID

Replace YOUR_TEAM_ID with your actual team ID. Sign up to get started.

Example request:

curl -X POST https://www.tinyowl.io/api/webhook/YOUR_TEAM_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Message",
    "body": "Hello from the API!"
  }'

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API keys from the API Keys page after signing up.

Request Body

Required Fields

title(string, max 200 chars) - Notification title

body(string, max 500 chars) - Notification message

Optional Fields

sound(string) - Notification sound. Default: team default sound

groups(array of strings) - Group slugs to target. Pro+ only. Example: ["engineering", "sales"]

Examples

Basic Notification

{
  "title": "New Task Assigned",
  "body": "You have a new task waiting for you."
}

With Custom Sound

{
  "title": "Payment Received",
  "body": "A new payment has been processed.",
  "sound": "correct"
}

Targeting Specific Groups

{
  "title": "Team Update",
  "body": "New sprint planning scheduled.",
  "groups": ["engineering", "product"]
}

Use the group slugs from your team groups. Groups are created and managed in the Groups page. Pro+ only.

Response

Successful responses return a 200 status with:

{
  "id": "notification_id",
  "status": "delivered",
  "title": "New Message",
  "body": "Hello from the API!",
  "sound": "default",
  "channels": {
    "push": true,
    "slack": false,
    "discord": false
  },
  "devices_reached": 5,
  "created_at": "2024-01-16T10:30:00Z"
}

Available Sounds

Use these sound IDs in the sound field:

default

Device default

arabian

🎪 Arabian Harp

bubble

🫧 Bubble Pop

correct

✓ Correct Answer

elevator

🏢 Elevator

fairy

✨ Fairy Sparkle

flute

🎺 Flute Melody

glitter

💫 Glitter

hammer

🔨 Hammer Hit

kitty

🐱 Kitty Meow

lock

🔒 Gaming Lock

longpop

💥 Long Pop

magic

🪄 Magic Ring

marimba

🎹 Magic Marimba

select

🎯 Interface Select

spell

🔮 Light Spell

tile

🧩 Tile Reveal

Admin Endpoints

These endpoints require a production API key (not staging). Use these to retrieve team information programmatically.

List Team Members

GET https://www.tinyowl.io/api/webhook/YOUR_TEAM_ID/members

Returns a list of team members with their email addresses, subgroups (group slugs), and date joined.

curl -X GET "https://www.tinyowl.io/api/webhook/YOUR_TEAM_ID/members" \
  -H "Authorization: Bearer YOUR_PRODUCTION_API_KEY"

Example response:

[
  {
    "email": "user@example.com",
    "subgroups": ["engineering", "backend"],
    "joined_at": "2024-01-16T10:30:00Z"
  },
  {
    "email": "another@example.com",
    "subgroups": [],
    "joined_at": "2024-01-15T08:00:00Z"
  }
]

List Team Groups

GET https://www.tinyowl.io/api/webhook/YOUR_TEAM_ID/groups

Returns a list of all subgroups (groups) in the team with their slugs, names, emojis, and member counts.

curl -X GET "https://www.tinyowl.io/api/webhook/YOUR_TEAM_ID/groups" \
  -H "Authorization: Bearer YOUR_PRODUCTION_API_KEY"

Example response:

[
  {
    "slug": "engineering",
    "name": "Engineering",
    "emoji": "⚙️",
    "member_count": 5
  },
  {
    "slug": "sales",
    "name": "Sales",
    "emoji": "💰",
    "member_count": 3
  }
]

Error Responses

401 Unauthorized

Invalid or missing API key

400 Bad Request

Invalid request body or missing required fields

403 Forbidden

API key does not belong to this team, feature requires higher tier, or admin endpoints require production API key (not staging)

429 Too Many Requests

Rate limit exceeded