# URL Scheme

> Create and open Done Bear tasks from Shortcuts and other apps with the donebear URL scheme.

Use the `donebear` URL scheme from Shortcuts, bookmarklets, and other apps on the same iPhone. This is an automation scheme, like Things' `things:///add`. It is separate from the https links that already open a workspace, task, or settings screen.

The scheme is handled by the iOS app. Add URLs need an auth token stored on that device. Show URLs do not.

## Auth token

1. Open Done Bear on iPhone.
2. Go to **Settings → URL Scheme**.
3. Copy the auth token.

Add URLs must include `auth-token`. Without it, or with a token that does not match, the app refuses to create a task. Rotate the token if it leaked. Disable it to reject add URLs without deleting the token; Enable turns it back on.

The token never leaves the device. It is not an API key and the server does not see it.

## Add a task

```text
donebear:///add?title=Buy%20milk&when=today&auth-token=YOUR_TOKEN
```

`donebear://add?...` (host form) is accepted too.

| Parameter                | Required                   | Description                                                                                                                                                                                                                               |
| ------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`                  | one of `title` or `titles` | Task title.                                                                                                                                                                                                                               |
| `titles`                 | one of `title` or `titles` | Newline-separated titles. Creates one task per line.                                                                                                                                                                                      |
| `auth-token`             | yes                        | The token from Settings → URL Scheme.                                                                                                                                                                                                     |
| `notes` or `description` | no                         | Description body.                                                                                                                                                                                                                         |
| `when`                   | no                         | `inbox`, `today`, `upcoming`, `anytime`, `someday`, or a start date `YYYY-MM-DD`. Default is today. A deadline with no `when` lands in Anytime. A project with no `when` lands in Inbox. A deadline wins over a project for that default. |
| `deadline`               | no                         | Due date `YYYY-MM-DD`.                                                                                                                                                                                                                    |
| `list` or `project`      | no                         | Project name or key. `list=Inbox` (and the other view names) sets `when` instead.                                                                                                                                                         |
| `tags` or `labels`       | no                         | Comma-separated labels. Unknown names are skipped.                                                                                                                                                                                        |
| `workspace`              | no                         | Workspace URL slug. Defaults to the workspace currently selected in the app.                                                                                                                                                              |
| `reveal`                 | no                         | `true` to open the created task. Default is false.                                                                                                                                                                                        |

Dates are calendar days (`YYYY-MM-DD`), not times.

## Show a list, search, or task

```text
donebear:///show?id=today
donebear:///show?query=launch
donebear:///show?id=92a73695-d772-4b43-9fb4-d79f5fbef300
```

Show does not use `auth-token`.

| Parameter   | Description                                                                    |
| ----------- | ------------------------------------------------------------------------------ |
| `id`        | `inbox`, `today`, `upcoming`, `anytime`, `someday`, `logbook`, or a task UUID. |
| `query`     | Opens search. Wins over `id` when both are present.                            |
| `workspace` | Workspace URL slug.                                                            |

## Shortcuts

1. Add an **Open URLs** action.
2. Set the URL to `donebear:///add?title=...&auth-token=...`.
3. Run the shortcut. Done Bear comes to the foreground and creates the task in the signed-in account.

Keep the token out of shared shortcuts and browser bookmarks. Store it in a password manager and paste it in when you build the shortcut.

## Not covered

Navigation links such as `https://donebear.com/acme/today` already exist and are unchanged. This scheme does not add Watch or Calendar callbacks, JSON batch payloads, or Things' `update` / `add-project` commands.

## Next steps

- Read [CLI overview](/cli) for terminal automation.
- Read [Raycast](/raycast) for keyboard-driven task management on Mac.