API Documentation

🎯 The Simple Version

Want to create reminders from your own app or script?

It's super easy! You just need two things:

Your 6-character API key (shown below when logged in)
A way to send web requests (like curl, Python, or any programming language)

Here's what you do:

Send a message to https://api.happymonday.com/functions/v1/create-event with:

Your 6-character API key in the Authorization header
The reminder text (like "get apples every tuesday at 4pm")

That's it! HappyMonday will understand your reminder with 95% name extraction accuracy and schedule it just like if you typed it on the website. Pushover notifications are handled automatically behind the scenes!

📚 Technical Details

Authentication

Include your 6-character API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Note: Your API key is the first 6 characters of your user profile ID.

Base URL

https://api.happymonday.com/functions/v1/

Endpoints

POST /create-event

Create a new reminder using natural language with enhanced parsing.

Request Body (JSON):

{
    "text": "get apples every tuesday at 4pm"
}

Response:

{
    "success": true,
    "event": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "get apples",
        "description": "get apples every tuesday at 4pm",
        "due_time": "2025-07-29T16:00:00.000Z",
        "status": "pending",
        "recurrence_pattern": "weekly",
        "recurrence_interval": 1,
        "recurrence_days": "tuesday"
    },
    "user": {
        "email": "user@example.com"
    },
    "parsing": {
        "input": "get apples every tuesday at 4pm",
        "extractedName": "get apples",
        "parsedDate": "2025-07-29T16:00:00.000Z"
    }
}

POST /acknowledge-window

Acknowledge a reminder time window.

Request Body (JSON):

{
    "timeWindowId": "time-window-id-from-notification",
    "action": "acknowledge"  // or "silence_event" or "mute_all"
}

Response:

{
    "success": true,
    "message": "Time window acknowledged successfully"
}

Actions:

acknowledge - Acknowledge this specific notification
silence_event - Silence all notifications for this event
mute_all - Mute all notifications for your account

Examples

Using curl

# Create reminder with natural language
curl -X POST https://api.happymonday.com/functions/v1/create-event \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "doctor appointment tomorrow at 2pm"}'

# Create recurring reminder
curl -X POST https://api.happymonday.com/functions/v1/create-event \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "take vitamins daily at 8am"}'

# Acknowledge a reminder
curl -X POST https://api.happymonday.com/functions/v1/acknowledge-window \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timeWindowId": "time-window-id", "action": "acknowledge"}'

Using Python

import requests

# Your 6-character API key
API_KEY = "YOUR_API_KEY"

# Create a reminder with natural language
response = requests.post(
    "https://api.happymonday.com/functions/v1/create-event",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "text": "team meeting every friday at 10am"
    }
)

if response.status_code == 200:
    result = response.json()
    print(f"Success! Created '{result['event']['name']}' due at {result['event']['due_time']}")
    if result['event']['recurrence_pattern']:
        print(f"Recurring: {result['event']['recurrence_pattern']} every {result['event']['recurrence_interval']} week(s)")
else:
    print(f"Error: {response.text}")

# You can also acknowledge reminders via API
response = requests.post(
    "https://api.happymonday.com/functions/v1/acknowledge-window",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "timeWindowId": "time-window-id-from-notification",
        "action": "acknowledge"
    }
)

if response.status_code == 200:
    print("Reminder acknowledged successfully!")
else:
    print(f"Error: {response.text}")

Using JavaScript/Node.js

// Your 6-character API key
const API_KEY = 'YOUR_API_KEY';

// Create a reminder with natural language
fetch('https://api.happymonday.com/functions/v1/create-event', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        text: 'water plants every sunday at 9am'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log(`Success! Created '${data.event.name}' due at ${data.event.due_time}`);
        if (data.event.recurrence_pattern) {
            console.log(`Recurring: ${data.event.recurrence_pattern} on ${data.event.recurrence_days || 'schedule'}`);
        }
    } else {
        console.error('Error:', data.error);
    }
})
.catch(error => console.error('Error:', error));

// Acknowledge a reminder via API
fetch('https://api.happymonday.com/functions/v1/acknowledge-window', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        timeWindowId: 'time-window-id-from-notification',
        action: 'acknowledge'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('Reminder acknowledged successfully!');
    } else {
        console.error('Error:', data.error);
    }
})
.catch(error => console.error('Error:', error));

Natural Language Examples

The API understands natural language with 95% name extraction accuracy and supports recurring events:

Enhanced Parsing Examples

"get apples every tuesday at 4pm" → "get apples" recurring weekly on Tuesdays
"take vitamins daily at 8am" → "take vitamins" recurring daily
"team meeting every friday at 10am" → "team meeting" recurring weekly on Fridays
"doctor appointment tomorrow at 2pm" → "doctor appointment" one-time event
"pay rent monthly on the 1st" → "pay rent" recurring monthly
"remind me to call mom in 30 minutes" → "call mom" one-time event

Recurring Patterns Supported

Daily: "daily", "every day"
Weekly: "weekly", "every week", "every [day]" (monday, tuesday, etc.)
Monthly: "monthly", "every month"
Weekdays: "every weekday" (Monday-Friday)
Weekends: "every weekend" (Saturday-Sunday)

Time Examples

"Doctor appointment tomorrow at 2pm"
"Take medication in 30 minutes"
"Birthday party on July 20 at 6pm"
"Call mom in 2 hours"
"Dentist appointment next Tuesday at 3:30pm"

Response Format

All successful responses include:

success: Boolean indicating success
event: The created event object with extracted name and parsed time
user: User information (email)
parsing: Details about how the text was parsed
authSystem: Authentication system used (Pushover Token Auth)

Error Responses

Status Code	Meaning	Example Response
200	Success	`{"success": true, ...}`
400	Bad request (missing text, parsing error)	`{"error": "Missing 'text' parameter"}`
401	Invalid or missing API key	`{"error": "Invalid API key"}`
403	Unauthorized access	`{"error": "Unauthorized: You can only acknowledge your own events"}`
500	Server error	`{"error": "Internal server error"}`

📱 Getting Your API Key

To find your API key:

Log in to HappyMonday
Your API key is shown at the top of this page when logged in
It's the first 6 characters of your user profile ID

💡 Your API key is just 6 characters - much shorter and easier than complex authentication tokens!

💡 Key Features

Why Use 6-Character API Keys:

Simpler: No need to manage complex API keys or user IDs
Short: Just 6 characters to remember
95% Name Extraction Accuracy: Correctly extracts task names from complex sentences
Recurring Event Support: Automatically detects and creates recurring reminders
Natural Language: Just type reminders like you would in the web app

Health Check

You can check if the API is running with a simple GET request:

curl -X POST https://api.happymonday.com/functions/v1/create-event \
  -H "Content-Type: application/json" \
  -d '{"test": "connectivity"}'

A 401 error indicates the API is running (just missing auth).

Rate Limits

There are no rate limits currently. Please be reasonable. 😊

Need Help?

Having trouble? The API works exactly like the web interface, so if you can create a reminder on the website, the same text will work via API! Just remember to use your 6-character API key for authentication.

Quick Start Summary

Get your API key: Log in to HappyMonday → Your key is shown on this page
Ready-to-use command:
curl -X POST https://api.happymonday.com/functions/v1/create-event -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"text": "test reminder in 1 hour"}'