Choosy: API

Choosy's API

Choosy has a URL-based API. Opening a specially formatted URL will cause Choosy to spring into action, and send a link to the right browser.

A Choosy API URL looks like this: x-choosy://api-method/web-url

The web-url part tells Choosy which Web address it should open, and the api-method part tells Choosy what to do with it.

Here's a real example: x-choosy://prompt.all/https://www.georgebrock.com

Opening that URL will tell Choosy to prompt you to select from all of your browsers, and to open https://www.georgebrock.com in the browser you pick.

API methods

API method	Description
`open`	Choosy should decide what to do based on the user's settings.
`prompt.all`	Choosy should prompt the user to select from all of their browsers.
`prompt.running`	Choosy should prompt the user to select from all of their browsers that are currently running (or all of their browsers, if none are running).
`best.all`	Choosy should use the user's favourite browser, i.e. the one at the top of their browser list.
`best.running`	Choosy should use the user's favourite browser that's already running, i.e. of the running browsers, the one nearest to the top of their browser list. If none are running, their overall favourite will be used.

Using the API

Exactly how you trigger the API will depend on the programming tools that you are using. To get you started, here are a few examples:

From the Terminal, or in a shell script, you can use the Choosy API via the open command:
```
open x-choosy://open/https://example.com
```

From AppleScript, you can use the open location command:

set choosy_url to "x-choosy://open/https://example.org"
open location choosy_url

In a browser, browser extension, or bookmarklet, you can set the window's location:
```
const url = "x-choosy://open/https://example.com";
window.location.href = url;
```

In a Swift application using AppKit you can use NSWorkspace's openURL method:

let url: URL! = URL(
  string: "x-choosy://open/https://example.com"
)
NSWorkspace.shared.open(url: url)

Custom API methods

Choosy's rule system allows you to define behaviours that match custom API methods, giving you the power to expand the API in whatever way you choose.

Follow these step-by-step instructions to create a custom API method.