SelfManager API and webhooks: your tables, in your own code

Get started

1. In SelfManager, open My Profile → Connected apps and make a personal API key: choose what it may do, and whether it lasts 30, 90 or 365 days. It is shown once, so keep it somewhere safe. Connected apps appears there once your account is in the beta.
2. Send it with every request, as Authorization: Bearer <your key>. Your first request says whose key it is:

curl https://api.selfmanager.ai/v1/me \
  -H "Authorization: Bearer <your key>"

Then read today's tables with GET /v1/days/today, or make a table with its tasks:

curl https://api.selfmanager.ai/v1/tables \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-prep-1" \
  -d '{"date": "2026-10-26", "name": "Launch prep", "tasks": [
        {"name": "Write the changelog"},
        {"name": "Record the demo", "priority": "high"}]}'

• Answers are JSON. A range of days, a search and most lists come a page at a time: an answer with a cursor has more, so send the same request with it.
• Every table has an id. Each answer gives a table its table_id; address the table as /v1/tables/ followed by it. Dates are YYYY-MM-DD, or today where a day is asked for.
• Retries are safe. Send an Idempotency-Key header with a change: sent again with the same key, it answers as it did the first time and changes nothing twice. A key is remembered for 24 hours. Making many tables at once, and copying or moving a table, need one.
• Keep your key on your server. A key acts as you. The API sends no CORS headers: keep it out of web pages and apps other people run.

Every endpoint, with its parameters, answers, permissions and price, is in the API reference, also as OpenAPI.

What you can build

Anything that can send a request can work with your tables. For example:

• Post today's list to your team's chat every morning.
• Make a table on the day of each new booking, with the tasks it needs.
• Turn every form a client sends into tasks on a table called Inbox.
• When a task is done, update an invoice or a CRM in your own app.
• When a table's last task is done, email the client.
• Copy a year of days, tasks and tracked time into a spreadsheet.
• Plan a month of workouts as 30 tables in one request.
• Copy new images, recordings and docs to your own storage, up to 8 MB each.

Prefer to ask in words? Connect an AI assistant through the MCP server instead.

What it can and can't do

Webhooks

A webhook sends an event to an address of yours as soon as something happens in your tables: a POST of JSON, signed so your app can tell it came from SelfManager. A key with the webhooks permission makes one:

curl https://api.selfmanager.ai/v1/webhooks \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com/selfmanager",
       "events": ["task.completed", "table.completed"]}'

The answer holds the webhook's secret, shown only there. The events:

• table.createdA table appears on a day.
• task.createdA task is added.
• task.completedA task is completed.
• table.completedThe last of a table's tasks is completed. It says how many tasks the table has.
• comment.createdA comment with words is added.
• deadline.dueA task's deadline is reached, for the person it reminds.

Which tables they come from

• Your tables that nobody else can change, unless you ask for more. With include_shared_tables, also your tables other people can change, and theirs you're on: what others do there can fill the webhook, and use your Integration Credits.
• A copy, made by Duplicate or by moving a table, sends none. A repeating table's copy appearing on its day, and its tasks, only with include_repeat_copies.
• What the key itself changes is left out, unless you turn exclude_own_changes off, so a script that adds a task for each new task never loops.
• An event is sent only while you can still see its table: lose access, and what wasn't sent yet never is.

What arrives

A POST of id, type, occurred_at and data, in the shapes the API answers with, times in UTC; via names the app when an app made the change. For example:

{
  "id": "evt_4kQ2mX9vR1sT7bN0pL3wYc",
  "type": "task.completed",
  "occurred_at": "2026-10-24T09:41:07.312Z",
  "data": {
    "task": {
      "task_id": "…",
      "name": "Send the invoice",
      "status": "completed",
      "priority": "high",
      "completed_at": "2026-10-24T09:41:07Z",
      "created_at": "2026-10-24T08:02:15Z"
    },
    "table": {
      "table_id": "2026-10-24/…",
      "name": "Client work",
      "date": "2026-10-24",
      "shared": false,
      "your_role": "owner"
    }
  }
}

It comes with this header, among others:

SelfManager-Signature: t=1792834867,v1=5257a869e7ec…

