Matcha 2.0 URL Scheme Reference

You can call Matcha from any application using the following URL scheme syntax:

matcha://[action]/[resourcePath]?[parameter list]

You can also use x-callback-url URL scheme. In this case, Matcha support returning control back to source app and return data using by specifying return URL in x-success and x-error.

matcha://x-callback-url/[action]/[resourcePath]?[parameter list]&x-source=[...]&...

Open file/folder

matcha://open/[resourcePath]?text=[...]&selection=[...]&afterSuccess=[...]

Open file specified in resourcePath. If specified resource refer to a folder, it will be opened in Drawer.

Parameter Definition:

  • resourcePath

    Specify full file/folder path to open. Prepend path with “/Dropbox” for Dropbox path or “/iCloud” for iCloud path.

  • selection: from[-to]

    Automatic select text at specified location. to can be omitted to just place cursor at from location. To specify text at end of document, just specify a very big value.

  • afterSuccess: none|close|open|edit

    Specify close with process the request, close the document and return to previous opened document (if any).

Examples:

  • Open Dropbox file /Personal/To Do List.txt.

    matcha://open/Dropbox/Personal/To%20Do%20List.txt
    
  • Open iCloud folder /Matcha/Backlog.

    matcha://open/iCloud/Matcha/Backlog
    

    This will open drawer and navigate to specified folder.

  • Open local file /Wisdom Writer/Welcome.txt, scroll to last position of the document and enter writing mode.

    matcha://open/Wisdom%20Writer/Welcome.txt?&selection=99999&afterSuccess=edit
    

Create file

matcha://create/[resourcePath]?text=[...]&selection=[...]&afterSuccess=[...]

Create a new file specified in resourcePath and add content specified in text. Matcha will parse text parameter as markdown. If resourcePath refers to a folder, Matcha will create a new file inside specified folder. If it refers to existing file, Matcha will automatically append (1), (2),... to end of file name, ex: New Document (1).

If you specify return URL using x-callback-url specification, Matcha will append path=[new document path] to the URL.

Parameter Definition:

  • resourcePath

    You can specify either file or folder path here. Refer to note above for more details.

  • text

    URL encoded text to insert to file. This text will be parsed as markdown.

  • selection: from[-to]

    Automatic select text at specified location. to can be omitted to just place cursor at from location. To specify text at end of document, just specify a very big value.

  • afterSuccess: none|close|open|edit

    Specify close with process the request, close the document and return to previous opened document (if any). Default action is open.

Examples:

  • Create new Dropbox file in root folder named “New Document.txt” with text “Enjoy Matcha” and automatically move cursor to the end of text.

    matcha://create/Dropbox/New%20Document.txt&text=Enjoy%20Matcha&selection=999999
    
  • Create new local document with text “# Hello World” in local root folder with automatic file naming.

    matcha://create/?text=%23%20Hello%20World
    
  • Create new local document with text “# Hello World” and call back source app specified in x-success on success.

    matcha://x-callback-url/create/?text=%23%20Hello%20World&x-success=matcha%3A%2F%2Fopen
    

    In example above, on success, Matcha will open matcha://open and append parameter path=[new document path] to x-success URL.

Append to file

matcha://append/[resourcePath]?text=[...]&selection=[...]&afterSuccess=[...]

Append some text specified in text parameter to file specified in resourcePath. If resourcePath doesn’t refer to valid file, it will behave like creating file.

Parameter Definition:

  • resourcePath

    Specify a valid file path here.

  • text

    URL encoded text to insert to file. You can specify markdown text here.

  • selection: from[-to]

    Automatic select text at specified location. to can be omitted to just place cursor at from location. To specify text at end of document, just specify a very big value.

  • afterSuccess: none|close|open|edit

    Specify close with process the request, close the document and return to previous opened document (if any). Default action is open.

Examples:

  • Append text “\n\n- Matcha” to /Sample List.txt.

    matcha://append/Sample%20List.txt?text=%0A%0A-%20Matcha&afterSuccess=edit
    

    Note: the text will be parsed as list item.

Search file and favorites

matcha://search/?q=[...]

This will open favorites and recent file screen if q is empty, or else it will show search result for specified keyword.

Parameter Definition:

  • q

    Search text/keywords.

Example:

  • Open favorite document list.

    matcha://search
    
  • Search file that contain text “Matcha”

    matcha://search?q=Matcha
    

Example

Use the following examples to see Marcha URL Scheme in action. You can open the link to try it.

 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk