Platform guide

Stacksona for Custom REST

Q: What statuses should my workflow allow?

Execute the gated action only on allow or approved. Stop, retry, notify, or route to fallback for every other state.

Use direct Stacksona Gate API calls from any platform that can make HTTP requests.

REST APIWorks anywhere HTTP works

Use direct HTTP calls for platforms that do not have a native Stacksona package, or when you want the smallest possible integration surface.

Bring your own Gate URL and agent key

Set STACKSONA_GATE_URL to your own Stacksona Gate endpoint, usually https://{gate-id}.stacksona.cloud. Set STACKSONA_API_KEY to the sg_ agent key for the agent making the request.

Full API reference

For every endpoint, schema, response field, webhook payload, signed approval token behavior, tool rule type, and error code, use the standard Gate API reference.

Open Gate API Reference

First successful call

Create a decision request before the risky action executes.

bash

curl -X POST "$STACKSONA_GATE_URL/api/agent/tasks/task_123/requests" \
  -H "Authorization: Bearer $STACKSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_name": "Customer Support",
    "task_label": "Approve customer email",
    "tool_name": "send_email",
    "subject": "Send reply to customer@example.com",
    "preview": "Agent drafted a customer-facing reply.",
    "risk_level": "medium"
  }'

Recommended pattern

Prepare action→POST decision request→Branch on status→Execute only if allowed

Check a decision

bash

curl "$STACKSONA_GATE_URL/api/agent/decisions?thread_id=thread_123" \
  -H "Authorization: Bearer $STACKSONA_API_KEY"

Validate an approval token

bash

curl -X POST "$STACKSONA_GATE_URL/api/agent/approvals/validate" \
  -H "Authorization: Bearer $STACKSONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"task_123","signature":"APPROVAL_TOKEN"}'

Decision handling

Status	Behavior
`allow`	Execute immediately.
`pending_review`	Poll briefly, store the decision ID, or resume through a webhook callback.
`approved`	Execute after review.
`reject` or `rejected`	Do not execute.

Integration FAQ

Can I use Stacksona with Custom REST today?

Yes. Use the documented native package when one exists. Otherwise, use the REST API, HTTP module, webhook action, or a small Node sidecar with @stacksona/sdk.

Where should Stacksona sit in a Custom REST workflow?

Place Stacksona immediately before the action that sends, updates, deletes, refunds, posts, deploys, or calls a production API.

What statuses should my workflow allow?

Execute the gated action only on allow or approved. Stop, retry, notify, or route to fallback for every other state.