What it does
The API covers one piece of work end to end: create it, read what Briedo knows about it and whether it is ready, answer an open question, fetch the finished document and manage handover. Workspace setup, policy, gate decisions and prerequisites stay in the app.
If all you need is to push work in, the signed webhook is simpler and needs no key.
What Briedo reads
Whatever you send. The API reads nothing from your systems on its own.
What Briedo may write
Only in your own workspace, and only what your key’s capabilities allow. A read-only key can see delivery status and change nothing about it.
Permissions you are granting
| Capability | What it allows |
|---|---|
| read | Every read below. |
| read and write | The reads, plus creating work, answering questions and managing handover. |
How to connect
- Ask Briedo to switch the API on. Until it is on, every call answers 503 service-disabled.
- Settings, then API keys.
- Create a key with the capabilities you need. The secret is shown once.
- Note the base address shown on the same screen — it includes your workspace.
- To create work through the API, also turn on Create a discovery automatically: Settings, then Integrations, then Before discovery, under Automation. Without it, a create answers 409 auto_create_discovery_disabled.
How to route work
There is no routing rule. Your call names the workspace and says what it is creating.
How mapping works
Creating a piece of work carries identity and, optionally, values for things Briedo wants to know. Answering an open question carries one value for one item.
The same rules apply as everywhere else: your values are subject to what your setup allows that source to settle, and something with parts must be sent as parts.
How to test it
- Once Briedo has switched the API on, start with a read — list the work in your workspace. It proves the key, the signature and the address in one call. A 503 service-disabled means the API is not on yet, not that your key is wrong.
- Create one piece of work and read it back.
- Repeat the create with the same idempotency key and confirm you get the same piece of work rather than a second.
How to know it is working
- Reads return your workspace’s work and nobody else’s.
- A repeated write with the same key changes nothing the second time.
- Errors come back in a consistent machine-readable shape with a type you can branch on.
When it goes wrong
| What you see | What it means |
|---|---|
| Service disabled (503) | Briedo has not switched the API on yet. Your key is fine. |
| Unauthorised | The key, the signature or the signed path does not match. You sign the path you actually requested, including its query string. |
| Forbidden | The key is read-only and the call writes. Create a key with write access. |
| Conflict (409) | Read the code. payload_mismatch: the same idempotency key was used for a different body. in_progress: that request is still running, so retry it shortly. auto_create_discovery_disabled: turn on Create a discovery automatically. Any other code is a delivery state you must act on, such as reconnecting the destination. |
| Not found for an address you expected | The sub-resource vocabulary is closed. An unknown one is a 404 rather than falling through to something else. A piece of work that is not yet part of the discovery view Briedo switches on with you also answers 404 on its discovery-state, readiness, brief, handoff, actions and deliveries addresses. |
How to disconnect
Revoke the key in Settings. It stops working immediately.
What happens to what it already told us
Nothing is deleted. Work that was already prepared keeps everything it learned, including the record that this system is where it came from. Those are records of what was true at the time, and disconnecting a system later does not make them untrue.
What stops is new information arriving. Deleting historical data is a separate request, and a deliberate one.