API Documentation

YouGot REST API

Integrate YouGot reminders directly into your applications. Available to Business tier subscribers.

Base URLhttps://yougot.ai

With the YouGot API you can create, schedule, and manage reminders delivered via email, SMS, WhatsApp, web push, or webhooks. Support for recurring schedules, nag mode, live data fetching, natural language parsing, tags, sharing, and analytics is included.

AI-Agent Ready

Full API docs available at /llms.txt for LLMs and AI coding agents

Open llms.txt

Authentication

All requests require a valid API key sent as a Bearer token in the Authorization header.

Go to Dashboard → API Keys to generate a key.
Include the key in every request as shown below.
Monitor usage via the X-RateLimit-Remaining response header.

curl https://yougot.ai/api/v1/reminders \
  -H "Authorization: Bearer yg_your_api_key_here"

Quick Start

Step 1 — Get your API key

Navigate to Dashboard → API Keys and create a new key. Copy it somewhere safe — it is only shown once.

Step 2 — Create your first reminder

curl -X POST https://yougot.ai/api/v1/reminders \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Review pull request from Anna",
    "scheduledAt": "2026-04-01T10:00:00Z",
    "channel": "email"
  }'

Step 3 — Verify it was created

curl https://yougot.ai/api/v1/reminders?status=pending \
  -H "Authorization: Bearer yg_your_api_key_here"

Create a Reminder

POST/api/v1/reminders— Create a new reminder

Field	Type	Required	Description
`message`	string	Yes	The reminder message text
`scheduledAt`	number \| string	Yes	Unix timestamp (ms) or ISO 8601 string
`channel`	string	No	"email", "sms", "whatsapp", "webhook", "web_push". Defaults to user's default
`additionalChannels`	string[]	No	Extra channels to deliver on simultaneously
`recurrence`	object	No	Recurring schedule (see below)
`tags`	string[]	No	Tags for organization, e.g. ["work", "meeting"]
`metadata`	object	No	Arbitrary key-value metadata
`nagMode`	object	No	Persistent nagging until acknowledged (see below)
`targetPhone`	string	No	Phone number for SMS/WhatsApp delivery (must be verified)
`targetWebhookId`	string	No	Webhook endpoint ID for webhook delivery
`dataFetch`	object	No	Live data to include at delivery time (see below)
`notifyBeforeMs`	number	No	Send notification early by this many milliseconds
`recipientIds`	string[]	No	User IDs to receive this reminder. Omit for a personal reminder. Any non-self recipient must be an active member of your group and requires a Plus or Business plan.

Recurrence Object

Field	Type	Required	Description
`type`	string	Yes	"daily", "weekly", "monthly", or "custom"
`interval`	number	No	Repeat every N periods (e.g. 2 = every other day)
`dayOfWeek`	number	No	Day of week for weekly: 0=Sun, 1=Mon, ... 6=Sat
`dayOfMonth`	number	No	Day of month for monthly: 1-31
`cronExpression`	string	No	Cron expression for custom schedules, e.g. "0 9 * * 1-5"
`intervalMs`	number	No	Interval in ms for sub-daily recurrence
`endDate`	number	No	Unix timestamp (ms) when recurrence stops
`description`	string	No	Human-readable label, e.g. "Every weekday at 9am"

The API automatically sanitizes recurrence input. If you pass dayOfWeek as an array, it will be converted to a cron expression using the hour from scheduledAt. For best results, use explicit cronExpression values.

Nag Mode Object

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable persistent nagging
`intervalMs`	number	No	Nag interval in ms (default: 300000 = 5 minutes)

Data Fetch Object

Field	Type	Required	Description
`type`	string	Yes	"crypto", "weather", "stock", or "web_search"
`query`	string	Yes	What to look up, e.g. "bitcoin", "New York", "AAPL"

# One-time email reminder
curl -X POST https://yougot.ai/api/v1/reminders \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Call the dentist",
    "scheduledAt": "2026-04-01T14:00:00Z",
    "channel": "email"
  }'

