Platform · API
The same API the product runs on, documented
Everything the web console and the mobile app do, they do through the Spy Monk REST API. Business-plan customers can use it directly: create audits, read mentions and coverage, run monitoring, manage cases and approvals, and pull report data into their own systems — with the same scoping, approvals and honesty rules as the interface.
Updated By Drive Digital Editorial
OpenAPI 3.0 spec · Idempotency on every money and case endpoint · Approval rules enforced server-side
Direct answer
Does Spy Monk have an API?
Yes. Spy Monk exposes a versioned REST API (/v1) described by an OpenAPI 3.0 specification. It authenticates with bearer tokens, scopes every request to one workspace, accepts an Idempotency-Key on endpoints that create audits, cases, approvals, orders or monitoring runs, and returns structured errors. API access is an entitlement of the Business plan; dedicated API keys are pending feasibility.
- Authentication: Authorization: Bearer <access token>; optional X-Tenant-Id to select a workspace you belong to
- Idempotency-Key (8–128 chars) on POST /audits, /cases, /cases/:id/approvals, /billing/orders, /monitoring/projects/:id/run — same key + same body within 24 h replays the stored response
- Rate limits: 120 requests per minute per address; stricter limits on one-time codes and the public enquiry form
- Errors: { statusCode, error, message, details? }; validation failures list the field path
Design
One API, no privileged back door
Spy Monk has a single API. The web console, the companion app and any customer integration call the same endpoints with the same rules. There is no internal route that skips tenant scoping, bypasses an approval or returns a source as live when it was not. If you build on the API you inherit all of that, which is the point: a report pulled by script carries the same coverage table as the one on screen.
The API is a modular monolith behind /v1 — HTTP controllers plus background workers for audits and monitoring — on PostgreSQL and Redis. Requests and responses are validated against schemas that are shared with the interface, so the shapes you see in the specification are the shapes the product itself uses. The specification (OpenAPI 3.0) is generated from the code and covers every route with request and response schemas; it ships with the product and will be published alongside this page at launch.
Three conventions are worth knowing before you write a line of code.
Conventions
What every integration should expect
- Available now
Workspace scoping
Your token carries the active workspace. Pass X-Tenant-Id to work in another workspace you are a member of. A resource id from a workspace you do not belong to returns the same 404 as an unknown id — and the attempt is audit-logged.
- Available now
Idempotency
Send an Idempotency-Key with any request that creates money, credit or case effects. The same key with the same body within 24 hours replays the first response with Idempotent-Replayed: true; the same key with a different body is refused with 409 IDEMPOTENCY_KEY_REUSED.
- Available now
Structured errors
Every error is { statusCode, error, message, details? }. Validation errors return 400 with the field path and message for each problem; entitlement limits return 403 ENTITLEMENT_EXCEEDED; an empty credit balance returns 402 INSUFFICIENT_CREDITS.
- Available now
Pagination
List endpoints return { items, page, pageSize, total }; page sizes up to 100.
- Available now
Approvals enforced server-side
A case cannot move from Awaiting Approval to Submitted without an approval record created by an Admin or Owner. Legal escalation returns 409 PROFESSIONAL_REVIEW_REQUIRED until the review flow exists. No script can skip it.
- Available now
Roles honoured
Analysts can create entities, audits, projects and cases; Admins and Owners additionally approve, manage members and buy. The API checks the role on every call.
Surface
Resource groups in /v1
A map, not the reference — the OpenAPI document is the reference.
| Group | What it does | Notes |
|---|---|---|
| auth | One-time codes, Google sign-in, two-factor, refresh, sign-out, session | Mobile token mode returns tokens in the body with X-DRS-Client: mobile |
| tenants, entities | Workspace, members, invites, usage; the people, brands and products you protect | Entity limits per plan; aliases up to 20 |
| audits | Create (one credit), list, read with findings and coverage, mentions, PDF, rerun | Idempotent create; 402 when the balance is empty |
| mentions | Query, statistics, update status/tags/sentiment, submit a URL, capture evidence, bulk actions | Safe fetching with SSRF protection on submit-url |
| monitoring/projects | Create, update, run now; schedules by plan | Scheduled runs debit one credit and hold when the balance is empty |
| cases | Create, transition, approvals, notes, link mentions, upload evidence | Transitions validated; approvals single-use; evidence ≤ 15 MB with SHA-256 |
| reports, notifications, communication | Overview per entity and period; report downloads by expiring link; notification history; communication preferences (e-mail and WhatsApp) and per-channel delivery states | Mandatory notification types cannot be muted |
| billing | Plans, subscription, orders, verification, ledger, payments, cancel | Razorpay or Paytm; signatures verified; production refuses demo |
| connectors | Health of sources and account connectors | Reports every provider as pending feasibility until approved |
| leads | Public enquiry form | Honeypot, throttle, escaped storage |
Source: docs/API-CONTRACT.md and docs/openapi.json in the product repository. Endpoints marked Phase 2 in the product are absent from the API too — nothing is exposed before it works.
Access
How you get access, and what is still pending
API access is an entitlement of the Business plan. Today, authentication uses the same tokens as the applications: sign in with a one-time code (and two-factor if enabled) to obtain a fifteen-minute access token and a thirty-day refresh token, then refresh on rotation. This is secure and fully supported, but it means an integration acts as a user of your workspace.
Dedicated API keys — long-lived credentials tied to a workspace rather than a person, with their own scopes and revocation — are pending feasibility. We would rather ship them with proper scoping and audit than quickly. Until then, we recommend a dedicated member account with the Analyst role for read and create operations, and no automated approvals: approvals are decisions people should make.
Webhooks from Spy Monk to your systems (for example, a high-risk mention or a case status change) are also pending feasibility; today you poll the notifications and cases endpoints, which are paginated and cheap.
If you are evaluating the API for an agency, a hospital group or a product team, write to us with the workflow you have in mind. We will tell you plainly what the API does today and what would have to wait.
Availability
API capabilities by status
- Versioned REST API with OpenAPI 3.0 specificationAvailable now
- Bearer-token authentication; mobile token modeAvailable now
- Idempotency keys on money, credit and case endpointsAvailable now
- Workspace scoping, roles and approvals enforced on every callAvailable now
- API access entitlement on the Business planAvailable now
- Published, browsable API reference on this sitePhase 2The specification exists and ships with the product; the public reference page follows at launch.
- Dedicated API keys with scopes and revocationPending feasibility
- Outbound webhooks for mentions and case eventsPending feasibility
- Agency and white-label APIsPending feasibilityPhase 5.
- Available now
- Available now5 items
- Phase 2
- Phase 21 item
- Pending feasibility
- Pending feasibility3 items
Questions
API questions
Which plan includes the API?
Business. Starter and Pro customers use the web console and the app; the same endpoints exist, but programmatic access is not part of those plans.
Can I create audits by script?
Yes. POST /v1/audits with an entity id, or with a query and kind, sends an Idempotency-Key and debits one scan credit. The response carries the audit, and GET returns findings, the coverage table and the summary when it completes.
Can a script approve a case?
Technically an Admin token can create an approval record through the API. We recommend against automating it: an approval is a human decision that names a recipient and an action, and the audit log records who made it.
Is there a sandbox?
Development servers run with a demo payment gateway and seeded demo sources, clearly labelled. A hosted sandbox for customers is pending feasibility; ask us when you evaluate.
What are the rate limits?
120 requests a minute per address for general endpoints, with stricter limits on one-time codes and the public enquiry form. Exceeding them returns 429; back off and retry.
Does the API expose anything the interface hides?
No. Sources that are not configured are reported as unavailable in the API exactly as on screen, Phase 2 features are absent rather than stubbed, and approval rules are enforced server-side.
Talk to us about an integration
Tell us the workflow. We will say what works today, what is Phase 2 and what is pending — before you commit.
No card needed