Capture from your phone

A task is a personal to-do — yours alone, never visible to teammates. Agents create them while they work, you tick them off, and each one can carry an intent like "turn this into a note". The web app is the comfortable place to work through them; this page is about the other half: getting a thought into Alkahest in three seconds, from a phone, without opening anything.

The endpoint behind it is one plain HTTPS request, so anything that can POST can capture a task — iOS Shortcuts, the macOS Shortcuts app, a Raycast script, curl in a terminal alias.

The short way

On alkahest.app → API tokens, switch the form to Task capture and create. Captured tasks always go to your Inbox; if you're in more than one workspace the form asks which one, because the Tasks view only shows the workspace you're currently in — a task filed to the other one reads as a task that never arrived. What you get back is a token plus the exact three values the Shortcuts app asks for — URL, headers, body — each with a copy button. Paste them into the steps below and you're done.

A capture token is deliberately small: it can create tasks and nothing else — it can't publish, read your maps, or touch your notes. It also remembers its workspace, which is why its request body is a single field. If you lose the phone, revoke that one row and the rest of your setup keeps working.

A full-access token (the CLI/MCP one) works here too — it just has to say which workspace itself. Widget tokens from the report widget do not: they're rejected with a 403.

The request

POST https://ytcmzkrvtomtcrcyqqcb.supabase.co/functions/v1/tasks-post
Authorization: Bearer alk_your_token
Content-Type: application/json

{ "title": "Rename the export button" }

That's the whole contract — no apikey header, no session. It answers { "ok": true, "task": { … } }, and the task lands in your Inbox.

To try it before wiring anything up:

curl -sX POST https://ytcmzkrvtomtcrcyqqcb.supabase.co/functions/v1/tasks-post \
  -H "authorization: Bearer $ALKAHEST_TOKEN" \
  -H "content-type: application/json" \
  -d '{"title":"hello from curl"}'

Build the iOS Shortcut

<!-- ONE-TAP SLOT: iOS only installs signed shortcuts from an iCloud share link, so there is no safe file to host in this repo (a raw .shortcut needs "Allow Untrusted Shortcuts" switched on). When we have a link from the Shortcuts app's Share → Copy iCloud Link, put it right here as a one-tap install button and demote the manual steps below to "or build it yourself". -->

1. Open Shortcuts → + → name it Add to Alkahest.
2. Add Ask for Input — prompt New task (or whatever you want to see it say), input type Text.
3. Add Get Contents of URL and set the URL to https://ytcmzkrvtomtcrcyqqcb.supabase.co/functions/v1/tasks-post.
4. Expand Show More:
   • Method → POST
   • Headers → Authorization = Bearer alk_your_token, Content-Type = application/json
   • Request Body → JSON, one field: title (Text) = the Provided Input from step 2.
5. Using a full-access token instead of a capture token? Add a second JSON field: workspace (Text) = the slug of the workspace you want. Without it — and with more than one workspace — the request comes back 400 ambiguous_workspace; Alkahest won't guess. That response lists your workspaces, so running the shortcut once is the easiest way to find the slug. A capture token skips all of this: the workspace is baked in.
6. Run it once to confirm, then Share → Add to Home Screen. One tap on the icon = a text box = a task in your Inbox.

Add Show Result at the end while you're setting it up — it prints the JSON, which makes typos in the token or headers obvious. Delete it once it works.

Variations worth the extra minute

• Share sheet capture. In the shortcut's settings turn on Show in Share Sheet and drop the Ask for Input step; use the Shortcut Input as the title instead. Now a selected sentence in Safari, Mail or a messenger becomes a task without retyping it. Put the page URL in body and the task detail view renders it as a clickable link.
• Dictation. Replace the input step with Dictate Text and the shortcut works hands-free from Siri: "Hey Siri, add to Alkahest."
• On the Mac. The same shortcut syncs to macOS Shortcuts, where you can give it a keyboard shortcut or pin it to the menu bar.

Fields you can send

Field	What it does
title	Required. The one line you'll see in the list.
body	Markdown detail — links here are clickable in the web app.
due_on	YYYY-MM-DD.
tags	An array of strings; a leading # is stripped.
slug	Tag the task with a project. Omit it and the task is a plain Inbox task.
workspace	Which workspace an Inbox task belongs to. A capture token already knows; a full-access token needs this when you're in several.
dedup_key	Your own idempotency key: re-posting the same key updates that task instead of adding a second one. Makes a flaky mobile connection safe to retry.
note_mode	keep or enrich — this task's content should end up as a note. See below.
note	The target note's slug. Implies note_mode: "keep".
skill	The name of a skill describing how that note should be written.

Capturing thoughts as notes, not to-dos

note_mode turns the shortcut into a thought inbox. A task posted with "note_mode": "enrich" is a standing instruction to your agent: research this and write it up. With "keep" it's file this text as-is. Next time an agent works through your tasks, it does exactly that and the task closes as a note in your project — so a stray idea on the bus becomes a documented one without you opening an editor.

A second home-screen icon posting {"title": …, "note_mode": "enrich"} is a good pairing: one button for things to do, one for things to look into.

Nothing merges on its own — an agent does the writing, and it needs a standing instruction to look for these tasks. The recipe is in Note recipes → Capture now, write later.

If it doesn't work

Response	What it means
401 invalid_token	Typo in the header, or the token was revoked. The value must be Bearer alk_….
403 insufficient_scope	That token may not create tasks — a widget token. Use a capture or full-access one.
400 ambiguous_workspace	A full-access token in an account with several workspaces. The response lists them — add "workspace": "<slug>" to the body (or a "slug" for a project, which settles it too), or mint a capture token, which carries one.
400 bad_request	Usually an empty title, or a due_on that isn't YYYY-MM-DD.
404 not_found	The slug / workspace / skill you named doesn't exist or isn't yours.

Good to know

• Tasks are personal. There's no assigning one to a teammate — pointing a task at someone else would only hide it from you and never reach them.
• The token is stored in the shortcut on your device. A capture token bounds the damage — task creation in one workspace is all it can do — but anyone who can run the shortcut can still write tasks as you, so treat a shared iPad accordingly. Revoking it on the Tokens page stops the shortcut immediately and affects nothing else.
• Everything you capture shows up in the Tasks view of your account, alongside what your agents filed there — but as yours: a capture token's tasks carry no agent chip and sit under the By me lens, because you wrote them. Tasks your agents create still show theirs.