API Documentation

Learn how to send push notifications programmatically using the Chirpme API.

Overview

The Chirpme API allows you to send push notifications to your channel subscribers programmatically. All API requests require authentication using an API key.

Base URL

https://chirpme.app/api

Authentication

All API requests must include your API key in the Authorization header using the Bearer token format.

Authorization: Bearer YOUR_API_KEY

Keep your API key secure

Never expose your API key in client-side code or public repositories. Use environment variables or secure key management systems.

API Key Types

Account Keys - Can send to any channel in your account
Channel Keys - Restricted to a specific channel only

POST/api/send

Send a push notification to channel subscribers

Required Parameters

Parameter	Type	Description
`channelId`	string	The unique identifier of the channel to send the notification to.
`title`	string	The notification title. Keep it short and attention-grabbing (max 65 characters recommended).
`body`	string	The notification body text. This is the main message content (max 240 characters recommended).

Optional Parameters

Parameter	Type	Description
`url`	string	A URL to open when the user taps the notification. Can be a deep link or web URL.
`detail`	string	Rich HTML content for the in-app detail view. Supports basic HTML tags for formatting.
`imageUrl`	string	URL of an image to display with the notification. Should be HTTPS and publicly accessible.
`scheduledAt`	string (ISO 8601)	Schedule the notification for future delivery. Use ISO 8601 format (e.g., '2025-01-15T10:00:00Z').

iOS-Specific Parameters

Parameter	Type	Description
`badge`	number	The badge number to display on the app icon. Set to 0 to clear the badge.
`sound`	string	The sound to play. Use 'default' for the default notification sound, or a custom sound file name.
`category`	string	iOS notification category identifier for custom actions.
`threadId`	string	Thread identifier for grouping related notifications together.

Android-Specific Parameters

Parameter	Type	Description
`channelName`	string	Android notification channel name. Creates a new channel if it doesn't exist.
`priority`	string	Notification priority. Options: 'default', 'low', 'high', 'max'.
`icon`	string	Custom notification icon identifier (Android legacy).
`color`	string	Notification accent color as hex (e.g., '#2dd4bf').
`tag`	string	Tag for replacing/updating existing notifications with the same tag.

Customization Parameters

Parameter	Type	Description
`notificationIcon`	string	Override the channel icon. Can be a Material Symbol name or an image URL.
`notificationIconType`	string	Type of notification icon. Options: 'material' (Material Symbol name) or 'url' (image URL).
`suggestedSubTab`	string	Suggest a sub-tab name for organizing this notification in the mobile app.
`suggestedSubTabColor`	string	Color for the suggested sub-tab as hex (e.g., '#3498db').

GET/api/channels

List all channels in your account

Returns a list of all channels owned by the authenticated user. Requires an account-scoped API key.

Example Response