• Check the signature before you trust a delivery: it is the hex HMAC-SHA256 of t, a dot and the body, keyed with the whole secret as text, whsec_ included. Compute it over the body exactly as it arrived, compare in constant time, and refuse a t more than 5 minutes old. While a secret is replaced, for 24 hours, there are two v1, one for each. The reference has the code, in Node.
• Answer with a 2xx within 10 seconds. A 429, a 5xx, no answer or no connection is sent again after 1, 5 and 15 minutes, then hourly: 8 attempts in all. Any other answer is final, and a 410 deletes the webhook.
• An event can arrive twice, or out of order: its id tells them apart.
• A webhook nothing succeeds for in 3 days is turned off. Turn it on again in My Profile → Connected apps.
• A webhook lasts as long as the key that made it. Revoking the key deletes its webhooks. Once the key expires, or after a password change, they send nothing more and are deleted at their next event, and SelfManager tells you.

Where you see them

• My Profile → Connected apps lists every webhook you have, with where it sends, its events and its latest deliveries. Send it a test, turn it back on, or delete it there.
• SelfManager tells you whenever a webhook is made, and names where it sends.
• An account has up to 25 webhooks, sending to public https addresses on port 443, and makes up to 50 a day.

The permissions you choose

When you make a key, you choose what it may do:

• Read your tables, tasks, notes and commentsAlways on.
• Make changesTicked unless you untick it.
• Also add tasks, comments and notes, and set deadlines that remind everyone, in tables other people can seeOff unless you tick it.
• Delete through the API: one thing at a time, in tables only you can see; also move tables and reset their task timesOff unless you tick it.
• Your journal: read it, and add to it if it may make changesTicked unless you untick it.
• Your images and voice recordings: see and download them, and read the transcriptsOff unless you tick it.
• Your docs: read and download the files in tables' Docs sectionsOff unless you tick it.
• Make webhooksOff unless you tick it.

To change them, make a new key and revoke the old one in My Profile → Connected apps. A revoked key stops working within about a minute, and its webhooks are deleted. A password or email change ends every key. The same key also connects apps that can't sign in to the MCP server, where it never deletes.

Integration Credits

The API and webhooks run on Integration Credits, kept apart from AI credits: those stay for SelfManager's own AI and for AI assistants connected through MCP.

What a request costs

• With too few credits left, a request that costs more does nothing and answers 402. Free requests keep working. Webhook events wait for credits, up to 7 days; then they are dropped.
• Your Subscription page shows what is left, and its usage history what used them: each request, and webhook events in batches.

More on plans on the Pricing page.

Limits