# Daily recurring with nag mode
curl -X POST https://yougot.ai/api/v1/reminders \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Take your medication",
    "scheduledAt": "2026-04-01T08:00:00Z",
    "channel": "email",
    "recurrence": {
      "type": "daily",
      "description": "Daily at 8am"
    },
    "nagMode": {"enabled": true, "intervalMs": 600000},
    "tags": ["health"]
  }'

# Weekday recurring via cron with live data
curl -X POST https://yougot.ai/api/v1/reminders \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Check Bitcoin price",
    "scheduledAt": "2026-04-01T09:00:00Z",
    "channel": "email",
    "recurrence": {
      "type": "custom",
      "cronExpression": "0 9 * * 1-5",
      "description": "Weekdays at 9am"
    },
    "dataFetch": {"type": "crypto", "query": "bitcoin"}
  }'

Response: 201 Created

{
  "id": "j97ekxp8040amr2hzfss...",
  "message": "Call the dentist",
  "scheduledAt": 1743519600000,
  "channel": "email",
  "status": "pending",
  "recipientIds": ["jd7ffzb3r1hdd28ffxvdeacbcs836cep"],
  "userId": "jd7ffzb3r1hdd28ffxvdeacbcs836cep"
}

recipientIds echoes who will receive the reminder. Omit it on create to get a personal reminder ([userId]). To send to other people, pass the user IDs of active members of your group. Each recipient gets the reminder in their own channel with an independent acknowledgement state, and the creator sees per-recipient delivery status in the "Sent by me" dashboard view.

Error Responses

HTTP	error message
400	Sending reminders to other people requires a Plus or Business plan.
400	You are not part of a group. Invite members before sending reminders to others.
400	One or more recipients are not active members of your group.
400	Invalid value "..." for field "recipientIds[0]"

List Reminders

GET/api/v1/reminders— List your reminders

Field	Type	Required	Description
`status`	string	No	Filter: pending, delivered, failed, snoozed, cancelled, paused, stopped
`limit`	number	No	Max results (default: 50, max: 100)

curl "https://yougot.ai/api/v1/reminders?status=pending&limit=10" \
  -H "Authorization: Bearer yg_your_api_key_here"

Response: 200 OK

{
  "data": [...],
  "count": 15
}

Get a Reminder

GET/api/v1/reminder?id=REMINDER_ID— Get a single reminder

curl "https://yougot.ai/api/v1/reminder?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here"

Update a Reminder

PATCH/api/v1/reminder?id=REMINDER_ID— Update a reminder

Field	Type	Required	Description
`message`	string	No	Updated message text
`scheduledAt`	number \| string	No	New delivery time (reschedules the job)
`channel`	string	No	Change primary channel
`additionalChannels`	string[]	No	Change additional channels
`tags`	string[]	No	Replace all tags
`metadata`	object	No	Replace metadata
`nagMode`	object	No	Enable/disable nag mode
`notifyBeforeMs`	number	No	Early notification offset

curl -X PATCH "https://yougot.ai/api/v1/reminder?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message": "Updated: call the dentist at 3pm", "tags": ["urgent"]}'

Delete a Reminder

DELETE/api/v1/reminder?id=REMINDER_ID— Cancel and delete a reminder

curl -X DELETE "https://yougot.ai/api/v1/reminder?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here"

Response: 200 OK

{"success": true}

Snooze a Reminder

POST/api/v1/reminder/snooze?id=REMINDER_ID— Snooze a reminder

Field	Type	Required	Description
`duration`	string \| number	Yes	"15m", "1h", "3h", "tomorrow", or a number (minutes)

curl -X POST "https://yougot.ai/api/v1/reminder/snooze?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"duration": "1h"}'

Response: 200 OK

{"success": true, "newScheduledAt": 1743523200000}

Pause a Reminder

POST/api/v1/reminder/pause?id=REMINDER_ID— Pause a pending reminder

Pauses a pending reminder or all pending occurrences in a recurring series. No request body needed.

curl -X POST "https://yougot.ai/api/v1/reminder/pause?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json"

