Skip to content
DOCUMENTATION

Quickstart

How to send an Agent’s calls through the FleetWarrant Gateway, and what to do with the record it keeps.

01

Base URL and authentication

Every Agent calls FleetWarrant through one endpoint, the Gateway. It speaks the OpenAI and the Anthropic API formats, so there’s no new SDK to install.

Base URL
https://gateway.fleetwarrant.com

This is FleetWarrant’s production Gateway, in AWS ap-southeast-2 (Sydney). Every Tenant uses it. We’ll tell you directly before its address changes.

Authenticate every request with your Agent’s API key. It is fwk_ followed by 43 characters, and the Gateway accepts it in either of these headers. OpenAI-style clients send the first; Anthropic SDKs and Claude Code send the second.

Headers
Authorization: Bearer <agent-api-key>
x-api-key: <agent-api-key>

The shell examples on this page read the base URL and the key from two variables. Set them once:

shell
export FW_GATEWAY="https://gateway.fleetwarrant.com"
export FW_AGENT_KEY="<agent-api-key>"
The Dashboard shows an Agent’s API key once, when you create the Agent, and never again. Put it in your secrets manager or environment straight away. Never paste it into email, chat or a support ticket. If it leaks, open the Agent’s menu in the Dashboard: Rotate key replaces it with a new one, and Revoke key turns it off for good once you type REVOKE. Admins can do this for any Agent, builders for the Agents they created.

Onboarding is hands-on for now. We create your Tenant, and your admin creates Agents in the Dashboard. If you don’t have a Tenant yet, see Support.

Back to contents

02

How your Agent’s calls reach FleetWarrant

Your Agent stops calling Anthropic, OpenAI or Bedrock directly. Change two settings in whatever it’s built on:

  • Base URL. Point it at the Gateway instead of the provider.
  • API key. Use the Agent’s fwk_ key instead of a provider key.

The Gateway checks the key and works out which Agent is calling. It swaps in the provider credential your Connector holds, forwards the call and records it. Your fwk_ key never reaches the provider, and the provider credential never reaches your Agent.

Which routes answer depends on your Connector’s provider:

Gateway routes by Connector provider
Connector/v1/chat/completions/v1/messages/v1/responses
AnthropicYes, streaming tooYes, streaming tooNo (400)
Amazon BedrockYes, streaming tooNo (400)No (400)
OpenAIYes, streaming tooNo (400)Yes, streaming too

On every route that answers, streamed or not, the Gateway records the tool calls the model asks for.

FleetWarrant only records calls that go through the Gateway. Anyone on your team who still has a real provider key can set up an Agent that skips FleetWarrant entirely. Keep the provider credential in your Connector only, and give developers and Agents fwk_ keys.

Back to contents

03

Connect your Agent

The base URL differs between the two SDK families, because each adds its own path to it:

  • Anthropic SDKs and Claude Code: https://gateway.fleetwarrant.com, with no /v1. The SDK adds /v1/messages.
  • OpenAI SDKs and OpenAI-compatible frameworks: https://gateway.fleetwarrant.com/v1, with /v1.

The SDK examples read the key from the FW_AGENT_KEY environment variable.

Claude Code

Needs an Anthropic Connector. Set these before starting it:

shell · Claude Code
export ANTHROPIC_BASE_URL="$FW_GATEWAY"
export ANTHROPIC_API_KEY="$FW_AGENT_KEY"
# Both must be models your Agent may use:
export ANTHROPIC_MODEL="<model-id>"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="<small-model-id>"

The first time Claude Code starts with a custom API key, it asks you to approve it once. To skip that, set ANTHROPIC_AUTH_TOKEN to the key instead of ANTHROPIC_API_KEY. It is sent as Authorization: Bearer, which the Gateway also accepts. Set one or the other, not both.

Every model Claude Code calls must be one your Agent may use. That includes its default model, which changes when a new model is released, and a smaller model it uses for background work. If it asks for one your Agent can’t use, Claude Code shows “There’s an issue with the selected model”. Pick an allowed model (claude --model <model-id>, or /model in a session), set the two model variables above, or add the model to your Agent with Edit models in the Dashboard.

Anthropic SDK

Needs an Anthropic Connector.

Python · anthropic
import os

