# Dash API (/docs/products/dash-dots/reference/dash-api)

Everything your dot can ask of the phone and of Dash: alerts, the camera, contacts, the network, storage and more. In a page, call it as `this.dash`. In `dot.ts`, it's `dash`.

For the everyday jobs, start with the [Use Dash features](/docs/products/dash-dots/developers/dash-apis) guide.

## Groups

| Group                                                              | Calls                               | What they do                                                                                                                  |
| ------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| [UI](/docs/products/dash-dots/reference/dash-api/ui)               | `dash.ui`                           | Show an alert, or let the person pick a date or a time with the phone's own pickers.                                          |
| [System](/docs/products/dash-dots/reference/dash-api/system)       | `dash.system`                       | Vibrate, use the torch, keep the screen on, copy, share, open the dialer or a web page, wait, and read facts about the phone. |
| [Media](/docs/products/dash-dots/reference/dash-api/media)         | `dash.media`                        | Let the person take or choose a photo, choose a file from their phone, or scan a QR code.                                     |
| [Contacts](/docs/products/dash-dots/reference/dash-api/contacts)   | `dash.contacts`                     | Let the person choose a phone number from their contacts.                                                                     |
| [Account](/docs/products/dash-dots/reference/dash-api/account)     | `dash.account`                      | Sign the person in to your dot with their Dash account.                                                                       |
| [Payments](/docs/products/dash-dots/reference/dash-api/payments)   | `dash.payments`                     | Take a payment in Dash's own payment sheet, by linked account, card or mobile money, and read it back later.                  |
| [Reminders](/docs/products/dash-dots/reference/dash-api/reminders) | `dash.reminders`                    | Remind the person with a notification that opens your dot at one of its pages, once or on a schedule.                         |
| [Network](/docs/products/dash-dots/reference/dash-api/network)     | `dash.network`, `dash.network.http` | Check whether the phone is online, and send requests, downloads and uploads to your server.                                   |
| [Files](/docs/products/dash-dots/reference/dash-api/files)         | `dash.storage.file`                 | Keep files on the phone that only your dot can read, and work with the files Dash gives your dot.                             |
| [Cache](/docs/products/dash-dots/reference/dash-api/cache)         | `dash.storage.cache`                | Keep values on the phone for a while, each with an optional expiry time.                                                      |
| [Secrets](/docs/products/dash-dots/reference/dash-api/secrets)     | `dash.storage.secret`               | Keep small private values, such as a session token, encrypted on the phone.                                                   |
| [Crypto](/docs/products/dash-dots/reference/dash-api/crypto)       | `dash.crypto`                       | Work out hashes and HMAC signatures, and make random bytes and UUIDs.                                                         |
| [Utils](/docs/products/dash-dots/reference/dash-api/utils)         | `dash.utils`                        | Convert text to base64 or hex and back, without waiting for Dash.                                                             |
| [Dot](/docs/products/dash-dots/reference/dash-api/dot)             | `dash.dot`                          | Close the dot from your code, the same as going back from its first page.                                                     |
| [Helpers](/docs/products/dash-dots/reference/dash-api/helpers)     | `@monimesl/dot-runtime`             | Tell errors apart, handle a picker the person closed, and search as the person types.                                         |
| [Versions](/docs/products/dash-dots/reference/dash-api/versions)   | `dash`                              | Check whether the person's Dash has a call, and how Dash API versions work.                                                   |

## Calls

Every call returns a `DashRequest`: a promise you await for the result, which you can also cancel. Every call also takes an optional last argument, `CallOptions`, with a `timeout` in milliseconds. Without one, a call waits as long as it takes.

```ts
const request = this.dash.network.http.request({ url: `${env.API_URL}/shows` }, { timeout: 10_000 });
// Later, if the answer is no longer needed:
request.cancel(); // the call fails with `cancelled`
```

A call that fails rejects with a `DashError`, whose `code` says why. See [Helpers](/docs/products/dash-dots/reference/dash-api/helpers) for checking it.

| `code`        | Meaning                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `unsupported` | The person's Dash can't do this, such as an older Dash or a phone without a camera. Catch it and offer something else.         |
| `denied`      | Not allowed: the dot didn't declare the permission in `dot.json`, the person said no, or the address isn't in `network.hosts`. |
| `cancelled`   | The call stopped before it finished: you cancelled it, the person closed a picker or scanner, or the page that made it closed. |
| `timeout`     | The call took longer than the `timeout` you gave it.                                                                           |
| `invalid`     | The call's options are wrong, such as an address that doesn't start with https.                                                |
| `missing`     | There's nothing there, such as a file the dot hasn't saved yet.                                                                |
| `failed`      | Dash tried and couldn't finish, such as when a server doesn't answer.                                                          |