Anomity Zapier API

Overview

The Anomity app on Zapier starts Zaps from Anomity events and acts on Anomity findings. It is built on a small JSON-over-HTTPS API, documented here in full. You do not need to call it yourself to use the Zapier app; this page is for teams who want to know exactly what the app does with their data, and for reviewers.

The base URL is https://app.anomity.ai/api/zapier/v1. Every request and response body is JSON, every request is made over HTTPS, and every answer is scoped to the organization of the person who connected the account.

• Triggers (instant): New Finding, New MCP Server Detected, New AI Tool Detected, New Blocked Agent Action.
• Actions: Update Finding Status, Add Comment to Finding.
• Search: Find Finding.

Authentication

The API uses OAuth 2.0 with the authorization code flow, through the same sign-in a person uses for the Anomity console. The authorization server is https://login.anomity.ai/. Zapier requests the audience https://app.anomity.ai/api/zapier and the scopes openid, profile, email and offline_access, the last of which issues a refresh token so a Zap keeps running after the access token expires.

Send the access token as a bearer token in the Authorization header. The API accepts only tokens issued for its own audience, and verifies them itself. A missing, expired or foreign token is answered with HTTP 401, which tells Zapier to refresh the token and retry.

There is no separate API key. A connection can never do more than the person who connected it can do in the console, and suspending that person, or their organization, stops the connection on its next call.

Permissions

Each endpoint requires a minimum Anomity role, the same role the console requires for the same action. Roles rank viewer, analyst, admin, owner.

• Viewer: read the connected account, read findings, read trigger samples, and turn off a Zap the person turned on.
• Analyst: update a finding's status and comment on a finding.
• Admin: turn on a Zap. Turning on a Zap sends the organization's events to a third party, so it needs the same role as connecting a SIEM. An admin can also turn off any Zap in the organization.
• Below admin, ignoring or dismissing a finding needs a reason and an end date at most 90 days away, exactly as on the Findings page.

Endpoints

Paths are relative to https://app.anomity.ai/api/zapier/v1.

• GET /me - the connected account: id, email, name, role, orgId and orgName. Zapier uses it as the connection test and labels the connection with the email.
• POST /hooks - subscribe a Zap. Body: event (violation, new_mcp, new_agent or hook_deny), targetUrl (the hook address Zapier generated, which must be on https://hooks.zapier.com/), and optional filters. For the violation event, filters may carry minSeverity (low, medium, high or critical) and policyTypes (a list of Anomity policy types). Answers 201 with the subscription id.
• DELETE /hooks/{id} - unsubscribe a Zap. Answers 200 with removed true, or removed false when the subscription was already gone, so turning a Zap off always succeeds.
• GET /samples/{event} - up to 10 recent real items for a trigger, in exactly the shape a live event has; limit defaults to 3. Empty when the organization has no such items yet.
• GET /findings - recent findings, newest first. Query parameters: status, severity, and limit (default 25, at most 100).
• GET /findings/{id} - one finding. Answers 404 when there is no finding with that id in the organization.
• PUT /findings/{id}/status - change a finding's status. Body: status (open, acknowledged, in_progress, resolved, ignored or dismissed), and for ignored or dismissed, reason and until (an ISO 8601 date). Answers with the updated finding.
• POST /findings/{id}/comments - add a comment. Body: text, at most 5,000 characters. Answers 201 with the comment id, findingId, text, author and createdAt.

The finding object

Find Finding, Update Finding Status and the finding list return the same fields. Internal evaluation details are not included.

• id, policyName, policyType, severity, status and description.
• deviceId and deviceHostname, for a finding raised on a managed device. A finding about a cloud account or a vendor organization has no device.
• agentName and mcpServerName, when the finding names an AI tool or an MCP server.
• assigneeName, dueDate, createdAt and resolvedAt, with dates in ISO 8601.
• link - the finding's page in the Anomity console.

The event a trigger delivers

When a subscribed Zap's event happens, Anomity sends an HTTPS POST to the Zap's hook address with a JSON array of events, and Zapier starts one Zap run per element. Every event carries the fields below, and fields that do not apply to an event are absent rather than empty.

• eventId - unique per Zap and event. Delivery is at least once, so use it to recognise a repeat.
• schema_version - the version of this field set, currently 1. A field is never renamed or removed without a new version.
• eventType - violation, new_mcp, new_agent, or hook for a blocked agent action.
• severity, policyName (the event's title) and description.
• message - one human-readable sentence describing the event.
• id, policyType and findingStatus - for findings only.
• decision - for a blocked agent action, always deny.
• deviceId, deviceName and deviceHostname - the machine the event happened on, when there is one.
• occurredAt - ISO 8601.
• link - the event's page in the Anomity console; a finding links to that finding.

Delivery

Events are queued and delivered within about a minute, in batches of at most 100 events and 1 MB. A Zap that is failing never holds back another Zap's events.

If Zapier answers 410 Gone, the Zap no longer exists, and Anomity deletes the subscription. A timeout, a 408, a 429 or a 5xx answer is retried, honouring Retry-After, up to 10 attempts. Any other answer drops that batch and records the error, which an admin can see on the organization's Zapier card in the console. Events that cannot be delivered within 7 days are discarded.

Errors and limits

Errors are JSON with an error field holding a sentence written for a person, for example the reason an analyst cannot ignore a finding without an end date.

• 400 - the request was refused: an unknown event, a hook address not on hooks.zapier.com, an invalid status, or a missing exception reason.
• 401 - no valid token for this API. Zapier refreshes the token and retries.
• 403 - the connected person's role does not allow this, or the person or organization is suspended.
• 404 - no such finding or subscription in this organization.
• 429 - more than 120 requests in a minute for one connected person. Retry after the window.
• At most 25 Zaps per organization can receive Anomity events at once.

Managing connected Zaps

In the Anomity console, Settings, Integrations, Automation, Zapier lists every Zap receiving the organization's events: its trigger and filters, who turned it on, when it last delivered, and its last error. An admin can disconnect one Zap or all of them there. Every Zap turned on or off, and every change a Zap makes to a finding, is recorded in the organization's Audit Log, marked as made through Zapier.

Questions, or something on this page that has drifted from what the API returns: [email protected].