import anthropic

client = anthropic.Anthropic(
    base_url="https://gateway.fleetwarrant.com",  # no /v1
    api_key=os.environ["FW_AGENT_KEY"],
)

message = client.messages.create(
    model="<model-id>",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)
TypeScript · @anthropic-ai/sdk
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://gateway.fleetwarrant.com", // no /v1
  apiKey: process.env.FW_AGENT_KEY,
});

const message = await client.messages.create({
  model: "<model-id>",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});
console.log(message.content);

OpenAI SDK

Works with any Connector. Through an OpenAI Connector, the Responses API (client.responses.create) works too.

Python · openai
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.fleetwarrant.com/v1",
    api_key=os.environ["FW_AGENT_KEY"],
)

completion = client.chat.completions.create(
    model="<model-id>",
    messages=[{"role": "user", "content": "Hello"}],
)
print(completion.choices[0].message.content)
TypeScript · openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.fleetwarrant.com/v1",
  apiKey: process.env.FW_AGENT_KEY,
});

const completion = await client.chat.completions.create({
  model: "<model-id>",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(completion.choices[0].message.content);

Agent frameworks and self-hosted agents

LangChain, the Vercel AI SDK and any agent with a “custom endpoint” or “base URL” setting work the same way. Choose the OpenAI provider option for any Connector, or the Anthropic one for an Anthropic Connector. Then set the base URL and API key as above. A tool that only offers a sign-in to your provider account, with no base URL or key setting, can’t be routed through FleetWarrant.

Back to contents

04

Your first request (OpenAI format)

POST https://gateway.fleetwarrant.com/v1/chat/completions takes the same request as OpenAI’s Chat Completions API. model and messages are the only required fields. Use a model your Agent is allowed to call.

curl · /v1/chat/completions
curl -sS "$FW_GATEWAY/v1/chat/completions" \
  -H "Authorization: Bearer $FW_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "<model-id>",
  "messages": [
    {
      "role": "user",
      "content": "Summarise the open invoices."
    }
  ]
}'

A successful call returns:

200 response
{
  "id": "chatcmpl-01jazyb3x8k9q2m4n5p6r7s8t9",
  "object": "chat.completion",
  "created": 1758500000,
  "model": "<model-id>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 96,
    "total_tokens": 120
  }
}

Tools

tools and tool_choice work on every Connector. The Gateway forwards them to OpenAI, and translates them for Anthropic and Bedrock. When it translates, a feature the provider can’t express is refused with a 400 that names it, never dropped: "strict": true, a tool that isn’t a function, and on Bedrock, "tool_choice": "none" or "parallel_tool_calls": false.

Fields the Gateway refuses

A few fields OpenAI accepts aren’t supported yet. Rather than accept and ignore them, the Gateway refuses the call with a 400 invalid_request_error that names the field: response_format, n, stop, top_p, seed, logprobs, presence_penalty and frequency_penalty. For seed, the message is:

error message
'seed' is not supported by this gateway yet and was rejected rather than silently accepted and ignored -- see fleetwarrant#85. Retry without 'seed'.

Message content must be text. An image or file part is refused the same way. So is stream_options without "stream": true, or with any key other than include_usage.

A field the Gateway doesn’t know isn’t refused. An OpenAI Connector forwards it. Anthropic and Bedrock Connectors drop it, and name it in the X-FleetWarrant-Ignored-Params response header.

Back to contents

05

Streaming responses

Add "stream": true to the same request and the Gateway answers with Server-Sent Events, on every Connector. Each frame is a chat.completion.chunk, the shape the OpenAI SDK already reads, sent as data: {...}. A literal data: [DONE] ends the stream.

curl · /v1/chat/completions, streaming
curl -sS -N "$FW_GATEWAY/v1/chat/completions" \
  -H "Authorization: Bearer $FW_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "<model-id>",
  "messages": [
    {
      "role": "user",
      "content": "Summarise the open invoices."
    }
  ],
  "stream": true
}'
text/event-stream
data: {"id":"chatcmpl-01jazyb3x8k9q2m4n5p6r7s8t9","object":"chat.completion.chunk","created":1758500000,"model":"<model-id>","choices":[{"index":0,"delta":{"content":"Sum"},"finish_reason":null}]}

