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.
| Parameter | Meaning |
|---|---|
from | First day, YYYY-MM-DD. Defaults to today. From 7 days ago to 60 days ahead. |
days | How 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
meetingortask. - showAs is
free,tentative,busy,ooffor out of office,workingElsewhere, orunknown. - 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
reasonwhen 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.when | Meaning | Extra fields |
|---|---|---|
before_call | Before each client call. 0 work days means the day of the call. | workDaysBefore |
weekdays | On set days of the week, every N weeks. | weekdays, everyWeeks, startWeek |
anytime | Planned 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.
| Parameter | Meaning |
|---|---|
month | YYYY-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.
| Status | Meaning |
|---|---|
| 400 | A parameter is missing or wrong. The message says which. |
| 401 | No key, or the key was deleted or has expired. Codes: no_key, bad_key, expired_key. |
| 402 | The DaySmith subscription isn't active. Code: billing_inactive. |
| 403 | The key doesn't have the permission this endpoint needs. Code: missing_scope. |
| 429 | Too many requests. Wait a minute and try again. |
| 502 | A connected tool didn't respond. Try again shortly. |
Limits
| Endpoint | Requests per minute, per key |
|---|---|
/v1/plan | 20 |
| Everything else | 60 |
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.