API reference

Every endpoint of the read-only DaySmith API, with examples.

The DaySmith API is read-only and returns JSON. Every request needs an API key. Times are in UTC, in ISO 8601 format. Days are written YYYY-MM-DD and follow your DaySmith time zone.

Basics

Base URL:

https://api.getdaysmith.com/v1

Send your key with every request:

Authorization: Bearer ds_k_your_key_here

The API is versioned. Fields may be added to /v1 responses over time, but existing fields won't be removed or renamed. Write your code to ignore fields it doesn't know.

GET /v1/me

Your profile and workday. Needs Read your plan.

{
  "name": "Sam Rivera",
  "email": "sam@example.com",
  "timezone": "America/Denver",
  "workdays": [1, 2, 3, 4, 5],
  "workdayStart": "08:00",
  "workdayEnd": "17:00"
}

workdays uses 0 for Sunday through 6 for Saturday.

GET /v1/plan

Your meetings and planned work, built fresh from your tools. Needs Read your plan.

ParameterMeaning
fromFirst day, YYYY-MM-DD. Defaults to today. From 7 days ago to 60 days ahead.
daysHow many days, 1 to 14. Defaults to 1.
GET /v1/plan?from=2026-10-15&days=2

{
  "from": "2026-10-15",
  "to": "2026-10-16",
  "timezone": "America/Denver",
  "generatedAt": "2026-10-15T13:02:11.000Z",
  "days": [
    {
      "day": "2026-10-15",
      "blocks": [
        {
          "type": "task",
          "id": "86b2x1",
          "provider": "clickup",
          "title": "Update giving page",
          "url": "https://app.clickup.com/t/86b2x1",
          "start": "2026-10-15T15:00:00.000Z",
          "end": "2026-10-15T15:45:00.000Z",
          "minutes": 45,
          "pinned": false,
          "status": { "name": "to do", "type": "open" },
          "list": { "id": "901", "name": "Woodmen Valley" },
          "folder": { "id": "77", "name": "Clients" },
          "client": { "id": "4f0c…", "name": "Woodmen Valley" },
          "dueAt": "2026-10-20T06:00:00.000Z",
          "createdAt": "2026-10-01T18:12:00.000Z"
        },
        {
          "type": "meeting",
          "id": "AAMkAG…",
          "provider": "microsoft",
          "title": "Woodmen Valley weekly",
          "start": "2026-10-15T21:00:00.000Z",
          "end": "2026-10-15T22:00:00.000Z",
          "allDay": false,
          "showAs": "busy",
          "isOrganizer": true,
          "seriesId": "AAMkAG…",
          "client": { "id": "4f0c…", "name": "Woodmen Valley" },
          "linkedTasks": []
        }
      ]
    }
  ],
  "didntFit": [
    {
      "type": "task",
      "id": "86b2y7",
      "title": "Quarterly report",
      "start": "",
      "end": "",
      "minutes": 0,
      "reason": "Woodmen Valley's monthly time is used up."
    }
  ],
  "errors": []
}

Work in didntFit has the same fields as other tasks. The example above is shortened.

  • Blocks are in time order for each day, with all-day meetings first.
  • type is meeting or task.
  • showAs is free, tentative, busy, oof for out of office, workingElsewhere, or unknown.
  • All-day meetings have allDay: true, and their start and end fall at midnight UTC on their dates.
  • pinned is true for work you placed yourself on the calendar.
  • client is null when a block has no client. For a task, it's the client whose work rule includes the task's List.
  • didntFit lists ready work that wasn't planned, most important first, with a reason when DaySmith knows one.
  • errors lists tools DaySmith couldn't reach, so their items are missing. Try again in a few minutes.
  • Plans are built live. The same request a few minutes later can differ, because meetings move and tasks get done.

GET /v1/clients

Your clients, their work rules, and their planned time this month. A client appears here once you've set a work rule for it. Needs Read clients and client time.

{
  "month": "2026-10",
  "clients": [
    {
      "id": "4f0c…",
      "name": "Woodmen Valley",
      "provider": "clickup",
      "listIds": ["901", "902"],
      "rule": { "when": "before_call", "workDaysBefore": 1 },
      "monthlyCapMinutes": 600,
      "plannedThisMonthMinutes": 135
    }
  ]
}
rule.whenMeaningExtra fields
before_callBefore each client call. 0 work days means the day of the call.workDaysBefore
weekdaysOn set days of the week, every N weeks.weekdays, everyWeeks, startWeek
anytimePlanned like any other work.

monthlyCapMinutes is null when the client has no monthly limit.

GET /v1/clients/time

Minutes of each client's work DaySmith planned, day by day, for one month. Needs Read clients and client time.

ParameterMeaning
monthYYYY-MM. Defaults to this month.
GET /v1/clients/time?month=2026-10

{
  "month": "2026-10",
  "clients": [
    {
      "id": "4f0c…",
      "name": "Woodmen Valley",
      "monthlyCapMinutes": 600,
      "totalMinutes": 135,
      "days": [
        { "day": "2026-10-14", "minutes": 90 },
        { "day": "2026-10-15", "minutes": 45 }
      ]
    }
  ]
}

These are planned minutes: the client's work in your plan at the end of each day. They aren't the time you tracked. For tracked time, use your time tracker's reports. Days are recorded from when you set the client's work rule.

Errors

Errors return JSON with a readable error message, and a code where one helps.

StatusMeaning
400A parameter is missing or wrong. The message says which.
401No key, or the key was deleted or has expired. Codes: no_key, bad_key, expired_key.
402The DaySmith subscription isn't active. Code: billing_inactive.
403The key doesn't have the permission this endpoint needs. Code: missing_scope.
429Too many requests. Wait a minute and try again.
502A connected tool didn't respond. Try again shortly.

Limits

EndpointRequests per minute, per key
/v1/plan20
Everything else60

A plan is built from your tools on every request, so ask for what you need, such as once an hour, rather than polling every few seconds.

Changing things

The API can only read. To move work, mark tasks done, or change client rules, use DaySmith itself. If you have a use for writing through the API, tell us at support@getdaysmith.com.

Didn't answer your question? Email support.