data: ...

data: [DONE]

Stream any call that may take more than a minute to answer. See Time limits.

Back to contents

06

Anthropic Messages API

With an Anthropic Connector, the Gateway also serves Anthropic’s own POST /v1/messages, and passes the request through unchanged. Tools, images, prompt caching, extended thinking and streaming work as Anthropic documents them, and errors come back in Anthropic’s format. Claude Code and the Anthropic SDKs use this route.

curl · /v1/messages
curl -sS "$FW_GATEWAY/v1/messages" \
  -H "x-api-key: $FW_AGENT_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "<model-id>",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Summarise the open invoices."
    }
  ]
}'

Add "stream": true for Anthropic’s own event stream, relayed as Anthropic sends it:

curl · /v1/messages, streaming
curl -sS -N "$FW_GATEWAY/v1/messages" \
  -H "x-api-key: $FW_AGENT_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "<model-id>",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Summarise the open invoices."
    }
  ],
  "stream": true
}'

A Bedrock or OpenAI Connector gets a 400 on this route. Use /v1/chat/completions for those.

Back to contents

07

Limits and errors

Rate limits

Each Agent API key can send 6,000 requests in 5 minutes, and each source IP address 30,000. Over either limit, the Gateway answers 429 with retry-after: 300. Over the per-key limit, the response is:

429 response
retry-after: 300

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "This Agent API key is sending more than 6,000 requests in 5 minutes. Slow down and retry.",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

Time limits

A call can run for up to 600 seconds, streams included. Within that, the Gateway has to send something at least every 60 seconds: the first byte within 60 seconds, and no longer gap after it. A call without streaming sends nothing until the model has finished, so stream any call that may take longer than a minute.

The Gateway gives your provider 30 seconds to accept a connection, and 60 seconds between reads.

A model your Agent can’t use

A call for a model that isn’t on the Agent’s allow-list is refused. On the OpenAI-format routes it gets a 403 permission_error; on /v1/messages, a 404 not_found_error. The message names the Agent and lists the models it may use:

error message
Agent '<agent-name>' (<agent-id>) is not allowed to use model '<model-id>'; allowed models: <model-ids>. Use one of those, or open this Agent in your FleetWarrant Dashboard and choose Edit models.

Back to contents

08

What gets redacted

The Gateway sees each request and response in the clear while it forwards the call to your provider. What it keeps is a separate matter. By default it does not keep the raw request and response: it keeps a redacted preview, encrypted under your Tenant’s own KMS key, plus the call’s metadata. If a Tenant admin turns on raw capture, it archives the full request and response as well, encrypted under a per-Event key.

Redaction applies to the preview. It runs on every call, on every Tenant, with nothing to configure, and removes two kinds of value.

Sensitive-looking field names

Any JSON key, at any depth in the request or the response, that contains one of these, ignoring case: password, passwd, secret, api_key, apikey, authorization, access_token, refresh_token, private_key, ssn, social_security, credit_card, card_number, cvv and client_secret. Its value becomes [REDACTED]. That catches a stray credential in a tool-call argument or a metadata field, whatever it’s called.

Secret-shaped text in a message

Prompt and completion text is scanned for a small set of high-confidence shapes. Each match is replaced in place, and the prose around it is left alone:

AWS access key IDs
AKIA..., followed by 16 more characters
FleetWarrant Agent API keys and registration secrets
fwk_... / fwreg_...
OpenAI API keys
sk-...
Anthropic API keys
sk-ant-...
Generic bearer tokens
Bearer <token>
US Social Security Numbers
123-45-6789, hyphenated only, not bare or space-separated digits
Email addresses
jane@example.com
Credit-card numbers
4111 1111 1111 1111, 13-19 digits, Luhn-valid runs only
This is not a general PII or secrets scanner. It is a fixed set of rules, the ones listed above, and nothing broader. Names, addresses, tax IDs, and other business or personal data that isn’t one of those specific shapes is not detected or masked, and neither is a credential in a format the rules don’t recognise yet. Don’t rely on this to keep sensitive data out of your audit trail. If that matters for your traffic, keep it out of the prompt.
Redaction doesn’t reach the raw copy. With raw capture on, a value the preview removed is still in the encrypted raw copy in the archive. Encryption protects it; it doesn’t redact it. Each raw body can be shredded on request or by your raw-body retention, and a legal hold pauses shredding. Turning raw capture off stops new raw bodies, and leaves the ones already archived until they are shredded.

