Version: 4.17.0 | Protocol: A2A Payment Protocol | Engine: Pulse Engines
https://your-instance.pulse.app/pulse-api/
All endpoints are prefixed with /pulse-api/. Requests must use HTTPS.
Every request (except /pulse-api/health) requires a SHA-256 API key in the
Authorization header.
Authorization: Bearer YOUR_API_KEY
| Property | Description |
|---|---|
| Format | YOUR_API_KEY prefix followed by 40 hex characters |
| Hashing | Keys are stored as SHA-256 hashes; raw key shown only once |
| IP Whitelist | Optional list of allowed source IPs per key |
| Permissions | Scoped permission array per key |
| Agent Restrictions | Optional allowed_agents array to limit agent access |
When an API key has an IP whitelist configured, requests from non-whitelisted IPs
receive a 403 Forbidden response. The x-forwarded-for header is used for IP
resolution behind load balancers.
| Limit Type | Value | Window | Scope |
|---|---|---|---|
| Per-minute | 120 RPM | Sliding | Per key |
| Daily | 10,000 | Calendar | Per key |
Rate limit headers are included in every response:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1713096960
X-RateLimit-Daily-Remaining: 9842
Exceeding the rate limit returns 429 Too Many Requests with a Retry-After header.
| Status | Code | Description |
|---|---|---|
| 400 | bad_request |
Missing or invalid request parameters |
| 401 | unauthorized |
Missing or invalid API key |
| 403 | forbidden |
Valid key but insufficient permissions |
| 404 | not_found |
Resource does not exist |
| 409 | conflict |
Resource already exists (duplicate) |
| 429 | rate_limited |
Rate limit exceeded |
| 500 | internal_error |
Server-side error |
Error response body:
{
"error": "Human-readable error message",
"code": "machine_readable_code",
"detail": "Additional context when available"
}Create a new payment transaction request. Triggers the full authorization pipeline.
Permission: payments:request
Request Headers:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
requesting_agent_id |
string | Yes | Agent initiating the payment |
counterparty_agent_id |
string | No | Receiving agent ID |
counterparty_org_id |
string | No | Receiving organization ID (cross-org) |
amount |
number | Yes | Payment amount (positive decimal) |
currency |
string | No | ISO 4217 currency code (default: USD) |
tx_type |
string | Yes | Transaction type identifier |
category |
string | No | Transaction category |
description |
string | No | Human-readable description |
reference_id |
string | No | External reference (invoice, PO, etc.) |
metadata |
object | No | Arbitrary key-value metadata |
escrow_conditions |
object | No | Escrow release conditions (if escrow) |
Response (200 - Authorized):
{
"transaction_id": "txn_9f8e7d6c5b4a",
"status": "authorized",
"authorization": {
"decision": "approved",
"reason_code": "policy_pass",
"compliance_status": "clear",
"processing_time_ms": 342
},
"settlement": {
"settled_at": "2026-04-14T12:35:00.000Z"
}
}Response (200 - Denied):
{
"transaction_id": "txn_9f8e7d6c5b4a",
"status": "denied",
"authorization": {
"decision": "denied",
"reason_code": "daily_limit_exceeded",
"reason_detail": "Daily spending limit of $50,000 exceeded",
"processing_time_ms": 89
}
}Error Responses:
400- Missing required fields403- Missingpayments:requestpermission
curl Example:
curl -X POST https://your-instance.pulse.app/pulse-api/payments/request \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"requesting_agent_id": "agent-treasury-ops",
"counterparty_agent_id": "agent-vendor-pay",
"amount": 2500.00,
"currency": "USD",
"tx_type": "vendor_payment",
"category": "operations",
"description": "Invoice INV-2026-0412",
"reference_id": "INV-2026-0412"
}'List payment transactions with filtering and pagination.
Permission: payments:read
Query Parameters:
| Param | Type | Default | Description |
|---|---|---|---|
limit |
int | 50 | Results per page (max 200) |
offset |
int | 0 | Pagination offset |
status |
string | - | Filter by status |
tx_type |
string | - | Filter by transaction type |
agent_id |
string | - | Filter by agent (sender or receiver) |
date_from |
string | - | ISO 8601 start date filter |
date_to |
string | - | ISO 8601 end date filter |
Response (200):
{
"transactions": [
{
"id": "txn_9f8e7d6c5b4a",
"requesting_agent_id": "agent-treasury-ops",
"requesting_org_id": "org_abc123",
"counterparty_agent_id": "agent-vendor-pay",
"counterparty_org_id": null,
"amount": 2500.00,
"currency": "USD",
"tx_type": "vendor_payment",
"category": "operations",
"description": "Invoice INV-2026-0412",
"reference_id": "INV-2026-0412",
"status": "settled",
"settled_at": "2026-04-14T12:35:00.000Z",
"created_at": "2026-04-14T12:34:57.000Z"
}
],
"count": 1,
"limit": 50,
"offset": 0
}curl Example:
curl "https://your-instance.pulse.app/pulse-api/payments?status=settled&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"Retrieve full detail for a single transaction including authorization, events, and escrow.
Permission: payments:read
Response (200):
{
"transaction": {
"id": "txn_9f8e7d6c5b4a",
"requesting_agent_id": "agent-treasury-ops",
"requesting_org_id": "org_abc123",
"counterparty_agent_id": "agent-vendor-pay",
"amount": 2500.00,
"currency": "USD",
"tx_type": "vendor_payment",
"status": "settled",
"metadata": {"invoice_id": "INV-2026-0412"},
"created_at": "2026-04-14T12:34:57.000Z"
},
"authorization": {
"id": "auth_x1y2z3",
"decision": "approved",
"reason_code": "policy_pass",
"processing_time_ms": 342,
"created_at": "2026-04-14T12:34:57.500Z"
},
"events": [
{"id": "evt_1", "event_type": "authorized", "created_at": "2026-04-14T12:34:57.500Z"},
{"id": "evt_2", "event_type": "settled", "created_at": "2026-04-14T12:35:00.000Z"}
],
"escrow": null
}Error Responses:
404- Transaction not found
curl Example:
curl "https://your-instance.pulse.app/pulse-api/payments/txn_9f8e7d6c5b4a" \
-H "Authorization: Bearer YOUR_API_KEY"Retrieve the event history for a transaction in chronological order.
Permission: payments:read
Response (200):
{
"events": [
{
"id": "evt_a1b2c3",
"event_type": "authorized",
"event_data": {"decision": "approved", "reason_code": "policy_pass"},
"created_at": "2026-04-14T12:34:57.500Z"
},
{
"id": "evt_d4e5f6",
"event_type": "settled",
"event_data": {"settled_at": "2026-04-14T12:35:00.000Z"},
"created_at": "2026-04-14T12:35:00.000Z"
}
]
}curl Example:
curl "https://your-instance.pulse.app/pulse-api/payments/txn_9f8e7d6c5b4a/events" \
-H "Authorization: Bearer YOUR_API_KEY"Raise a dispute on an escrowed transaction.
Permission: payments:write
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
reason |
string | No | Dispute reason text |
Response (200):
{
"disputed": true,
"escrow_id": "esc_a1b2c3",
"status": "disputed",
"disputed_at": "2026-04-14T13:00:00.000Z"
}Error Responses:
400- Transaction has no escrow404- Transaction not found
curl Example:
curl -X POST "https://your-instance.pulse.app/pulse-api/payments/txn_9f8e7d6c5b4a/dispute" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason": "Deliverables not met per SOW section 3.2"}'List all active wallets for the authenticated organization.
Permission: wallets:read
Response (200):
{
"wallets": [
{
"id": "wal_a1b2c3",
"agent_id": "agent-treasury-ops",
"currency": "USD",
"available_balance": 50000.00,
"held_balance": 5000.00,
"lifetime_sent": 1250000.00,
"lifetime_received": 1350000.00,
"last_transaction_at": "2026-04-14T12:35:00.000Z",
"is_active": true,
"created_at": "2026-01-15T00:00:00.000Z"
}
]
}curl Example:
curl "https://your-instance.pulse.app/pulse-api/wallets" \
-H "Authorization: Bearer YOUR_API_KEY"Retrieve detailed wallet information for a specific agent.
Permission: wallets:read
Response (200):
{
"id": "wal_a1b2c3",
"org_id": "org_abc123",
"agent_id": "agent-treasury-ops",
"currency": "USD",
"available_balance": 50000.00,
"held_balance": 5000.00,
"lifetime_sent": 1250000.00,
"lifetime_received": 1350000.00,
"last_transaction_at": "2026-04-14T12:35:00.000Z",
"is_active": true,
"created_at": "2026-01-15T00:00:00.000Z",
"updated_at": "2026-04-14T12:35:00.000Z"
}Error Responses:
404- Wallet not found
curl Example:
curl "https://your-instance.pulse.app/pulse-api/wallets/agent-treasury-ops" \
-H "Authorization: Bearer YOUR_API_KEY"Add funds to an agent's wallet.
Permission: wallets:write
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
amount |
number | Yes | Amount to add (must be positive) |
currency |
string | No | Currency code (default: USD) |
Response (200):
{
"funded": true,
"agent_id": "agent-treasury-ops",
"amount": 10000.00,
"new_balance": 60000.00
}Error Responses:
400- Invalid or non-positive amount404- Wallet not found
curl Example:
curl -X POST "https://your-instance.pulse.app/pulse-api/wallets/agent-treasury-ops/fund" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount": 10000, "currency": "USD"}'Withdraw funds from an agent's wallet.
Permission: wallets:write
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
amount |
number | Yes | Amount to withdraw (must be positive) |
currency |
string | No | Currency code (default: USD) |
Response (200):
{
"withdrawn": true,
"agent_id": "agent-treasury-ops",
"amount": 5000.00,
"new_balance": 45000.00
}Error Responses:
400- Invalid amount or insufficient balance404- Wallet not found
curl Example:
curl -X POST "https://your-instance.pulse.app/pulse-api/wallets/agent-treasury-ops/withdraw" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount": 5000, "currency": "USD"}'List all spending policies for the authenticated organization.
Permission: policies:read
Response (200):
{
"policies": [
{
"id": "pol_abc123",
"org_id": "org_abc123",
"policy_name": "Default Policy",
"agent_id": null,
"max_per_transaction": 10000.00,
"max_daily": 50000.00,
"max_monthly": 500000.00,
"currency": "USD",
"require_human_above": 25000.00,
"approved_counterparties": [],
"blocked_counterparties": [],
"allowed_categories": [],
"compliance_precheck": true,
"compliance_jurisdictions": ["US_FEDERAL"],
"is_active": true,
"created_at": "2026-01-15T00:00:00.000Z"
}
]
}curl Example:
curl "https://your-instance.pulse.app/pulse-api/policies" \
-H "Authorization: Bearer YOUR_API_KEY"Create a new spending policy.
Permission: policies:write
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
policy_name |
string | Yes | Human-readable policy name |
agent_id |
string | No | Agent ID (null for org-wide default) |
max_per_transaction |
number | No | Max amount per single transaction |
max_daily |
number | No | Max daily aggregate spend |
max_monthly |
number | No | Max monthly aggregate spend |
currency |
string | No | Currency code (default: USD) |
require_human_above |
number | No | Human approval threshold |
approved_counterparties |
string[] | No | Allowed counterparty agent IDs |
blocked_counterparties |
string[] | No | Blocked counterparty agent IDs |
allowed_categories |
string[] | No | Permitted transaction categories |
compliance_precheck |
boolean | No | Enable compliance check (default: true) |
compliance_jurisdictions |
string[] | No | Jurisdictions for compliance evaluation |
Response (201):
{
"id": "pol_new123",
"org_id": "org_abc123",
"policy_name": "Treasury Agent Policy",
"agent_id": "agent-treasury-ops",
"max_per_transaction": 50000.00,
"max_daily": 200000.00,
"max_monthly": 2000000.00,
"currency": "USD",
"require_human_above": 100000.00,
"approved_counterparties": ["agent-vendor-pay"],
"blocked_counterparties": [],
"allowed_categories": ["treasury", "operations"],
"compliance_precheck": true,
"compliance_jurisdictions": ["US_FEDERAL", "US_STATE_NY"],
"is_active": true,
"created_at": "2026-04-14T13:00:00.000Z"
}Error Responses:
400- Missing policy_name409- Active policy already exists for this agent
curl Example:
curl -X POST "https://your-instance.pulse.app/pulse-api/policies" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"policy_name": "Treasury Agent Policy",
"agent_id": "agent-treasury-ops",
"max_per_transaction": 50000,
"max_daily": 200000,
"max_monthly": 2000000,
"require_human_above": 100000,
"allowed_categories": ["treasury", "operations"],
"compliance_jurisdictions": ["US_FEDERAL", "US_STATE_NY"]
}'Update an existing spending policy. Supports partial updates.
Permission: policies:write
Request Body: Any subset of the fields from POST /pulse-api/policies (except policy_name is optional here).
Response (200):
{
"updated": true
}Error Responses:
404- Policy not found
curl Example:
curl -X PATCH "https://your-instance.pulse.app/pulse-api/policies/pol_abc123" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"max_per_transaction": 75000, "max_daily": 300000}'Soft-delete a spending policy (sets is_active to false).
Permission: policies:write
Response (200):
{
"deleted": true,
"soft": true
}Error Responses:
404- Policy not found
curl Example:
curl -X DELETE "https://your-instance.pulse.app/pulse-api/policies/pol_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"List reconciliation reports with filtering and pagination.
Permission: reconciliation:read
Query Parameters:
| Param | Type | Default | Description |
|---|---|---|---|
limit |
int | 20 | Results per page (max 100) |
offset |
int | 0 | Pagination offset |
date_from |
string | - | Filter by period start date |
date_to |
string | - | Filter by period end date |
Response (200):
{
"reports": [
{
"id": "rec_a1b2c3",
"report_period_start": "2026-04-01T00:00:00.000Z",
"report_period_end": "2026-04-07T23:59:59.999Z",
"total_transactions": 450,
"matched_count": 447,
"unmatched_count": 2,
"discrepancy_count": 1,
"total_volume": 125000.00,
"status": "completed",
"created_at": "2026-04-08T01:00:00.000Z"
}
],
"count": 1,
"limit": 20,
"offset": 0
}curl Example:
curl "https://your-instance.pulse.app/pulse-api/reconciliation?date_from=2026-04-01" \
-H "Authorization: Bearer YOUR_API_KEY"Trigger an on-demand reconciliation audit for a specified period.
Permission: reconciliation:trigger
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
period_start |
string | No | ISO 8601 start of period |
period_end |
string | No | ISO 8601 end of period |
Response (200):
{
"triggered": true,
"report_id": "rec_new456",
"status": "processing",
"period_start": "2026-04-08T00:00:00.000Z",
"period_end": "2026-04-14T23:59:59.999Z"
}curl Example:
curl -X POST "https://your-instance.pulse.app/pulse-api/reconciliation/trigger" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"period_start": "2026-04-08T00:00:00Z", "period_end": "2026-04-14T23:59:59Z"}'Health check endpoint. No authentication required.
Response (200):
{
"status": "operational",
"version": "4.17.0",
"timestamp": "2026-04-14T12:00:00.000Z"
}curl "https://your-instance.pulse.app/pulse-api/health"Returns organization metadata, permissions, and API key info for the authenticated key.
Permission: Any valid API key.
curl "https://your-instance.pulse.app/pulse-api/meta" \
-H "Authorization: Bearer YOUR_API_KEY"Push up to 100 records of structured data to the platform.
Permission: data:write
Request Body: { "source": string, "data_type": string, "records": array }
curl -X POST "https://your-instance.pulse.app/pulse-api/data/push" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"source": "erp", "data_type": "invoices", "records": [{"external_id": "INV-001", "data": {"amount": 5000}}]}'Push up to 1,000 records in batches of 100.
Permission: data:write
Request Body: Same schema as /pulse-api/data/push but allows up to 1,000 records.
curl -X POST "https://your-instance.pulse.app/pulse-api/data/bulk" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"source": "erp", "data_type": "invoices", "records": [...]}'Query stored data with filtering and pagination.
Permission: data:read
Query Parameters / Body: limit, offset, data_type, category, connector_slug, date_from, date_to
curl "https://your-instance.pulse.app/pulse-api/data/query?data_type=invoices&limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"Returns a summary of stored data grouped by type and category.
Permission: data:read
curl "https://your-instance.pulse.app/pulse-api/data/summary" \
-H "Authorization: Bearer YOUR_API_KEY"Trigger a Pulse Engines agent run with optional input parameters.
Permission: agents:trigger
Request Body: { "agent": string, "input": object, "priority": string, "callback_webhook": string }
curl -X POST "https://your-instance.pulse.app/pulse-api/agents/trigger" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent": "market-analyzer", "input": {"region": "northeast"}, "priority": "high"}'Check the status of a specific agent run.
Permission: agents:trigger
curl "https://your-instance.pulse.app/pulse-api/agents/status/run_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"List recent agent run results with optional filtering.
Permission: agents:trigger
Query Parameters: agent (filter by agent ID), limit (max 100, default 20)
curl "https://your-instance.pulse.app/pulse-api/agents/results?agent=market-analyzer&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"Aggregate efficiency metrics across all agent runs.
Permission: reports:read
curl "https://your-instance.pulse.app/pulse-api/reports/efficiency" \
-H "Authorization: Bearer YOUR_API_KEY"Recent compliance predictions and risk assessments.
Permission: reports:read
curl "https://your-instance.pulse.app/pulse-api/reports/compliance" \
-H "Authorization: Bearer YOUR_API_KEY"Financial data records for the authenticated organization.
Permission: reports:read
curl "https://your-instance.pulse.app/pulse-api/reports/financial" \
-H "Authorization: Bearer YOUR_API_KEY"List all webhook endpoints for the organization.
Permission: webhooks:manage
curl "https://your-instance.pulse.app/pulse-api/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY"Register a new webhook endpoint with event subscriptions and signing secret.
Permission: webhooks:manage
Request Body: { "url": string, "description": string, "events": string[], "agent_filter": string[] }
curl -X POST "https://your-instance.pulse.app/pulse-api/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://your-app.com/pulse-api/hooks", "events": ["payment.authorized", "payment.settled"]}'Manage individual webhook endpoints.
Permission: webhooks:manage
PATCH - Update endpoint configuration:
curl -X PATCH "https://your-instance.pulse.app/pulse-api/webhooks/whk_abc123" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "active", "events": ["payment.authorized"]}'DELETE - Remove endpoint and all delivery history:
curl -X DELETE "https://your-instance.pulse.app/pulse-api/webhooks/whk_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"GET /pulse-api/webhooks/:id/deliveries - View delivery history:
curl "https://your-instance.pulse.app/pulse-api/webhooks/whk_abc123/deliveries?limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"POST /pulse-api/webhooks/:id/test - Send test delivery:
curl -X POST "https://your-instance.pulse.app/pulse-api/webhooks/whk_abc123/test" \
-H "Authorization: Bearer YOUR_API_KEY"| Permission | Routes |
|---|---|
payments:request |
POST /pulse-api/payments/request |
payments:read |
GET /pulse-api/payments, GET /pulse-api/payments/:id, GET /pulse-api/payments/:id/events |
payments:write |
POST /pulse-api/payments/:id/dispute |
wallets:read |
GET /pulse-api/wallets, GET /pulse-api/wallets/:agent_id |
wallets:write |
POST /pulse-api/wallets/:agent_id/fund, POST /pulse-api/wallets/:agent_id/withdraw |
policies:read |
GET /pulse-api/policies |
policies:write |
POST /pulse-api/policies, PATCH /pulse-api/policies/:id, DELETE /pulse-api/policies/:id |
reconciliation:read |
GET /pulse-api/reconciliation |
reconciliation:trigger |
POST /pulse-api/reconciliation/trigger |
data:read |
GET /pulse-api/data/query, GET /pulse-api/data/summary |
data:write |
POST /pulse-api/data/push, POST /pulse-api/data/bulk |
agents:trigger |
POST /pulse-api/agents/trigger, GET /pulse-api/agents/status/:id, GET /pulse-api/agents/results |
reports:read |
GET /pulse-api/reports/efficiency, GET /pulse-api/reports/compliance, GET /pulse-api/reports/financial |
webhooks:manage |
All /pulse-api/webhooks endpoints |