REST API reference
The /api/v1 surface — create threads, send turns, read state, and stream events over SSE.
The /api/v1 surface is how something other than a browser drives the swarm: CI, a script, or another product. Integrations & API covers all the ways in; this page describes the API itself operation by operation.
Authentication
A single bearer token guards the whole surface. Send it with every request; there's no separate session or handshake to manage. Keep it server-side — the same rule that applies to the LLM keys and git credentials darting.dev holds for you.
The operations
Four operations cover the lifecycle of a thread. That's the whole model: a thread is the unit of work here exactly as it is in the UI.
| Operation | What you supply | What happens / comes back |
|---|---|---|
| Create a thread | A first prompt | A fresh sandbox and branch are provisioned and the turn is queued; you get back the thread to address afterwards |
| Send a follow-up turn | An existing thread and your next message | The turn is queued on that thread, in the same sandbox, with the same history |
| Read a thread | An existing thread | Its status and message history |
| Stream events | An existing thread | A live Server-Sent Events feed of the run |
Creating a thread is asynchronous by nature — provisioning an environment and running an agent takes longer than an HTTP request should. So creation queues the work and you observe it, either by polling the read operation or by streaming.
Streaming
The stream is the same event spine the browser rides. There's no separate API-only event format and no lossy summary channel: your client sees what a user watching the thread would see, as it happens.
That has a useful consequence — a client running on one server can stream an agent running on another. A CI job can tail a run to completion, a bot can relay progress into chat, and your own UI can render the run without proxying through darting.dev's front end. See the event spine for what flows through it.
API threads are just threads
A thread created over the API is a normal chat thread. It appears in the workspace with its full transcript, its diffs, and its video proof — so when a run needs judgment, you open it and take over mid-flight. Nothing is marked "machine-created" or fenced off from human turns, and the reverse holds too: a thread you started by typing can be continued over the API.
What people build with it
- CI kicking off a fix thread. A red build posts the failing job's output as a first prompt; the agent lands a fix on its own branch and opens a pull request.
- A script fanning out work. One repetitive migration across many files or services becomes many threads, each on its own branch, landing through the merge queue.
- Another product embedding the swarm. Create a thread from your own UI and stream it back to your users.
Other ways in
Not everything needs a client. GitHub webhooks can route issue and PR comments straight into a project's agent, and inbound hooks POST external events onto the event spine for automations to react to. Both are covered in integrations.