Resume a Reminder

POST/api/v1/reminder/resume?id=REMINDER_ID— Resume a paused or stopped reminder

Resumes a paused or stopped reminder. Reschedules future occurrences. No request body needed.

curl -X POST "https://yougot.ai/api/v1/reminder/resume?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json"

Skip Next Occurrence

POST/api/v1/reminder/skip?id=REMINDER_ID— Skip the next recurring occurrence

Only works on recurring reminders with status pending or paused. Skips the next occurrence and schedules the one after.

curl -X POST "https://yougot.ai/api/v1/reminder/skip?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json"

Unskip

POST/api/v1/reminder/unskip?id=REMINDER_ID— Re-enable a skipped occurrence

Re-enables a previously skipped (cancelled) recurring occurrence, if it is still in the future.

curl -X POST "https://yougot.ai/api/v1/reminder/unskip?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json"

Stop Recurring

POST/api/v1/reminder/stop?id=REMINDER_ID— Stop all future recurring occurrences

curl -X POST "https://yougot.ai/api/v1/reminder/stop?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json"

Acknowledge (Nag Mode)

POST/api/v1/reminder/acknowledge?id=REMINDER_ID— Stop nagging for a reminder

Stops nag mode for a reminder. The reminder is marked as delivered and nagging stops.

curl -X POST "https://yougot.ai/api/v1/reminder/acknowledge?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json"

Toggle Nag Mode

POST/api/v1/reminder/nag?id=REMINDER_ID— Enable or disable nag mode

Field	Type	Required	Description
`enabled`	boolean	Yes	true to enable, false to disable
`intervalMs`	number	No	Nag interval in ms (default: 300000 = 5 min)

# Enable nag mode
curl -X POST "https://yougot.ai/api/v1/reminder/nag?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "intervalMs": 600000}'

# Disable nag mode
curl -X POST "https://yougot.ai/api/v1/reminder/nag?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Add a Tag

POST/api/v1/reminder/tag?id=REMINDER_ID— Add a tag to a reminder

Field	Type	Required	Description
`tag`	string	Yes	Tag name (auto-lowercased, duplicates ignored)

curl -X POST "https://yougot.ai/api/v1/reminder/tag?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"tag": "work"}'

Remove a Tag

DELETE/api/v1/reminder/tag?id=REMINDER_ID&tag=work— Remove a tag from a reminder

curl -X DELETE "https://yougot.ai/api/v1/reminder/tag?id=REMINDER_ID&tag=work" \
  -H "Authorization: Bearer yg_your_api_key_here"

POST/api/v1/reminder/share?id=REMINDER_ID— Generate a shareable link

Idempotent — returns the existing code if already shared.

curl -X POST "https://yougot.ai/api/v1/reminder/share?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json"

Response: 200 OK

{
  "shareCode": "9efea664",
  "shareUrl": "https://yougot.ai/r/9efea664"
}

Unshare a Reminder

DELETE/api/v1/reminder/share?id=REMINDER_ID— Deactivate the share link

curl -X DELETE "https://yougot.ai/api/v1/reminder/share?id=REMINDER_ID" \
  -H "Authorization: Bearer yg_your_api_key_here"

Search Reminders

GET/api/v1/reminders/search— Full-text search across reminders

Field	Type	Required	Description
`q`	string	Yes	Search text (matches message and tags)
`status`	string	No	Filter by status
`limit`	number	No	Max results (default: 50, max: 100)

curl "https://yougot.ai/api/v1/reminders/search?q=dentist&status=pending" \
  -H "Authorization: Bearer yg_your_api_key_here"

Delivery History

GET/api/v1/reminders/history— Get delivery history

Field	Type	Required	Description
`limit`	number	No	Max results (default: 50, max: 200)

curl "https://yougot.ai/api/v1/reminders/history?limit=20" \
  -H "Authorization: Bearer yg_your_api_key_here"

Statistics

GET/api/v1/reminders/stats— Get reminder statistics