Back to contents

09

Using the Dashboard API

Some settings below have a screen in the Dashboard. The rest are set through the Dashboard API for now, the API the Dashboard itself calls. It takes your Dashboard sign-in, not an Agent API key. Your onboarding contact gives you its URL. Set two variables in your terminal:

shell · Dashboard API
export FW_API="<dashboard-api-url>"
export FW_ID_TOKEN="<id-token>"

Until the Dashboard has a button that copies your ID token, you read it from your browser. This is a stopgap. Sign in to the Dashboard, open your browser’s developer console on that page, and run this one line:

browser console
JSON.parse(sessionStorage.getItem("fw_dashboard_session")).id_token
Run only this line, copied from this page. Never paste code that someone sends you into your browser console: it runs as you. The ID token is your sign-in credential, so keep it in your terminal and never send it by email, chat or support ticket. It expires. When calls start returning 401, sign in again and copy a new one.

What you can change depends on your Dashboard role. Admins can do everything on this page. Builders manage the Agents they created. Viewers can read, and can request evidence exports. Each section says where a step is admin-only.

Routes are written with their parameters in braces, such as {agent_id}. An Agent id is agt_ followed by 26 characters.

Back to contents

10

Sessions

The Gateway groups an Agent’s calls into sessions, so you can read one task as a timeline instead of a flat list of calls. It uses the first of these that a call carries:

  • Your own session id, in the X-FleetWarrant-Session header. This always wins. It can be 1 to 128 printable ASCII characters, and is used exactly as sent. Calls with the same value share a session, however far apart they are.
  • Claude Code’s own session id. Claude Code sends one on every call (the x-claude-code-session-id header), and the Gateway picks it up. There is nothing to set up. Each Claude Code session, tool loops and subagents included, becomes one FleetWarrant session.
  • Neither. The Gateway groups the Agent’s calls itself, and starts a new session after a gap of more than 15 minutes. These sessions are marked as inferred, so they are never mistaken for an id you sent.

Send the header on any Gateway call. Here it is on the first request, with a shorter body:

curl · X-FleetWarrant-Session
curl -sS "$FW_GATEWAY/v1/chat/completions" \
  -H "Authorization: Bearer $FW_AGENT_KEY" \
  -H "X-FleetWarrant-Session: invoice-review-2026-09-26" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model-id>","messages":[{"role":"user","content":"Hello"}]}'

To give a Claude Code run your own session id, set it as a custom header before starting Claude Code. It stays the same for the whole process, so set a new one for each run you want kept apart:

shell · Claude Code
export ANTHROPIC_CUSTOM_HEADERS="X-FleetWarrant-Session: invoice-review-2026-09-26"

A session id is only a label for the audit trail. An invalid one is ignored, never refused, so it can’t cost you a call. None of these headers is forwarded to the provider. From Claude Code’s request, FleetWarrant keeps only the session id, not the device or account ids sent beside it.

List an Agent’s sessions, newest first:

GET /v1/dashboard/agents/{agent_id}/sessions
curl -sS "$FW_API/v1/dashboard/agents/<agent-id>/sessions" \
  -H "Authorization: Bearer $FW_ID_TOKEN"

GET /v1/dashboard/sessions/{session_id} returns one session’s Events and totals.

Back to contents

11

Alerts: Slack and webhooks

Alerts go to Slack channels and to signed HTTPS webhooks. Each channel chooses which alert types it gets. Alerts are sent in the background and never slow down an Agent’s calls. Adding, changing and testing channels is admin-only.

Slack

In Slack, create an incoming webhook (Apps → Incoming Webhooks). In the Dashboard, open Alerts → + New channel, choose Slack and paste the https://hooks.slack.com/... URL. It is stored encrypted and never shown again.

Webhooks

Choose Webhook and enter a public https:// URL on port 443. Or use the API:

