Connect your agent · Task 04 · 4 min
Use the API
Call Syndcast operations over plain HTTP from your own code with an agent token.
The API is the door for your own code. Every operation is one HTTP request.
Before you start
You need an agent token. Send it as a bearer token on every request.
Step 1 of 5
Call an operation
Send a POST to /api/agent/v1/<family>/<verb>. The body is a JSON object with the operation's inputs. The answer is JSON.
curl -X POST https://syndcast.com/api/agent/v1/access/me \
-H "Authorization: Bearer <your token>" \
-H "Content-Type: application/json" \
-d '{}'
Add the header x-syndcast-door: cli only if you are the command line. Any other value, or none, counts as the API.
Step 2 of 5
Find the operations
The OpenAPI document lists every operation, its inputs and its answers:
https://syndcast.com/api/agent/v1/openapi.json
It supports If-None-Match, so a client can keep a copy and ask for a new one only when it changes.
Step 3 of 5
Status codes
| Status | Meaning |
|---|---|
| 200 | It worked. |
| 400 | The body was not valid JSON. |
| 401 | The token is missing, wrong, revoked or expired. |
| 403 | Not allowed, or the request needs approval (approval_required). |
| 404 | The operation or the thing it names does not exist. |
| 409 | The request conflicts with the current state, or something is busy. |
| 422 | The inputs are wrong. |
| 429 | Too many requests. Wait for the Retry-After header. |
| 500 | A fault on our side. |
| 503 | Syndcast cannot answer right now. Try again. |
An error answer is a JSON object with a code and a message.
Step 4 of 5
Approvals
The API does not wait for a person. When a request needs a yes, it answers approval_required with status 403. The person answers in the channel's Agent tab. Read the open requests with confirmations.list, then send the same request again.
Step 5 of 5
Page through lists
An operation that returns a list may include nextCursor in its answer. Send the same request again with cursor set to that value to get the next page. When there is no nextCursor, you have everything.