Smart Scheduling API

The Smart Scheduling API allows you to programmatically trigger scheduling and retrieve scheduling status.

Endpoints

Trigger Scheduling

Triggers the unified scheduler for a workspace, scheduling both habits and tasks.

Path Parameters

string

required

The workspace ID (UUID format)

Request Body

number

default:30

How many days into the future to schedule events (7-90)

boolean

default:false

If true, deletes existing auto-generated events and creates new ones

Response

{
  "success": true,
  "summary": {
    "habitsScheduled": 5,
    "tasksScheduled": 3,
    "eventsCreated": 12,
    "bumpedHabits": 1,
    "rescheduledHabits": 1,
    "windowDays": 30
  },
  "habits": {
    "events": [
      {
        "habitId": "uuid",
        "habitName": "Morning Meditation",
        "occurrence": "2024-01-15",
        "duration": 20,
        "event": {
          "id": "uuid",
          "start_at": "2024-01-15T07:00:00Z",
          "end_at": "2024-01-15T07:20:00Z"
        }
      }
    ],
    "warnings": []
  },
  "tasks": {
    "events": [
      {
        "taskId": "uuid",
        "taskName": "Complete report",
        "scheduledMinutes": 120,
        "warning": null,
        "events": [
          {
            "id": "uuid",
            "start_at": "2024-01-15T09:00:00Z",
            "end_at": "2024-01-15T11:00:00Z",
            "scheduled_minutes": 120
          }
        ]
      }
    ],
    "bumpedHabits": [
      {
        "habitId": "uuid",
        "habitName": "Reading",
        "occurrence": "2024-01-15",
        "originalEventId": "uuid"
      }
    ],
    "warnings": []
  },
  "rescheduledHabits": [
    {
      "habitId": "uuid",
      "habitName": "Reading",
      "occurrence": "2024-01-15",
      "duration": 30,
      "event": {
        "id": "uuid",
        "start_at": "2024-01-15T19:00:00Z",
        "end_at": "2024-01-15T19:30:00Z"
      }
    }
  ],
  "warnings": []
}

Example

curl -X POST "https://tuturuuu.com/api/v1/workspaces/{wsId}/calendar/schedule" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"windowDays": 30, "forceReschedule": false}'

const response = await fetch(
  `/api/v1/workspaces/${wsId}/calendar/schedule`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ windowDays: 30, forceReschedule: false }),
  }
);

const result = await response.json();
console.log(`Created ${result.summary.eventsCreated} events`);

Get Scheduling Status

Retrieves the current scheduling status and statistics for a workspace.

Path Parameters

string

required

The workspace ID (UUID format)

Response

{
  "lastScheduledAt": "2024-01-15T10:30:00Z",
  "lastStatus": "success",
  "lastMessage": "Scheduled 5 habits and 3 tasks",
  "statistics": {
    "habitsScheduled": 5,
    "tasksScheduled": 3,
    "eventsCreated": 12,
    "bumpedHabits": 1,
    "windowDays": 30
  },
  "schedulableItems": {
    "activeHabits": 7,
    "autoScheduleTasks": 4
  }
}

Example

curl "https://tuturuuu.com/api/v1/workspaces/{wsId}/calendar/schedule" \
  -H "Cookie: your-session-cookie"

const response = await fetch(
  `/api/v1/workspaces/${wsId}/calendar/schedule`
);

const status = await response.json();
console.log(`Last scheduled: ${status.lastScheduledAt}`);

Authentication

User Authentication

Standard user authentication via session cookie. The user must be a member of the workspace.

Cron Authentication

For background jobs, the API accepts a Bearer token with the cron secret:

Authorization: Bearer {CRON_SECRET}

This is used by the Vercel cron job that runs scheduling every 6 hours. The cron secret is read from process.env.CRON_SECRET ?? process.env.VERCEL_CRON_SECRET.

Error Responses

Status	Description
400	Invalid workspace ID
401	Not authenticated
403	Not a workspace member
409	Safe apply blocked because the schedule still has unresolved warnings
422	Workspace timezone is not set, or is set to `auto`
500	Internal server error

Rate Limiting

The scheduling endpoint is rate-limited to prevent abuse:

Manual triggers: Limited by standard API rate limits
Cron triggers: A single global cron runs every 6 hours and fans out to eligible workspaces (not per-workspace at the cron level)

Cron Job

Smart Scheduling runs automatically every 6 hours via Vercel Cron:

{
  "path": "/api/cron/calendar/smart-schedule",
  "schedule": "0 */6 * * *"
}

The cron job:

Finds all workspaces with auto-schedule enabled habits or tasks
Calls the scheduling API for each workspace
Logs results and any errors

The cron job uses forceReschedule: false to avoid disrupting existing schedules. Only new items are scheduled.

Calendar link preview for Mail

GET /api/v1/workspaces/{wsId}/calendar/events/{eventId}/link-preview returns a sanitized read-only target for an explicit Mail association. The default Calendar/Tasks authentication boundary is preserved; this endpoint also accepts a validated Mail app session and mobile bearer authentication. Workspace membership and manage_calendar remain required. A provider target additionally requires one enabled, active connected account owned by the actor, with both the stored workspace source and external calendar IDs matching exactly. Read-only provider roles are eligible; ambiguous or incomplete legacy identities, disabled accounts, missing targets, and cancelled events suppress the preview. The response preserves internal IDs, connected-account row and connection IDs, provider calendar and immutable event IDs, actual provider UID, and original occurrence identity when available. Microsoft occurrence UIDs are returned as provided and must not be assumed to equal a series UID. Native events report unknown account, organizer, UID, recurrence and attendee ownership. Provider fields come from an exact authorized GET, after the local encrypted storage boundary. Missing keys, malformed ciphertext and authentication failures suppress both native previews and provider GETs; the preview never treats the legacy decryption fallback or an encryption flag as proof of plaintext. Hidden attendees are omitted; conferencing fields only yield validated HTTPS Teams/Meet links, separately from the structured location. Raw bodies, account credentials and provider errors are never returned. This endpoint does not save associations, alter either event, respond to invitations, copy events or grant permission to merge a private hold into an organizer’s request. The shared wire contract is exported from @tuturuuu/internal-api/calendar. Mail owns actor-scoped association metadata and must recheck this preview on confirm/open. No Calendar table or provider mutation is part of this seam.

Overview

Platform

Build

Learn

Reference

API Reference

Smart Scheduling API

Endpoints

Trigger Scheduling

Path Parameters

Request Body

Response

Example

Get Scheduling Status

Path Parameters

Response

Example

Authentication

User Authentication

Cron Authentication

Error Responses

Rate Limiting

Cron Job

Calendar link preview for Mail

​Smart Scheduling API

​Endpoints

​Trigger Scheduling

​Path Parameters

​Request Body

​Response

​Example

​Get Scheduling Status

​Path Parameters

​Response

​Example

​Authentication

​User Authentication

​Cron Authentication

​Error Responses

​Rate Limiting

​Cron Job

​Calendar link preview for Mail

Smart Scheduling API

Endpoints

Trigger Scheduling

Path Parameters

Request Body

Response

Example

Get Scheduling Status

Path Parameters

Response

Example

Authentication

User Authentication

Cron Authentication

Error Responses

Rate Limiting

Cron Job

Calendar link preview for Mail