POST /v1/dashboard/alert-channels
curl -sS -X POST "$FW_API/v1/dashboard/alert-channels" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "webhook",
  "display_name": "ops-alerts",
  "url": "https://alerts.example.com/fleetwarrant",
  "alert_types": [
    "budget.threshold",
    "usage.threshold",
    "agent.suspended",
    "agent.resumed",
    "circuit_breaker.tripped"
  ]
}'

The response includes the channel’s signing_secret, which starts fwwhsec_. It is shown once, so store it straight away. If you lose it, POST /v1/dashboard/alert-channels/{channel_id}/rotate-secret issues a new one. Then send a test alert, with Send test alert on the channel’s row or through the API. The result shows on the channel as its last delivery:

POST /v1/dashboard/alert-channels/{channel_id}/test
curl -sS -X POST "$FW_API/v1/dashboard/alert-channels/<channel-id>/test" \
  -H "Authorization: Bearer $FW_ID_TOKEN"

Alert types

Switch types on per channel, in the Dashboard’s channel form or in alert_types through the API. The form offers each of these:

budget.threshold
An Agent or Tenant budget crossed a threshold, plus a daily reminder while over budget.
usage.threshold
An Agent went over its requests-per-minute or tokens-per-minute alert level.
agent.suspended
An Agent was suspended, or the Tenant emergency stop was used.
agent.resumed
An Agent was resumed, or “resume all” was used.
circuit_breaker.tripped
One of an Agent’s circuit breakers tripped.
call.blocked
The Gateway refused an Agent’s call.
model.available
A Connector’s provider offers a new model.
agent.key_changed
An Agent’s API key was revoked or rotated.
export.failing
A continuous export destination has failed to deliver for 15 minutes, with no success in between. Sent once per run of failures.

The form lists export.created as coming soon. Nothing sends it yet.

Send test alert sends a test alert to that one channel; it needs no switch. Repeated usage.threshold alerts within a minute are rolled up into one digest alert.

What a webhook receives

A POST with a JSON body like the one below. Money is always US$, as a decimal string in a field ending _usd. Alerts carry ids, counts and amounts, never a prompt, a response or a key. Delivery is at least once, so de-duplicate on alert_id.

webhook body
{
  "alert_id": "alt_01k5yq3z8v0c9m2d7h4n6r1t5w",
  "data": {
    "level": "warning",
    "limit_usd": "500.00",
    "period": "month",
    "period_start": "2026-09-01",
    "spent_usd": "400.12",
    "threshold_percent": 80
  },
  "links": {
    "dashboard": "https://dashboard.example.com/agents/agt_01j9z1h2k3m4n5p6q7r8s9t0v2"
  },
  "occurred_at": "2026-09-25T01:02:03.456Z",
  "schema_version": 1,
  "subject": { "agent_id": "agt_01j9z1h2k3m4n5p6q7r8s9t0v2" },
  "tenant_id": "ten_01k2r7wq9d4hx8m3vznc6tp5ye",
  "type": "budget.threshold"
}

Verify the signature

Every webhook request carries X-FleetWarrant-Alert-Id and a signature header:

header
X-FleetWarrant-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>

The signature is HMAC-SHA256, keyed with the channel’s signing secret, over <t>.<raw request body>. Check it against the raw bytes you received, before parsing the JSON. Reject the request if t or v1 is missing, if t is more than 300 seconds from your clock, or if no v1 matches. In Python, with the standard library only, where body is the raw request body as bytes:

Python · verify
import hashlib
import hmac
import time


def verify_fleetwarrant_signature(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    timestamp = None
    signatures = []
    for part in header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t" and value.isascii() and value.isdigit() and len(value) <= 12:
            timestamp = int(value)
        elif key == "v1":
            signatures.append(value)
    if timestamp is None or not signatures:
        return False
    if abs(time.time() - timestamp) > tolerance:
        return False
    signed = str(timestamp).encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected.encode(), s.encode()) for s in signatures)

A Flask endpoint that uses it:

Python · Flask
import json
import os

from flask import Flask, abort, request

# verify_fleetwarrant_signature is the function above.

app = Flask(__name__)
SIGNING_SECRET = os.environ["FW_SIGNING_SECRET"]