curl https://yougot.ai/api/v1/reminders/stats \
  -H "Authorization: Bearer yg_your_api_key_here"

Response: 200 OK

{
  "total": 50,
  "pending": 15,
  "delivered": 14,
  "failed": 9,
  "cancelled": 8,
  "paused": 4
}

Delivery Rate

GET/api/v1/reminders/delivery-rate— Get delivery success rate

curl https://yougot.ai/api/v1/reminders/delivery-rate \
  -H "Authorization: Bearer yg_your_api_key_here"

Response: 200 OK

{
  "successful": 14,
  "total": 23,
  "rate": 61
}

Parse Natural Language

POST/api/v1/parse— Parse natural language into structured reminder data

Parses a natural language reminder into structured data without creating the reminder. Supports any language.

Field	Type	Required	Description
`text`	string	Yes	Natural language input, e.g. "remind me tomorrow at 9am to call mom"
`timezone`	string	No	IANA timezone, e.g. "America/New_York". Defaults to user's stored timezone

curl -X POST https://yougot.ai/api/v1/parse \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "every weekday at 9am review priorities", "timezone": "America/New_York"}'

Response: 200 OK

{
  "message": "review priorities",
  "scheduledAt": "2026-03-24T14:00:00.000Z",
  "recurrence": {
    "type": "custom",
    "cronExpression": "0 9 * * 1-5",
    "description": "Every weekday at 9am"
  },
  "channel": null,
  "tags": ["work"],
  "nagMode": null,
  "dataFetch": null
}

Webhooks

List Webhooks

GET/api/v1/webhooks— List all registered webhooks

curl https://yougot.ai/api/v1/webhooks \
  -H "Authorization: Bearer yg_your_api_key_here"

Create Webhook

POST/api/v1/webhooks— Register a new webhook endpoint

Field	Type	Required	Description
`url`	string	Yes	The URL to receive webhook POST requests

curl -X POST https://yougot.ai/api/v1/webhooks \
  -H "Authorization: Bearer yg_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-server.com/webhook"}'

Delete Webhook

DELETE/api/v1/webhooks?id=WEBHOOK_ID— Remove a webhook endpoint

curl -X DELETE "https://yougot.ai/api/v1/webhooks?id=WEBHOOK_ID" \
  -H "Authorization: Bearer yg_your_api_key_here"

List Verified Phone Numbers

GET/api/v1/phones— List all verified phone numbers

Returns all verified phone numbers for the authenticated user. Use the phone value as targetPhone when creating SMS/WhatsApp reminders.

curl https://yougot.ai/api/v1/phones \
  -H "Authorization: Bearer yg_your_api_key_here"

Response: 200 OK

{
  "data": [
    {
      "_id": "abc123",
      "phone": "+12025551234",
      "label": "Personal",
      "countryCode": "US",
      "isPrimary": true,
      "verifiedAt": 1711375200000
    }
  ]
}

Error Reference

All errors return JSON in the format: {"error": "Description"}

Status	Meaning
`400`	Bad request -- missing or invalid parameters
`401`	Unauthorized -- missing or invalid API key
`403`	Forbidden -- not authorized for this resource, or tier too low
`404`	Not found
`429`	Rate limit exceeded (retry after Retry-After header)
`500`	Server error

← Back to Home

YouGot REST API

Authentication

Quick Start

Step 1 — Get your API key

Step 2 — Create your first reminder

Step 3 — Verify it was created

Create a Reminder

Recurrence Object

Nag Mode Object

Data Fetch Object

List Reminders

Get a Reminder

Update a Reminder

Delete a Reminder

Snooze a Reminder

Pause a Reminder

Resume a Reminder

Skip Next Occurrence

Unskip

Stop Recurring

Acknowledge (Nag Mode)

Toggle Nag Mode

Add a Tag

Remove a Tag

Share a Reminder

Unshare a Reminder

Search Reminders

Delivery History

Statistics

Delivery Rate

Parse Natural Language

Webhooks

List Webhooks

Create Webhook

Delete Webhook

List Verified Phone Numbers

Error Reference