Ahoy REST API v1

The Ahoy REST API lets you read and write CRM records from your own systems. It is a small, deliberately regular surface: 20 operations over every object type your credential can reach, rather than a bespoke endpoint per entity.

This API is in beta

v1 is usable and we support it, but it has not yet reached general availability. Concretely, that means:

• Breaking changes are possible before GA, and we will tell you before making one. Outside beta, v1 would only ever change additively.
• The surface is enabled per organisation. If requests return service_unavailable with reason: "surface_disabled", the API is not switched on for your org yet — talk to us.
• Please tell us what breaks. Beta is when feedback still changes the design. Quote the request_id from any response you are asking about.

Note

AI agents should use the MCP surface, not this one. This API is for conventional server-to-server integrations.

Base URL

https://api.ahoy.ai/rest/v1/

There is no organisation id in the path. Your credential already belongs to one org, and the server resolves it from the token — so a key can never accidentally read another org’s data by changing a path segment.

Your first request

curl https://api.ahoy.ai/rest/v1/self/ \
  -H "Authorization: Bearer $AHOY_API_KEY"

{
  "data": {
    "org_id": 42,
    "principal_id": "prn_01J8Z2K9QW3X4Y5Z6A7B8C9D",
    "reach": "user"
  }
}

GET /rest/v1/self/ is the fastest way to confirm a key works, see which org it belongs to, and check its reach.

Conventions

Every part of the API follows the same rules, so you only have to learn them once.

Success envelope	Payloads are wrapped: {"data": ...}
Errors	RFC 9457 application/problem+json with a closed code enum
Pagination	Cursor-based — follow pagination.next_cursor
Rate limits	Per org, reported on every response
Tracing	request_id in every body, Ahoy-Request-Id on every response
Caching	Cache-Control: no-store — responses are never cached

Discovery

Two endpoints need no authentication:

Endpoint	Returns
GET /rest/v1/	Version, OpenAPI URL, and docs URL
GET /rest/v1/openapi.json	The full OpenAPI 3.1 document

The OpenAPI document is the same artifact this documentation is generated from, so the two can never disagree.

Versioning

v1 is the major version. Additive changes ship without a version bump — new endpoints, new fields on existing responses, and new reason sub-codes can appear at any time.

While v1 is in beta, breaking changes remain possible; we will announce them before they ship. Once v1 reaches GA, only additive changes will be made to it.

Write clients that tolerate unknown fields and unknown reason values. If v1 is ever deprecated, responses will carry Deprecation and Sunset headers well in advance.