@app.post("/fleetwarrant")
def fleetwarrant_alert():
    body = request.get_data()
    header = request.headers.get("X-FleetWarrant-Signature", "")
    if not verify_fleetwarrant_signature(SIGNING_SECRET, body, header):
        abort(400)
    alert = json.loads(body)
    ...
    return "", 204

Retries

Any 2xx counts as delivered. A timeout, a connection failure, a 5xx or a 429 is retried, up to 5 attempts in all. Redirects are not followed. Each retry is signed again with its own time, so reply quickly and do slow work afterwards.

Back to contents

12

Budgets and spend

Every Gateway call is priced in US$, the currency the providers charge in, with no conversion. The Dashboard’s Spend page shows month to date, a projection, a daily chart, spend by Agent, model and Connector, and the most expensive calls. The Agents list has a Spend (MTD, US$) column.

A call FleetWarrant has no US$ price for is counted as unpriced, never as US$0. A total that includes unpriced calls reads “at least US$…”, with the number of unpriced calls beside it, so treat it as a lower bound. Budget alerts say the same: spend_is_lower_bound is true and unpriced_calls says how many.

Budgets

Budgets are alert-only. A budget never blocks, slows or refuses a call. When spend crosses a threshold you get a budget.threshold alert, and a person decides what to do, such as suspending the Agent (below). Set a monthly budget per Agent, per Tenant, or both. The default thresholds are 50%, 80%, 100%, 120% of the budget. Each threshold alerts once a month, and while spend stays over budget a reminder follows each day. Months and days follow your Tenant’s time zone, Australia/Sydney unless it’s been set otherwise.

Setting budgets is admin-only, through the API. An Agent can also have a requests-per-minute (rpm_alert_threshold) or tokens-per-minute (tpm_alert_threshold) level, which sends usage.threshold alerts. null clears a setting, and a field you leave out is unchanged:

PUT /v1/dashboard/agents/{agent_id}/limits
curl -sS -X PUT "$FW_API/v1/dashboard/agents/<agent-id>/limits" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "monthly_budget_usd": "500.00",
  "budget_alert_thresholds_pct": [
    50,
    80,
    100,
    120
  ],
  "rpm_alert_threshold": 120
}'
PUT /v1/dashboard/tenant/limits
curl -sS -X PUT "$FW_API/v1/dashboard/tenant/limits" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "monthly_budget_usd": "2000.00"
}'

Spend from the API

from and to are days (YYYY-MM-DD, inclusive); leave both out for the current month. group_by is agent, connector, model or day. Builders see only their own Agents’ spend:

GET /v1/dashboard/spend
curl -sS "$FW_API/v1/dashboard/spend?from=2026-09-01&to=2026-09-26&group_by=agent" \
  -H "Authorization: Bearer $FW_ID_TOKEN"

Back to contents

13

Kill switch and circuit breakers

Suspend one Agent

In the Dashboard, open Agents and use Suspend on the Agent’s row. Its next call is refused with a 403 (code agent_suspended) that names the Agent and your reason. The Agent’s API key stays valid, so resuming needs no change on the client: its next call after Resume goes through. Suspending is reversible; revoking a key is not.

POST /v1/dashboard/agents/{agent_id}/suspend
curl -sS -X POST "$FW_API/v1/dashboard/agents/<agent-id>/suspend" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Looping on the invoices API"
}'
POST /v1/dashboard/agents/{agent_id}/resume
curl -sS -X POST "$FW_API/v1/dashboard/agents/<agent-id>/resume" \
  -H "Authorization: Bearer $FW_ID_TOKEN"

The reason is optional. Admins can suspend and resume any Agent. Builders can suspend Agents they created, and resume only a suspension they made themselves. Only an admin can lift a suspension made by the emergency stop.

Emergency stop

On the Dashboard’s Tenant page, Emergency stop suspends every Agent in the Tenant at once, after you type STOP (or the Tenant’s name) to confirm. Keys stay valid. While it’s in force, every Dashboard page shows a banner. Resume all brings back exactly the Agents the stop suspended; any that were already suspended stay suspended. Both are admin-only:

POST /v1/dashboard/tenant/emergency-stop
curl -sS -X POST "$FW_API/v1/dashboard/tenant/emergency-stop" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm": "STOP",
  "reason": "Suspected leaked Agent key"
}'
POST /v1/dashboard/tenant/resume-all
curl -sS -X POST "$FW_API/v1/dashboard/tenant/resume-all" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Key rotated; all clear"
}'

