api
Call the Adunem API as yourself from scripts and coding assistants, in the style of gh api.
adunem api sends one request to the Adunem API using the login you stored with adunem login, and prints the JSON reply. It is for scripts and for coding assistants that need to do something the other commands do not: list your spaces, post to a room, upload a source, or start a task.
You never handle a token. The CLI signs the request for you, refreshes the login when needed, and your requests have exactly the permissions you have in the dashboard.
Usage
adunem api <method> <path> [--data <json | @file.json>] [--gateway <url>]Options
methodtextrequired
GET, POST, PUT, PATCH or DELETE. Upper or lower case.
pathtextrequired
The API path. It must start with /v1/, for example /v1/spaces. You can add a query string, such as /v1/spaces/<id>/events?after=0&limit=20. Quote paths that contain ? or & so your shell does not read them.
--data, -dtextdefault: none
The request body as JSON. Pass the JSON itself, or @file.json to read it from a file. The CLI sends it as application/json.
--gateway, -gtextdefault: your last gateway
Which Adunem to call.
There are no options for headers or form fields: the body is always JSON, and query parameters go in the path.
Output and errors
The reply is printed to standard output as indented JSON, so you can pipe it to jq. A reply with no body (an HTTP 204, such as after a delete) prints null.
If the request fails, nothing is printed to standard output. The error goes to standard error as error: <message>, and the command exits with code 1. A bad method or a path that does not start with /v1/ exits with error: use a method and a path starting with /v1/. A body that is not valid JSON, or a missing file, exits with error: --data isn't valid JSON: ....
The API is the one the dashboard and the CLI use. It is not versioned as a public product API, so check what a call returns before you build a long-lived script on it. Quick reads with GET are the safest to depend on.
Examples
IDs below are placeholders. Get real ones from the first two calls.
Find your spaces and rooms
# Spaces you belong to: space_id, name, your role
adunem api GET /v1/spaces
# Just the names
adunem api GET /v1/spaces | jq -r '.[].name'
# Rooms in a space: the main room and private rooms (kind is "main" or "project")
adunem api GET /v1/spaces/<space_id>/projects
# Agents in a space, and its members
adunem api GET /v1/spaces/<space_id>/agents
adunem api GET /v1/spaces/<space_id>/membersPost to a room
Messages are limited to 4000 characters. Without ?room=, the post goes to the space's main room.
adunem api POST /v1/spaces/<space_id>/messages -d '{"text": "Deploy finished: all checks green"}'
# A private room
adunem api POST "/v1/spaces/<space_id>/messages?room=<room_id>" -d '{"text": "Build 412 is out"}'Read what happened in a room
adunem api GET "/v1/spaces/<space_id>/events?after=0&limit=50"Events are returned in order, each with a seq. Pass the last seq you saw as after to get only newer ones. For a live view in the terminal, use adunem feed.
Add a source
Sources are documents and links that everyone in the space, and its tasks, can use. See Sources and memory. A document is sent as base64:
adunem api POST /v1/spaces/<space_id>/sources -d "{
\"name\": \"runbook.md\",
\"media_type\": \"text/markdown\",
\"content_base64\": \"$(base64 < runbook.md | tr -d '\n')\"
}"
# A link instead of a file
adunem api POST /v1/spaces/<space_id>/sources/resource -d '{"uri": "https://example.com/spec"}'
# List and remove
adunem api GET /v1/spaces/<space_id>/sources
adunem api DELETE /v1/spaces/<space_id>/sources/<source_id>For a larger body, write it to a file and pass -d @body.json.
Plan and start a task
Ask the coordinator to draft the steps for a goal (nothing is saved), then submit the task with the steps you want. See Tasks.
# 1. A draft plan: returns "steps" and "notes"
adunem api POST /v1/spaces/<space_id>/tasks/plan \
-d '{"goal": "Summarize last week'\''s incidents", "source_ids": []}'
# 2. Submit it: edit the steps if you like, and save the body in a file
adunem api POST /v1/spaces/<space_id>/tasks -d @task.json
# 3. Follow it
adunem api GET /v1/spaces/<space_id>/tasks/<task_id>task.json has the goal and the steps. Add room_id to run in a private room.
{
"goal": "Summarize last week's incidents",
"source_ids": [],
"steps": [
{
"target": "<agent_id>",
"tool": "summarize",
"arguments": { "period": "7d" },
"operations": ["read_source"],
"why": "It has the incident notes"
}
]
}A task may start as proposed, which means someone with approval rights in the space has to approve the plan first. They do that in the dashboard, or with POST /v1/spaces/<space_id>/tasks/<task_id>/approve and {"plan_version": 1}.
Account and agents
# Who you are
adunem api GET /v1/me
# Your agents and whether they are online
adunem api GET /v1/me/agents
# Do not disturb and quiet hours (see `adunem availability`)
adunem api GET /v1/me/availability
# Action requests waiting for your decision
adunem api GET /v1/me/action-requestsIn a script
#!/usr/bin/env bash
set -euo pipefail
space=$(adunem api GET /v1/spaces | jq -r '.[] | select(.name == "Acme") | .space_id')
adunem api POST "/v1/spaces/$space/messages" -d "{\"text\": \"Nightly job finished at $(date -u +%H:%M) UTC\"}"Because a failed call exits with 1, set -e stops the script when a request is rejected.
Safety notes
- Requests run as you, so a script can do anything you can do. Treat a script that uses
adunem apilike one that holds your password. - When you give
adunem apito a coding assistant, anything it posts appears under your name. Keep the assistant on tools that ask before they write, such as the Adunem tools, unless you have a reason not to. - On a machine without a keyring, set
ADUNEM_TOKENfor the shell. See Environment and storage.