Skip to main content
Your workspace has one public URL. Everything under it reaches the workspace, so the same URL serves the built-in endpoints below, any endpoint your agent writes, and the files your automations produce.
Find yours under Settings → API on the workspace, or ask the agent.

​
Authentication

Every call carries your workspace’s API key. It sits next to the URL on the same settings page, and starts with dk_.
If the service you are calling from has already claimed its Authorization header, send the key in x-desert-api-key instead. One form or the other, not both:
A missing or wrong key gets a 401 and never reaches your workspace. Generating a new key revokes the old one on the spot. There is no grace period and no expiry list, because the reason to press that button is that the old key should stop working. Anything still using it starts failing immediately, so change the callers first, or be ready to. See Authentication for what a 401 tells you, how to tell a wrong key from a wrong URL, and why file links need no key at all.

​
Every automation is already on it

There is nothing to register, switch on, or generate. If an automation shows up in your Automations tab, it is readable through the API right now. The API is built from the same two things the app is: the list of automations your agent registered, and the record kept for every run. Both already exist, because without them the app would have no catalogue and no history. The endpoints below are a second way of reading what was already there. Two consequences worth knowing:
  • A new automation needs no API work. The moment it appears in the app, its runs are readable. Nobody has to remember a second step.
  • An automation only appears if it goes through the run record. That is how every automation is built. It is also why the History tab works, so anything missing here is missing there too. Tell the agent if you see that.

​
The four you always have

List automations

What this workspace can do.

List runs

What one automation has done, newest first.

Check a run

Whether it finished, and how long it took. Poll this one.

Get the result

What it produced.
Each page has a request builder you can run against your own workspace. A typical read is two calls: check the run until status is done, then fetch the result.
Check the run rather than polling the result. The run answer stays small however large the thing the automation produced, so polling it costs the same every time.

​
Results are the automation’s own shape

result is whatever the automation returned, unchanged. A report automation might return markdown, a lookup might return an object, a check might return a single number. Two automations answering different questions have no reason to agree on a shape, so nothing reshapes them on the way out. Read one finished run to see what a given automation returns, or ask the agent.

​
Anything else your agent wrote

The four above are what every workspace has. Beyond them, any path under your base URL reaches your workspace. An endpoint your agent writes is live the moment it exists, path parameters and query string intact.
Give me an endpoint our ops tool can call to get today’s unresolved defects as JSON.
The agent writes the route and hands you the URL. Nothing gets registered.

​
Files

Anything that is a file, rather than an answer, takes /~file in front of the path:
~file is not a folder. It tells the platform to wake your workspace and then send you there for the bytes. The file never passes through the platform, so a download costs a redirect instead of a copy. The link itself is unchanged by this: same wake, and it still works a week later. Follow the redirect, which every HTTP client does by default. See Download a file. File links are the one thing here that needs no API key, and that is on purpose: they are made to be clicked, and a browser following a link out of an email cannot be asked to set a header. So a file link is its own credential — anyone holding one can fetch that file. Send them the way you would send the file. Use it for PDFs, photographs and spreadsheets. Leave it off for JSON, where a redirect would only add a round trip.

​
Worth knowing

  • The key is the credential, the URL is the address. Keep the key out of public repos, frontend code and shared docs — anything holding it can read everything this API serves. The URL is worth keeping quiet too, since it opens your workspace’s pages in a browser, but it is the key that authorises a call.
  • A sleeping workspace wakes on the first call. Workspaces sleep when idle, so a first request after a quiet spell can take 10 to 60 seconds. Later ones are immediate. Set your client’s timeout accordingly.
  • 600 requests a minute, shared across the whole workspace including anyone looking at its pages. Past that you get a 429.
  • A handler gets 30 seconds once the workspace is awake, then the caller gets a 504 and it is not retried. Work that takes longer should start a run and return its id, which is what these endpoints are for.
  • Relayed answers are capped at 4MB. Files fetched through /~file are not, because they never pass through the platform.