On a large Tenant, a stop or resume can run out of time part-way. The response then says complete: false. Send the same request again to finish it; both are safe to repeat.

Circuit breakers

Every Agent has four, checked every minute, away from the Gateway’s request path. By default each one sends a circuit_breaker.tripped alert and does nothing else, and none can trip during an Agent’s first 14 days. The defaults:

spend_spike
The last hour’s spend is more than 10× the Agent’s average hourly spend over the last 7 days, and at least US$10.00.
call_surge
Calls in 5 minutes are more than 10× the Agent’s baseline, and at least 200.
blocked_storm
More than 25 refused calls in 5 minutes.
error_storm
More than 50% of calls fail upstream over 5 minutes, once there are at least 20 calls.

An admin can change the numbers, switch a breaker off, or opt it in to suspend. Opting in has to be confirmed explicitly with "confirm_auto_suspend": true:

PUT /v1/dashboard/agents/{agent_id}/breakers
curl -sS -X PUT "$FW_API/v1/dashboard/agents/<agent-id>/breakers" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "spend_spike": {
    "mode": "suspend"
  },
  "confirm_auto_suspend": true
}'
Automatic suspension is on the roadmap. Today a breaker set to suspend still only alerts (the alert’s mode says suspend), and a person suspends the Agent from the alert’s Dashboard link.

Back to contents

14

Evidence exports

An evidence export is a signed zip of your Events for a date range, which an auditor can check without trusting FleetWarrant or the Dashboard. Admins and viewers can request and download exports; builders can’t. Every request and every download is recorded in your audit trail.

1. Request one

range.from and range.to are UTC timestamps, at most 92 days apart. A longer period takes several exports. You can narrow one with filters.agent_id, filters.connector_id or filters.action.

"include_raw_bodies": true adds the raw request and response bodies, and is admin-only, to request and to download. Raw bodies exist only for a Tenant that has turned on raw capture. They come in a separate raw_bodies.jsonl, marked as unredacted data. A body that was shredded or never captured is listed as unavailable, with the reason.

POST /v1/dashboard/exports
curl -sS -X POST "$FW_API/v1/dashboard/exports" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "range": {
    "from": "2026-06-01T00:00:00Z",
    "to": "2026-09-01T00:00:00Z"
  }
}'

2. Wait for it

The response carries the export_id. Its status moves from pending through running to complete, or to failed with an error:

GET /v1/dashboard/exports/{export_id}
curl -sS "$FW_API/v1/dashboard/exports/<export-id>" \
  -H "Authorization: Bearer $FW_ID_TOKEN"

3. Download it

Once it’s complete, this returns a url to the zip, valid for up to 24 hours:

POST /v1/dashboard/exports/{export_id}/download
curl -sS -X POST "$FW_API/v1/dashboard/exports/<export-id>/download" \
  -H "Authorization: Bearer $FW_ID_TOKEN"

The bundle contains:

events.jsonl
One Event per line.
summary.csv
Counts per Agent and model.
manifest.json
The export’s request, the SHA-256 and size of every other file, and the signing key’s id and fingerprint.
manifest.sig
An ECDSA P-256 / SHA-256 signature over manifest.json, made with FleetWarrant’s export signing key in AWS KMS.
public_key.pem
The public half of that key.
verify.py
A standalone script that checks all of the above.
README.txt
How to verify.
raw_bodies.jsonl
Only if an admin asked for raw bodies: the unredacted request and response of each Event that has one, listed in the manifest like the other files.

4. Verify it

With Python 3.9 or later and only the cryptography package, take verify.py out of the bundle and run it against the zip:

shell · verify
unzip bundle.zip verify.py
pip install cryptography
python verify.py bundle.zip --expect-fingerprint <fingerprint>

It checks the signature over manifest.json, that the manifest names the key that signed it, the SHA-256 and size of every listed file, and that the zip holds nothing else. It prints PASS or FAIL: <reason>, and exits 0 on success and 1 on failure. Without Python:

