Tools

Running actions

Find a tool, run it for one of your users, and handle approvals.

Find a tool

GET /v1/tools/search with q (plain words), and optionally toolkits, executable=true and limit. Needs tools:read.

curl "https://setu.supremeai.services/api/setu/v1/tools/search?q=send%20an%20email&executable=true&limit=5" \
  -H "Authorization: Bearer $SETU_API_KEY"

Run it: POST /v1/executions

Needs tools:execute. Answers 200 with the result, 202 with approval_required for write actions, or 428 connect_required if the user has not connected the app.

Part	Notes
Idempotency-Key header	Required. Your own id, so a retry never runs the action twice.
Setu-External-User header	The user the action runs for (your id for them).
action	The action name, e.g. GMAIL_SEARCH.
arguments	The action’s arguments.
dryRun	Optional. Check the call without running it.

# Run an action for one of your users.
# Idempotency-Key: your own id, so a retry never runs the action twice.
curl https://setu.supremeai.services/api/setu/v1/executions \
  -H "Authorization: Bearer $SETU_API_KEY" \
  -H "Setu-External-User: customer_42" \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "GMAIL_SEARCH",
    "arguments": { "query": "in:inbox" }
  }'

# Write actions (for example GMAIL_SEND_EMAIL) answer 202 with
# "approval_required": true until someone approves them.
# 428 "connect_required" means the user has not connected the app yet.

Approvals

Write actions (sending email, adding a row, creating an event and similar) wait for approval. Approve or deny with the approvals API; each approval is used once.

# Approve (or deny) a write action that is waiting.
curl https://setu.supremeai.services/api/setu/v1/approvals/$APPROVAL_ID \
  -H "Authorization: Bearer $SETU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approve", "reason": "Checked the draft" }'

Get API key All docs