{
  "success": true,
  "channels": [
    {
      "id": "abc123xyz",
      "name": "Product Updates",
      "description": "Get notified about new features",
      "code": "PROD-2024",
      "subscriberCount": 150,
      "notificationCount": 42,
      "isPasswordProtected": false,
      "isPublic": false,
      "createdAt": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Note: Channel-scoped API keys cannot list channels. Use an account-scoped key.

POST/api/channels

Create a new notification channel

Required Parameters

Parameter	Type	Description
`name`	string	The channel name. Must be between 2 and 100 characters.
`description`	string	Channel description. Must be between 10 and 500 characters.

Optional Parameters

Parameter	Type	Description
`code`	string	Custom channel code (3-20 characters, uppercase letters, numbers, and hyphens). Auto-generated if not provided.
`password`	string	Password to protect the channel. Subscribers will need this to join.
`icon`	string	Channel icon. Can be a Material Symbol name or an image URL.
`iconType`	string	Type of icon. Options: 'material' (default) or 'url'.
`isPublic`	boolean	Whether the channel is discoverable in the mobile app. Default: false.
`suggestedTab`	string	Suggested tab name for organizing this channel in mobile apps.
`suggestedTabColor`	string	Color for the suggested tab as hex (e.g., '#2dd4bf').

Example Response

{
  "success": true,
  "channel": {
    "id": "abc123xyz",
    "name": "Product Updates",
    "description": "Get notified about new features",
    "code": "PROD-2024",
    "subscriberCount": 0,
    "notificationCount": 0,
    "isPasswordProtected": false,
    "isPublic": false,
    "createdAt": "2025-01-08T10:30:00.000Z"
  }
}

Note: Channel-scoped API keys cannot create channels. Use an account-scoped key.

Response Format

Success Response (200)

{
  "success": true,
  "notification": {
    "id": "abc123xyz",
    "channelId": "your-channel-id",
    "status": "sent",
    "scheduledAt": null,
    "sentAt": "2025-01-07T10:30:00.000Z"
  }
}

Error Response

{
  "error": "Error message describing what went wrong"
}

Error Codes

Code	Name	Description
400	Bad Request	Missing required fields (channelId, title, body).
401	Unauthorized	Missing, invalid, or expired API key.
403	Forbidden	API key doesn't have permission for the specified channel.
404	Not Found	The specified channel does not exist.
500	Internal Error	Server error. Please try again or contact support.

Code Examples

cURL

curl -X POST https://chirpme.app/api/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "your-channel-id",
    "title": "Hello World",
    "body": "This is a test notification",
    "url": "https://example.com",
    "detail": "<p>Rich HTML content for detail view</p>",
    "imageUrl": "https://example.com/image.png",
    "scheduledAt": "2025-01-15T10:00:00Z",
    "badge": 1,
    "sound": "default",
    "priority": "high",
    "notificationIcon": "notifications",
    "notificationIconType": "material",
    "suggestedSubTab": "Updates",
    "suggestedSubTabColor": "#2dd4bf"
  }'

Node.js

const response = await fetch('https://chirpme.app/api/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    channelId: 'your-channel-id',
    title: 'Hello World',
    body: 'This is a test notification',
    url: 'https://example.com',
    detail: '<p>Rich HTML content for detail view</p>',
    imageUrl: 'https://example.com/image.png',
    scheduledAt: '2025-01-15T10:00:00Z',
    // iOS options
    badge: 1,
    sound: 'default',
    category: 'general',
    threadId: 'thread-123',
    // Android options
    priority: 'high',
    color: '#2dd4bf',
    tag: 'notification-tag',
    // Icon override
    notificationIcon: 'notifications',
    notificationIconType: 'material', // or 'url'
    // Sub-tab suggestion
    suggestedSubTab: 'Updates',
    suggestedSubTabColor: '#2dd4bf',
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    'https://chirpme.app/api/send',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'channelId': 'your-channel-id',
        'title': 'Hello World',
        'body': 'This is a test notification',
        'url': 'https://example.com',
        'detail': '<p>Rich HTML content for detail view</p>',
        'imageUrl': 'https://example.com/image.png',
        'scheduledAt': '2025-01-15T10:00:00Z',
        # iOS options
        'badge': 1,
        'sound': 'default',
        'category': 'general',
        'threadId': 'thread-123',
        # Android options
        'priority': 'high',
        'color': '#2dd4bf',
        'tag': 'notification-tag',
        # Icon override
        'notificationIcon': 'notifications',
        'notificationIconType': 'material',  # or 'url'
        # Sub-tab suggestion
        'suggestedSubTab': 'Updates',
        'suggestedSubTabColor': '#2dd4bf',
    }
)

data = response.json()
print(data)

C#

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");

var payload = new {
    channelId = "your-channel-id",
    title = "Hello World",
    body = "This is a test notification",
    url = "https://example.com",
    detail = "<p>Rich HTML content for detail view</p>",
    imageUrl = "https://example.com/image.png",
    scheduledAt = "2025-01-15T10:00:00Z",
    // iOS options
    badge = 1,
    sound = "default",
    category = "general",
    threadId = "thread-123",
    // Android options
    priority = "high",
    color = "#2dd4bf",
    tag = "notification-tag",
    // Icon override
    notificationIcon = "notifications",
    notificationIconType = "material", // or "url"
    // Sub-tab suggestion
    suggestedSubTab = "Updates",
    suggestedSubTabColor = "#2dd4bf"
};

var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(
    "https://chirpme.app/api/send",
    content
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Channel API Examples

cURL

curl -X POST https://chirpme.app/api/channels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Updates",
    "description": "Get notified about new features and product updates",
    "code": "PROD-2024",
    "icon": "notifications",
    "iconType": "material",
    "isPublic": false
  }'

Node.js

const response = await fetch('https://chirpme.app/api/channels', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Product Updates',
    description: 'Get notified about new features and product updates',
    code: 'PROD-2024',
    icon: 'notifications',
    iconType: 'material',
    isPublic: false,
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    'https://chirpme.app/api/channels',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Product Updates',
        'description': 'Get notified about new features and product updates',
        'code': 'PROD-2024',
        'icon': 'notifications',
        'iconType': 'material',
        'isPublic': False,
    }
)

data = response.json()
print(data)

C#

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");

var payload = new {
    name = "Product Updates",
    description = "Get notified about new features and product updates",
    code = "PROD-2024",
    icon = "notifications",
    iconType = "material",
    isPublic = false
};

var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

var response = await client.PostAsync(
    "https://chirpme.app/api/channels",
    content
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Ready to get started?

Create Free Account Try API Explorer