REST API

Use AgentShield Without an SDK

AgentShield has a REST API that works with any tool that can send an HTTP POST request — Python, JavaScript, cURL, n8n, Make, Zapier, or any other language or no-code platform. The Python SDK is optional.

Endpoint

POST https://api.agentshield.one/v1/track

Authentication

All requests require a Bearer token. Get your API key from Settings → API Keys.

Authorization: Bearer ags_live_xxxxx

Request Body

Required fields

Field	Type	Description
agent	string	Unique name for your agent or workflow. Used for grouping in the dashboard.

Optional fields

Field	Type	Description
model	string	Model name (e.g. gpt-4o, claude-opus-4-5). Used for cost calculation.
provider	string	Provider name (openai, anthropic, google, cohere). Auto-detected from model if omitted.
input_tokens	integer	Number of prompt/input tokens. Used to calculate cost.
output_tokens	integer	Number of completion/output tokens. Used to calculate cost.
cost_usd	float	Override the calculated cost. Use if you already know the exact cost.
session_id	string	Group multiple calls into one session for Replay. Generate a UUID per user conversation.
latency_ms	integer	Response latency in milliseconds. Used for latency tracking and anomaly detection.
metadata	object	Any key-value pairs you want to attach. Visible in session detail.

Response

{
  "tracked": true,
  "cost_usd": 0.0185,
  "session_id": "ses_01jbk...",
  "event_id": "evt_01jbk..."
}

Examples

cURL

curl -X POST https://api.agentshield.one/v1/track \
  -H "Authorization: Bearer ags_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-agent",
    "model": "gpt-4o",
    "input_tokens": 1250,
    "output_tokens": 340,
    "session_id": "ses_user_abc123"
  }'

JavaScript / Node.js

await fetch("https://api.agentshield.one/v1/track", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ags_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agent: "my-agent",
    model: "gpt-4o",
    input_tokens: completion.usage.prompt_tokens,
    output_tokens: completion.usage.completion_tokens,
    session_id: sessionId
  })
})

n8n HTTP Request Node

Method: POST
URL: https://api.agentshield.one/v1/track

Headers:
  Authorization: Bearer ags_live_xxxxx
  Content-Type: application/json

Body (JSON):
{
  "agent": "my-n8n-workflow",
  "model": "gpt-4o",
  "input_tokens": {{ $json.usage.prompt_tokens }},
  "output_tokens": {{ $json.usage.completion_tokens }}
}

Make (Integromat) HTTP Module

Module: HTTP > Make a request
URL: https://api.agentshield.one/v1/track
Method: POST
Body type: Raw / JSON

{
  "agent": "my-make-scenario",
  "model": "gpt-4o",
  "input_tokens": {{ai_module.usage.prompt_tokens}},
  "output_tokens": {{ai_module.usage.completion_tokens}}
}

Zapier Webhooks

Action: Webhooks by Zapier > POST
URL: https://api.agentshield.one/v1/track

Headers:
  Authorization: Bearer ags_live_xxxxx

Data:
  agent: my-zapier-zap
  model: gpt-4o
  input_tokens: (from previous AI step)
  output_tokens: (from previous AI step)

Error Codes

Status	Error	Fix
401	Unauthorized	Check your API key. Must be a valid ags_live_ key.
422	Validation error	agent field is required. Check the request body.
429	Rate limited	You are sending too many requests. Back off and retry.
402	Budget cap exceeded	This agent has hit its budget cap. Increase or reset it in the dashboard.
500	Server error	Retry with exponential backoff. Contact support if it persists.

Need the Python SDK instead?

The SDK wraps this API with automatic session management and framework integrations. View SDK docs →