API reference
Trigger a staff member
POST /api/pub/v1/staff/{address}/trigger, hand an AI staff member a piece of work from your own server and read the reply back.
https://api.dhanu.ai/api/pub/v1/staff/{address}/triggerHands a staff member a piece of work through its API address, the opaque
stf_… string on the staff member’s Channels tab. A task is created in the
staff member’s workspace and the reply is written to it in the background, so the
call returns at once with the task and you read its messages
to see the answer.
The run spends workspace credits like any other task; the trigger itself is not billed. Everything you send is treated as untrusted text: the staff member reports on it, it never obeys instructions inside it.
Request
| Path parameter | Type | Required | Notes |
|---|---|---|---|
address | string | Yes |
| Field | Type | Required | Notes |
|---|---|---|---|
input | string | Yes | The work to hand over, as plain text. At least 1 characters, up to 50000 characters. |
subject | string | No | |
threadId | string | No | Continue an earlier task instead of starting a new one. |
curl -X POST https://api.dhanu.ai/api/pub/v1/staff/stf_abc123/trigger \
-H "Authorization: Bearer $DHANU_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "input": "Draft minutes for today\u0027s stand-up.", "subject": "Stand-up minutes" }'import { Dhanu } from "dhanu";
const dhanu = new Dhanu(process.env.DHANU_API_KEY!);
const task = await dhanu.tasks.trigger({
address: "stf_abc123",
input: "Draft minutes for today's stand-up.",
subject: "Stand-up minutes",
idempotencyKey: crypto.randomUUID(),
});import os
import uuid
from dhanu import Dhanu
dhanu = Dhanu(os.environ["DHANU_API_KEY"])
task = dhanu.tasks.trigger(
address="stf_abc123",
input="Draft minutes for today's stand-up.",
subject="Stand-up minutes",
idempotency_key=str(uuid.uuid4()),
)Pass threadId, a task id from an earlier trigger, to continue that task
instead of opening a new one.
Response
202 Accepted
{
"task": {
"id": "…",
"title": "Stand-up minutes",
"createdAt": "2026-09-17T10:15:00.000Z",
"updatedAt": "2026-09-17T10:15:00.000Z"
}
}Errors
| Code | Status | Meaning |
|---|---|---|
invalid_api_key | 401 | The bearer key is missing or unknown. |
api_key_revoked | 401 | The key was revoked. |
api_key_expired | 401 | The key passed its expiry date. |
api_key_ip_not_allowed | 403 | The caller's IP is outside the key's allowlist. |
developer_access_revoked | 403 | The key's creator lost developer access in the workspace. |
api_key_project_scope | 403 | The key covers no active projects, or projectId is outside its scope. |
invalid_request_body | 422 | The body did not match the schema; error.issues names each field. |
channel_route_not_found | 404 | No staff member in the key's workspace has that trigger address. |
The full list is on Errors.