Skip to main content

​
API Overview

The Steward API is a REST API built with Hono running on Bun. All responses follow a consistent ApiResponse<T> shape.

​
Base URL

https://api.steward.fi
For self-hosted instances, replace with your deployment URL.

​
Authentication

Steward supports three authentication methods:
For tenant-level operations (agent CRUD, policy management, secret management):
curl https://api.steward.fi/agents \
  -H "X-Steward-Key: stwd_your_tenant_api_key"
The API key is returned once when a tenant is created and cannot be retrieved again.

​
Platform Key

For platform-level operations (cross-tenant management), use the platform key: 
curl https://api.steward.fi/platform/stats \
  -H "X-Steward-Platform-Key: your-platform-key"

​
Response Format

All endpoints return a consistent format: 
// Success
{
  "ok": true,
  "data": T  // Response payload
}

// Error
{
  "ok": false,
  "error": "Human-readable error message",
  "data"?: T  // Optional additional context (e.g., policy results)
}

​
HTTP Status Codes

CodeMeaning
200Success
201Created (new resource)
202Accepted (transaction queued for approval)
400Bad request (invalid input)
401Unauthorized (missing or invalid auth)
403Forbidden (policy denied, wrong scope)
404Not found
409Conflict (duplicate resource)
500Internal server error
502Bad gateway (RPC error from blockchain)

​
Rate Limits

The API does not currently enforce global rate limits. Per-agent rate limits are configured via policies.

​
Route Groups

PrefixDescriptionAuth Required
/agentsAgent CRUD + policy managementTenant key or agent JWT
/vaultSigning, approvals, historyAgent JWT or tenant key
/secretsSecret + route CRUDTenant key only
/tenantsTenant managementTenant key
/authSIWE, passkeys, email loginVaries
/platformCross-tenant adminPlatform key
/healthHealth checkNone

​
Content Type

All request bodies must be JSON: 
Content-Type: application/json

​
Error Handling

import { StewardClient, StewardApiError } from "@stwd/sdk";

try {
  await steward.signTransaction("my-agent", { ... });
} catch (error) {
  if (error instanceof StewardApiError) {
    console.error(`Status: ${error.status}`);
    console.error(`Message: ${error.message}`);
    console.error(`Data:`, error.data); // May contain policy results
  }
}