shell · openssl
openssl dgst -sha256 -verify public_key.pem -signature manifest.sig manifest.json
openssl pkey -pubin -in public_key.pem -outform DER | sha256sum
sha256sum events.jsonl summary.csv verify.py README.txt
Take the fingerprint you pass to --expect-fingerprint from FleetWarrant, never from the bundle. Anyone who altered a bundle could re-sign it with their own key and ship that key inside it. The fingerprint isn’t published yet, so ask us for it, over a channel other than the bundle. It is the SHA-256 of the signing key’s DER public key, in lowercase hex. Keys that have signed exports stay valid for checking, so old bundles keep verifying.

Back to contents

15

Continuous export

Continuous export sends each Event to your own tools as it’s written: an S3 bucket, Splunk HEC, Datadog Logs or a signed webhook. It runs off the Gateway’s request path, so a failing destination only delays its own export. Destinations are admin-only, set through the API, and export Events written from the moment they’re created.

Every destination gets the same line format: one JSON object per Event, with schema_version, event_id, tenant_id and the event itself, already redacted. Delivery is at least once, so use event_id as the unique key.

Your S3 bucket

No secret is shared. You create an IAM role in your own AWS account, and FleetWarrant assumes it with an external id:

POST /v1/dashboard/export-destinations · s3
curl -sS -X POST "$FW_API/v1/dashboard/export-destinations" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "s3",
  "display_name": "audit-archive",
  "bucket": "<bucket-name>",
  "prefix": "fleetwarrant",
  "region": "ap-southeast-2",
  "role_arn": "arn:aws:iam::<account-id>:role/<role-name>"
}'

The response includes the destination’s external_id, and the exact trust_policy and permission_policy to put on your role. Paste those as returned. The trust policy lets only FleetWarrant’s S3 delivery role assume yours, and only with that external id:

trust_policy (shape)
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowFleetWarrantS3ExportAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<fleetwarrant-account-id>:role/fleetwarrant-export-s3-delivery"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ],
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<external-id>"
        }
      }
    }
  ]
}

The permission policy allows s3:PutObject under your prefix and nothing else: no read, list or delete. If the bucket uses your own KMS key, add kms_key_arn to the request, and the policy also allows kms:GenerateDataKey on that key:

permission_policy (shape)
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "FleetWarrantExportPutObjects",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket-name>/fleetwarrant/*"
      ]
    }
  ]
}

Splunk HEC

The URL of your HEC endpoint (port 443 or 8088) and a HEC token. Events arrive with sourcetype fleetwarrant:event:

POST /v1/dashboard/export-destinations · splunk_hec
curl -sS -X POST "$FW_API/v1/dashboard/export-destinations" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "splunk_hec",
  "display_name": "splunk",
  "url": "https://splunk.example.com:8088",
  "token": "<hec-token>"
}'

Datadog Logs

Your Datadog site’s logs intake URL and an API key. With no path, /api/v2/logs is added. Logs arrive with service and ddsource set to fleetwarrant:

POST /v1/dashboard/export-destinations · datadog
curl -sS -X POST "$FW_API/v1/dashboard/export-destinations" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "datadog",
  "display_name": "datadog",
  "url": "https://http-intake.logs.datadoghq.com",
  "token": "<datadog-api-key>"
}'

Signed webhook

Each request is a JSON array of lines, signed with X-FleetWarrant-Signature exactly as alert webhooks are, so the same verify function works. The response includes the signing_secret, once. If it’s lost, delete the destination and create a new one:

POST /v1/dashboard/export-destinations · webhook
curl -sS -X POST "$FW_API/v1/dashboard/export-destinations" \
  -H "Authorization: Bearer $FW_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "webhook",
  "display_name": "siem-webhook",
  "url": "https://siem.example.com/fleetwarrant"
}'

Failures

Tokens and URLs are stored encrypted and only ever shown masked. A timeout, a 5xx or a 429 is retried. Any other failure, such as a revoked token’s 401, is not. Each destination shows its last_success_at, last_failure_at and last_error. A destination that has failed for 15 minutes sends an export.failing alert to every channel that switched it on.

Back to contents

16

Support

Something not working, a question about a request, or no Tenant yet: email matt@fleetwarrant.com. Onboarding is hands-on at this stage, so that reaches the team that set your Tenant up, not a ticket queue.

Back to contents