• 120 requests a minute for an account, refused ones included. Within them, a minute: 10 searches; 10 requests that make or change many tables at once (making several tables, copying, moving or deleting a table, editing a repeating table, resetting a table's task times, opening a day); 20 deletes; 20 downloads; 30 docs read; and 5 webhook tests.
• 10,000 requests a day (UTC), and 8 at once.
• In a day (UTC), across your keys and assistants: up to 100 deletes and 10 whole tables deleted, 50 tables copied or moved, and 50 deadlines set for everyone.
• Webhooks: from one table, at most 60 events and 300 deliveries a minute; from all your own tables, 300 and 1,500. Tables other people can change have as many again for each of their owners. What is over isn't sent.
• Sizes: a change's body is one JSON object of at most 1 MiB, and a download at most 8 MB; a larger file is downloaded in SelfManager.

Past a limit, the answer is a 429 with a Retry-After header: the seconds to wait.

How you can tell what it did

• Each change it makes to an existing table adds a line to that table's log, if the table keeps one (new tables do), ending in "via the API". Everyone on that table sees it. For example:

Row "Send the invoice" status changed from not started to completed (via the API)

• A comment it adds shows "via the API" next to your name, so the people you share with know. It never shows your key's name.
• The Assistant activity page lists what your keys changed in the last 30 days, also after you revoke them. My Profile → Connected apps lists your keys, and when each was last used.
• SelfManager sends you a notice whenever a key or a webhook is made.

Privacy

A key gets only the SelfManager data its requests ask for, as you, within the permissions you gave it: images, recordings and docs only if you allowed them. On a shared table, that includes what other members wrote, added or recorded, and their names, never their email addresses. Where your program keeps what it reads is up to you.

A webhook sends its events only to the address you chose. Whoever runs that address receives them, so send them only somewhere you trust.

For 30 days we keep a list of what each key changed, for your Assistant activity page: which table (by its name) or day, and when, never the text it wrote or what it deleted. So that a request sent twice is applied once, we keep each change's answer for a day. Each webhook delivery's record is kept for 8 days, for its retries and your list of latest deliveries.

What a key deletes is deleted as it is in SelfManager. Its images, recordings and docs are removed from our storage within minutes, with every stored copy, and a whole table's files go as when you delete the table in SelfManager; as for any file you delete, our storage provider can recover them for up to 7 days.

Read more in our Privacy Policy.

If something doesn't work

An error answers error.code and a message written for a person, and every answer the API gives has an X-Request-Id: quote it if you write to us. The ones you're most likely to meet:

401 unauthorized

No key was sent, or it has expired or was revoked. A password or email change ends your keys too: make a new one.

403 not_in_beta

Your account isn't in the beta yet. Write to marian@selfmanager.ai from the address you sign in with.

403 plan_inactive

Start or renew a plan in SelfManager. The 7-day free trial counts.

403 insufficient_scope

The key wasn't given the permission this request needs. Make a key that has it.

403 writes_off

Changes through the API aren't switched on yet. Reading still works.

403 viewer_role

You're a viewer on that table, so you can read it but not change it.

402 insufficient_credits

Fewer Integration Credits are left than this request costs. Free requests keep working, and your weekly credits renew on Monday (UTC).

429 rate_limited

Too many requests in a minute or in a day, or the Integration Credits left are held by requests still running or webhook events still being sent. Wait the seconds the Retry-After header gives.

409 conflict

That Idempotency-Key was used before, with another request. Give each new request its own key.

A webhook stopped sending

A webhook nothing succeeds for in 3 days is turned off: fix your endpoint, then turn it on again in My Profile → Connected apps. One whose key has ended is deleted: make a new key, and the webhook again. With no Integration Credits left, events wait for them up to 7 days.

The endpoints

Each at https://api.selfmanager.ai/v1 followed by its path. Those without a price are free. The reference has every parameter and answer.

Reading 19

• GET /v1/me Whose key it is: your name, plan, today's date, what the key may do, and your Integration Credits.
• GET /v1/days/{date} The tables on one day, with their tasks, progress and tracked time. The date can be today.
• GET /v1/days The same over any range, years too, a page at a time. 1 credit a page
• GET /v1/totals Totals per week or month over any range: tables, tasks, completed tasks, completion and time. 1 credit a page
• GET /v1/dates The days you have tables on, with how many on each. 1 credit a page
• GET /v1/tables/{table_id} One table: every task, your deadlines on it, its notes, and its comments if asked.
• GET /v1/search Your own tables, by a word or phrase in their name, tasks or notes (and comments if asked), over the last 30 days unless you give dates. 1 credit a page
• GET /v1/pins Your pinned tables, in their order.
• GET /v1/deadlines Your deadlines, as the Deadlines page shows them.
• GET /v1/repeats Your repeating tables: what repeats, how often, the next date.
• GET /v1/repeats/{repeat_id} One repeating table whole: its schedule, and the name, tasks and notes each copy starts with.
• GET /v1/journal Your journal (your daily Self message), for one day or any range. With the journal permission.
• GET /v1/comments Every comment you can see, newest first, with who wrote each (by name).
• GET /v1/notes Every table's notes you can see, newest first.
• GET /v1/shared/with-me The tables other people share with you, with whose each is and your role.
• GET /v1/shared/by-me Your tables other people can see, with who is on each (by name) and their role.
• GET /v1/ai-history Your AI History: the AI Reviews and chats you saved, newest first.
• GET /v1/ai-history/{conversation_id} One conversation from your AI History, as text.
• GET /v1/ai-usage What used your AI credits, as the AI Usage page lists it.

Making changes 20

With the Make changes permission. In a table other people can see, adding and deadlines need that permission too.

• POST /v1/tables Create a table of yours on a day, with up to 200 tasks and notes. 1 credit or more
• POST /v1/tables/batch Create up to 1,000 tables in one request, on any days, several on one day too. Needs an Idempotency-Key. 1 credit or more
• POST /v1/tables/{table_id}/tasks Add up to 200 tasks at the end of a table. 1 credit or more
• PATCH /v1/tables/{table_id}/tasks/{task_id} Change a task's priority or progress, or rename it in a table nobody else can read.
• POST /v1/tables/{table_id}/tasks/{task_id}/complete Mark a task completed, as ticking it does: its time, who completed it, and the table's log.
• POST /v1/tables/{table_id}/tasks/{task_id}/reopen Mark a completed task as not started. This deletes the time recorded for it.
• POST /v1/tables/{table_id}/tasks/{task_id}/time Record how long a task took: completes it with that time, or changes a done task's time.
• PUT · DELETE /v1/tables/{table_id}/tasks/{task_id}/deadline Set or remove a task's deadline and reminder, for you, or for everyone on a table others see.
• POST /v1/tables/{table_id}/comments Add a comment, in your name. 1 credit
• POST /v1/tables/{table_id}/notes Add text at the end of a table's notes. 1 credit
• PATCH /v1/tables/{table_id} Rename a table, change its description or time tracking, turn its log on, or make it your homepage table.
• POST /v1/tables/{table_id}/duplicate Copy one of your tables, as Duplicate does: its tasks, and if you ask, its comments, images, audio, notes and log. Needs an Idempotency-Key. 1 credit, once done
• GET /v1/jobs/{job_id} Whether a copy or a move is done.
• PUT · DELETE /v1/tables/{table_id}/pin Pin a table, or unpin it.
• POST /v1/days/{date}/open Make a day's repeating tables, as opening that day in SelfManager does.
• POST /v1/repeats Make a repeating table, as the Repeats page does, with its tasks, notes and schedule. 1 credit or more
• PATCH /v1/repeats/{repeat_id} Change what new copies start with, the schedule or the end date, or pause and resume it.
• POST /v1/journal/{date} Add text to a day's journal line. With the journal permission. 1 credit
• PUT /v1/journal/{date} Rewrite a day's journal line. The old line is kept, to bring back in SelfManager. 1 credit
• POST /v1/ai-history Save a review or a chat to your AI History. 1 credit

Images, recordings and docs 6

With the images and recordings permission, or the docs permission.

• GET /v1/images The images on your tables and those shared with you, with who added each. One table's too.
• GET /v1/recordings Voice recordings, with their length and whether they have a transcript. One table's too.
• GET /v1/tables/{table_id}/recordings/{recording_id} A recording's transcript.
• GET /v1/docs The docs on tables you can see, with who added each. One table's too.
• GET /v1/tables/{table_id}/docs/{doc_id} A doc's text, a page at a time.
• GET /v1/tables/{table_id}/images/{image_id}/file Download the file itself, up to 8 MB: an image (a HEIC as its JPEG), a recording (…/recordings/{recording_id}/file) or a doc (…/docs/{doc_id}/file). 1 credit

Deleting 12

Only with "Delete through the API", ticked when the key was made: one thing at a time, in tables only you can see. Moving a table needs it too, since the table leaves its day.

• DELETE /v1/tables/{table_id}/tasks/{task_id} Delete one task, with its deadline.
• DELETE /v1/tables/{table_id}/comments/{comment_id} Delete one comment, with its images and voice recordings.
• DELETE /v1/tables/{table_id}/notes Empty a table's notes. The old notes stay one undo away in SelfManager.
• DELETE /v1/tables/{table_id}/images/{image_id} Delete one image.
• DELETE /v1/tables/{table_id}/recordings/{recording_id} Delete one voice recording.
• DELETE /v1/tables/{table_id}/docs/{doc_id} Delete one doc, with its file and its text. With the docs permission too.
• GET /v1/tables/{table_id}/delete-preview What is in a table, and the confirmation deleting it needs. It changes nothing.
• DELETE /v1/tables/{table_id} Delete a whole table you own that nobody else can see, within 5 minutes of its preview.
• POST /v1/tables/{table_id}/move Move a table of yours that nobody else sees to another day, with everything in it. Needs an Idempotency-Key. 1 credit, once done
• POST /v1/tables/{table_id}/reset-times Set every task's times in a table to now, as "Reset time on all rows" does.
• DELETE /v1/repeats/{repeat_id} Delete a repeating table: no new copies are made, and the tables it made stay.
• DELETE /v1/journal/{date} Clear a day's journal line. It is kept, to bring back in SelfManager.

Webhooks 6

With the webhooks permission. A key manages the webhooks it made.

• POST /v1/webhooksMake a webhook. The answer holds its secret, shown only there.
• GET /v1/webhooksThe webhooks this key made, and how each one's last delivery went.
• GET /v1/webhooks/{webhook_id}One webhook, with its latest 20 deliveries.
• POST /v1/webhooks/{webhook_id}/testSend it a ping now, and see how your endpoint answered.
• POST /v1/webhooks/{webhook_id}/rotate-secretA new secret. For 24 hours each delivery is signed with both.
• DELETE /v1/webhooks/{webhook_id}Delete a webhook: nothing more is sent to it.

More

• API reference →
• MCP server: connect an AI assistant →
• Questions about MCP and the API →
• Privacy Policy: AI assistants and keys →
• Terms: connected apps and AI assistants →
• Contact us →