# X-callback-url Scheme documentation > X-callback-URLs are an API for operating with Bear. Among other things you can open a note or a tag, add text or file, rename or delete tags, and archive notes Source: https://bear.app/faq/x-callback-url-scheme-documentation/ Bear implements the [x-callback-url][1] protocol, which allow iOS and Mac developers to expose and document API methods they make available to other apps and return useful data. Bear URL Scheme actions look like this: `bear://x-callback-url/[action]?[action parameters]&[x-callback parameters]` with x-success and x-error as available x-callback parameters. ## Actions * [/open-note](#open-note) - [/create](#create) * [/add-text](#add-text) - [/add-file](#add-file) * [/tags](#tags) - [/open-tag](#open-tag) - [/rename-tag](#rename-tag)- [/delete-tag](#delete-tag) * [/trash](#trash) - [/archive](#archive) - [/untagged](#untagged) - [/todo](#todo)- [/today](#today) - [/locked](#locked) * [/search](#search) - [/grab-url](#grab-url) * [/open-workspace](#open-workspace) - [/close-workspace](#close-workspace) ### /open-note Open a note identified by its title or id and return its content. **parameters** * **id** _optional_ note unique identifier. * **title** _optional_ note title. * **header** _optional_ an header inside the note. * **exclude\_trashed** _optional_ if `yes` exclude trashed notes. * **new\_window** _optional_ if `yes` open the note in an external window (MacOS only). * **float** _optional_ if `yes` makes the external window float on top (MacOS only). * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). * **open\_note** _optional_ if `no` do not display the new note in Bear’s main or external window. * **selected** _optional_ if `yes` return the note currently selected in Bear ([token][10] required) * **pin** _optional_ if `yes` pin the note to the top of the list. * **edit** _optional_ if `yes` place the cursor inside the note editor. * **search** _optional_ opens the in-note find&replace panel with the specified text **x-success** * **note** note text. * **identifier** note unique identifier. * **title** note title. * **tags** note tags array * **is\_trashed** `yes` if the note is trashed. * **modificationDate** note modification date in [ISO 8601 format][2]. * **creationDate** note creation date in [ISO 8601 format][3]. **example** `bear://x-callback-url/open-note?id=7E4B681B` `bear://x-callback-url/open-note?id=7E4B681B&header=Secondary%20Ttitle` Create and try /open-note actions in seconds with our [URL builder online](https://bear.app/xurl/open-note/) --- ### /create Create a new note and return its unique identifier. Empty notes are not allowed. **parameters** * **title** _optional_ note title. * **text** _optional_ note body. * **clipboard** _optional_ if `yes` use the text currently available in the clipboard * **tags** _optional_ a comma separated list of tags. * **file** _optional_ base64 representation of a file. * **filename** _optional_ file name with extension. Both *file* and *filename* are required to successfully add a file. * **open\_note** _optional_ if `no` do not display the new note in Bear's main or external window. * **new\_window** _optional_ if `yes` open the note in an external window (MacOS only). * **float** _optional_ if `yes` make the external window float on top (MacOS only). * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). * **pin** _optional_ if `yes` pin the note to the top of the list. * **edit** _optional_ if `yes` place the cursor inside the note editor. * **timestamp** _optional_ if `yes` prepend the current date and time to the text * **type** *optional* if `html` the provided *text* parameter is converted from html to markdown * **url** *optional* if *type* is `html` this parameter is used to resolve relative image links **x-success** * **identifier** note unique identifier. * **title** note title. **example** `bear://x-callback-url/create?title=My%20Note%20Title&text=First%20line&tags=home,home%2Fgroceries` **notes** The base64 **file** parameter have to be [encoded][6] when passed as an url parameter. Create and try /create actions in seconds with our [URL builder online](https://bear.app/xurl/create/) --- ### /add-text append or prepend text to a note identified by its title or id. Encrypted notes can't be accessed with this call. **parameters** * **id** _optional_ note unique identifier. * **title** _optional_ title of the note. * **selected** _optional_ if `yes` use the note currently selected in Bear ([token][10] required) * **text** _optional_ text to add. * **clipboard** _optional_ if `yes` use the text currently available in the clipboard * **header** _optional_ if specified add the text to the corresponding header inside the note. * **mode** _optional_ the allowed values are `prepend`, `append`, `replace_all` and `replace` (keep the note's title untouched). * **new_line** _optional_ if `yes` and `mode` is `append` force the text to appear on a new line inside the note * **tags** _optional_ a comma separated list of tags. * **exclude\_trashed** _optional_ if `yes` exclude trashed notes. * **open\_note** _optional_ if `no` do not display the new note in Bear's main or external window. * **new\_window** _optional_ if `yes` open the note in an external window (MacOS only). * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). * **edit** _optional_ if `yes` place the cursor inside the note editor. * **timestamp** _optional_ if `yes` prepend the current date and time to the text **x-success** * **note** note text. * **title** note title. **example** `bear://x-callback-url/add-text?text=new%20line&id=4EDAF0D1&mode=append` Create and try /add-text actions in seconds with our [URL builder online](https://bear.app/xurl/add-text/) --- ### /add-file append or prepend a file to a note identified by its title or id. This call can't be performed if the app is a locked state. Encrypted notes can't be accessed with this call. **parameters** * **id** _optional_ note unique identifier. * **title** _optional_ note title. * **selected** _optional_ if `yes` use the note currently selected in Bear ([token][10] required) * **file** _required_ base64 representation of a file. * **header** _optional_ if specified add the file to the corresponding header inside the note. * **filename** _required_ file name with extension. Both *file* and *filename* are required to successfully add a file. * **mode** _optional_ the allowed values are `prepend`, `append`, `replace_all` and `replace` (keep the note's title untouched). * **open\_note** _optional_ if `no` do not display the new note in Bear's main or external window. * **new\_window** _optional_ if `yes` open the note in an external window (MacOS only). * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). * **edit** _optional_ if `yes` place the cursor inside the note editor. *x-success* * **note** note text **example** `bear://x-callback-url/add-file?filename=test.gif&id=4EDAF0D1-2EFF-4190-BC1D-67D9BAE49BA9-28433-000187BAA3D182EF&mode=append&file=R0lGODlhAQABAIAAAP%2F%2F%2F%2F%2F%2F%2FyH5BAEKAAEALAAAAAABAAEAAAICTAEAOw%3D%3D` **notes** The base64 **file** parameter have to be [encoded][9] when passed as an url parameter. Create and try /add-file actions in seconds with our [URL builder online](https://bear.app/xurl/add-file/) --- ### /tags Return all the tags currently displayed in Bear's sidebar. **parameters** * **token** _required_ application [token][10]. *x-success* * **tags** json array representing tags. `[{ name }, ...]` **example** `bear://x-callback-url/tags?token=123456-123456-123456` Create and try /tags actions in seconds with our [URL builder online](https://bear.app/xurl/tags/) --- ### /open-tag Show all the notes which have a selected tag in bear. **parameters** * **name** _required_ tag name or a list of tags divided by comma * **token** _optional_ application [token][12]. *x-success* * **notes** json array representing the tag's notes. `[{ title, identifier, modificationDate, creationDate, pin }, ...]` Encrypted notes will be excluded from the notes array. If more than one tag is passed with the `name` parameter this action returns all the notes matching one of the tags passed. If _token_ is not provided nothing is returned. **example** `bear://x-callback-url/open-tag?name=work` `bear://x-callback-url/open-tag?name=todo%2Fwork` Create and try /open-tag actions in seconds with our [URL builder online](https://bear.app/xurl/open-tag/) --- ### /rename-tag Rename an existing tag. This call can't be performed if the app is a locked state. If the tag contains any locked note this call will not be performed. **parameters** * **name** _required_ tag name. * **new\_name** _required_ new tag name. * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). **example** `bear://x-callback-url/rename-tag?name=todo&new_name=done` Create and try /rename-tag actions in seconds with our [URL builder online](https://bear.app/xurl/rename-tag/) --- ### /delete-tag Delete an existing tag. This call can't be performed if the app is a locked state. If the tag contains any locked note this call will not be performed. **parameters** * **name** _required_ tag name. * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). **example** `bear://x-callback-url/delete-tag?name=todo` Create and try /delete-tag actions in seconds with our [URL builder online](https://bear.app/xurl/delete-tag/) --- ### /trash Move a note to bear trash and select the Trash sidebar item. This call can't be performed if the app is a locked state. Encrypted notes can't be used with this call. **parameters** * **id** _optional_ note unique identifier. * **search** _optional_ string to search. * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). **example** `bear://x-callback-url/trash?id=7E4B681B` `bear://x-callback-url/trash?search=old` **notes** The **search** term is ignored if an **id** is provided. Create and try /trash actions in seconds with our [URL builder online](https://bear.app/xurl/trash/) --- ### /archive Move a note to bear archive and select the Archive sidebar item. This call can't be performed if the app is a locked state. Encrypted notes can't be accessed with this call. **parameters** * **id** _optional_ note unique identifier. * **search** _optional_ string to search. * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). **example** `bear://x-callback-url/archive?id=7E4B681B` `bear://x-callback-url/archive?search=projects` **notes** The **search** term is ignored if an **id** is provided. Create and try /archive actions in seconds with our [URL builder online](https://bear.app/xurl/archive/) --- ### /untagged Select the Untagged sidebar item. **parameters** * **search** _optional_ string to search. * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). * **token** _optional_ application [token][18]. *x-success* * **notes** json array representing the untagged notes. `[{ title, identifier, [tag, ...], modificationDate, creationDate, pin }, ...]` Encrypted notes will be excluded from the notes array. If _token_ is not provided nothing is returned. **example** `bear://x-callback-url/untagged?search=home` Create and try /untagged actions in seconds with our [URL builder online](https://bear.app/xurl/untagged/) --- ### /todo Select the Todo sidebar item. **parameters** * **search** _optional_ string to search. * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). * **token** _optional_ application [token][20]. *x-success* * **notes** json array representing the todo notes. `[{ title, identifier, [tag, ...], modificationDate, creationDate, pin }, ...]` Encrypted notes will be excluded from the note array. If _token_ is not provided nothing is returned. **example** `bear://x-callback-url/todo?search=home` Create and try /todo actions in seconds with our [URL builder online](https://bear.app/xurl/todo/) --- ### /today Select the Today sidebar item. **parameters** * **search** _optional_ string to search. * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). * **token** _optional_ application [token][22]. *x-success* * **notes** json array representing the today notes. `[{ title, identifier, [tag, ...], modificationDate, creationDate, pin }, ...]`f Encrypted notes will be excluded from the note array. If _token_ is not provided nothing is returned. **example** `bear://x-callback-url/today?search=family` Create and try /today actions in seconds with our [URL builder online](https://bear.app/xurl/today/) --- ### /locked Select the Locked sidebar item. **parameters** * **search** _optional_ string to search. * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). **example** `bear://x-callback-url/locked?search=data` Create and try /locked actions in seconds with our [URL builder online](https://bear.app/xurl/locked/) --- ### /search Show search results in Bear for all notes or for a specific tag. **parameters** * **term** _optional_ string to search. * **tag** _optional_ tag to search into. * **show\_window** _optional_ if `no` the call don't force the opening of bear main window (MacOS only). * **token** _optional_ application [token][25]. *x-success* * **notes** json array representing the note results of the search. `[{ title, identifier, [tag, ...], modificationDate, creationDate, pin }, ...]` Encrypted notes will be excluded from the note array. If _token_ is not provided nothing is returned. **example** `bear://x-callback-url/search?term=nemo&tag=movies` Create and try /search actions in seconds with our [URL builder online](https://bear.app/xurl/search/) --- ### /grab-url Create a new note with the content of a web page. **parameters** * **url** _required_ url to grab. * **tags** _optional_ a comma separated list of tags. If tags are specified in the Bear's web content prefences this parameter is ignored. * **pin** _optional_ if `yes` pin the note to the top of the list. * **wait** _optional_ if `no` x-success is immediately called without _identifier_ and _title_. **x-success** * **identifier** note unique identifier. * **title** note title. **available values** `yes` `no` **example** `bear://x-callback-url/grab-url?url=https://bear.app` Create and try /grab-url actions in seconds with our [URL builder online](https://bear.app/xurl/grab-url/) ### /open-workspace Open a selected tag as a workspace **parameters** * **name** tag to open as workspace. **example** `bear://x-callback-url/open-workspace?name=work` --- ### /close-workspace Closes any workspace opened in Bear **example** `bear://x-callback-url/close-workspace` --- ## Token Generation In order to extend their functionalties, some of the API calls allow an app generated token to be passed along with the other parameters. Please mind a Token generated on iOS is not valid for MacOS and vice-versa. On MacOS, select `Help` → `Advanced` →`API Token` → `Copy Token` and will be available in your pasteboard. On iOS go to the preferences → `Advanced`, locate the `API Token` section and tap the cell below to generate the token or copy it in your pasteboard. ## Support To discuss URL scheme improvements or reporting bugs please use our [Support Form][30] or Bear's subreddit. [1]: http://x-callback-url.com/ [2]: https://en.wikipedia.org/wiki/ISO_8601 [3]: https://en.wikipedia.org/wiki/ISO_8601 [4]: https://bear.app/xurlbuilder/open-note/ [5]: https://bear.app/xurlbuilder/create/ [6]: https://www.w3schools.com/tags/ref_urlencode.asp [7]: https://bear.app/xurlbuilder/add-text/ [8]: https://bear.app/xurlbuilder/add-file/ [9]: https://www.w3schools.com/tags/ref_urlencode.asp [10]: #token-generation [11]: https://bear.app/xurlbuilder/tags/ [12]: #token-generation [13]: https://bear.app/xurlbuilder/open-tag/ [14]: https://bear.app/xurlbuilder/rename-tag/ [15]: https://bear.app/xurlbuilder/delete-tag/ [16]: https://bear.app/xurlbuilder/trash/ [17]: https://bear.app/xurlbuilder/archive/ [18]: #token-generation [19]: https://bear.app/xurlbuilder/untagged/ [20]: #token-generation [21]: https://bear.app/xurlbuilder/todo/ [22]: #token-generation [23]: https://bear.app/xurlbuilder/today/ [24]: https://bear.app/xurlbuilder/locked/ [25]: #token-generation [26]: https://bear.app/xurlbuilder/search/ [27]: https://bear.app/xurlbuilder/grab-url/ [28]: https://bear.app/xurlbuilder/change-theme/ [29]: https://bear.app/xurlbuilder/change-font/ [30]: https://bear.app/contact/