RevvedAgents API

Trigger agents, read run status, and manage approvals from your own code, Zapier, CI pipeline, or any HTTP client.

Bearer auth

Keys start with ak_. Generate in Settings → API keys.

60 req/min per key

Responses include X-RateLimit-Remaining. Burst over the limit and you get 429 with a Retry-After header.

Scoped keys

read, run, admin. Give each integration the minimum it needs.

Authentication

Send your API key as a bearer token. The organization is resolved from the key — you don't need to pass an org ID.

curl https://revvedagents.example/api/v1/agents \
  -H "Authorization: Bearer ak_YOUR_KEY_HERE"

Endpoints

GET/api/v1/agentsscope: read

List active agents available to your org.

POST/api/v1/agents/{slug}/runsscope: run

Trigger an agent run. Optional body: recordObjectType, recordId, config.

GET/api/v1/runs/{id}scope: read

Get a run's status, progress, and results.

GET/api/v1/approvalsscope: read

List approvals. Query: ?status=pending|approved|rejected, ?limit=50.

POST/api/v1/approvals/{id}/approvescope: admin

Approve a pending approval and execute the underlying action.

POST/api/v1/approvals/{id}/rejectscope: admin

Reject a pending approval. Body: { reason?: string }.

Example: trigger a run

curl -X POST https://revvedagents.example/api/v1/agents/deal-risk-autopilot/runs \
  -H "Authorization: Bearer ak_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "recordObjectType": "deal", "recordId": "12345" }'

# → 202 Accepted
# { "success": true, "data": { "runId": "...", "status": "queued" } }

Errors

401 — missing or invalid bearer token.
403 — key lacks the required scope for that endpoint.
404 — resource not visible to this org.
429 — rate limit exceeded; inspect Retry-After.
5xx — transient; safe to retry with backoff.

Webhooks

Subscribe to events at Settings → Webhooks. Each delivery is a POST with a JSON body and two headers: X-RevvedAgents-Event (event name) and X-RevvedAgents-Signature (HMAC-SHA256 of the raw body, keyed by your endpoint secret). Non-2xx responses retry with exponential backoff — 30s, 2m, 15m, 1h, 6h. After 5 consecutive failures the endpoint is marked failed and paused.

Events

agent.run.completed

An agent run finished successfully. Payload includes runId, agentSlug, summary, score, findingsCount, completedAt.

agent.run.failed

An agent run failed. Payload includes runId, agentSlug, error.

finding.critical

A completed run produced a critical-severity finding. Emits once per critical finding.

approval.created

An agent queued an action for human approval. Payload includes approvalId, action, expiresAt.

approval.approved

A pending approval was approved (dashboard or API). Payload includes approvalId, action, reviewedAt.

approval.rejected

A pending approval was rejected. Payload includes approvalId, action, reason, reviewedAt.

hubspot.connection.disconnected

A HubSpot connection for this org was disconnected. Payload includes connectionId, portalId.

Verifying the signature (Node.js)

import crypto from "crypto";

export function verifyRevvedAgentsWebhook(req, rawBody, secret) {
  const sent = req.headers["x-agenthub-signature"];
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(sent || "", "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Always compute the HMAC over the raw request body, before any JSON parsing. Reject any request where the signature doesn't match — the event payload may have been tampered with.

OpenAPI

Full machine-readable spec: /api/v1/openapi.json. Drop it into Postman, Stoplight, or your favorite SDK generator.

Need a use case we don't cover? Email api@revvedagents.ai — we tend to ship the obvious ones quickly.