Skip to main content
The Tally REST API gives you programmatic access to every capability of the Tally identity data platform — ingesting and reading entity snapshots, computing diffs, managing tenants, issuing grants, and subscribing to webhook events. Every API response is a structured JSON document, and every error follows the same predictable envelope so that your integration code stays clean and consistent.

​
Base URL

The API is served at your deployment’s base URL. All resource endpoints are prefixed with /v1: 
https://<your-tally-host>/v1
The two utility endpoints (/health and /v1/meta) are available without a version prefix and a /v1 prefix respectively, as described in the Utility endpoints section below.

​
Authentication

Every endpoint except GET /health requires a valid OIDC bearer token issued by a configured identity provider. Include the token in the Authorization header of every request: 
Authorization: Bearer <your-token>
Tokens are validated against the configured OIDC issuers. Requests with a missing, expired, or malformed token receive a 401 Unauthorized response. See the Authentication guide for instructions on obtaining and refreshing tokens.
In local and development environments, authentication may be disabled for convenience. In staging and prod deployments, authentication is always enforced and cannot be disabled.

​
Content Type

All request bodies must be encoded as JSON, and all responses — including errors — are returned as JSON. Set the Content-Type header on any request that includes a body: 
Content-Type: application/json
Tally will respond with Content-Type: application/json on every endpoint.

​
Versioning

The current API version is v1. The version prefix is part of every resource path (e.g., /v1/tenants/:tenant_id/snapshots). Snapshot payloads carry an additional versioning field, envelope_version, which is always set to "entity_state_envelope_v1". This field is stable and lets you write forward-compatible snapshot parsers without coupling to the HTTP version. When Tally introduces breaking changes, a new path prefix (/v2, etc.) will be introduced alongside the existing one, giving you time to migrate before the old version is retired.

​
Endpoints Overview

Subjects & Snapshots

Create and retrieve entity state snapshots for subjects across your tenants.

Snapshot Reads

Query the current or historical snapshot for any entity by subject and type.

Diffs

Compute attribute-level diffs between two snapshots or across a time range.

State Updates

Apply JSON Patch operations to update attributes on an existing entity state.

Tenants & Access

Manage tenants, list members, and configure tenant-level settings.

Grants

Issue, list, and revoke cross-tenant data-sharing grants.

Refresh Requests

Trigger and track on-demand data refresh requests for a subject.

Webhooks

Register webhook endpoints to receive real-time event notifications.

​
Utility Endpoints

Tally exposes two utility endpoints that are useful for health checks, deployment tooling, and debugging. Neither endpoint returns sensitive data.

​
GET /health

A simple liveness probe with no authentication required. Use this endpoint in load balancer health checks and uptime monitors. Response 
{
  "ok": true,
  "service": "@tally/api"
}

​
GET /v1/meta

Returns metadata about the running service instance, including the deployed version and build information. This endpoint requires a valid bearer token. Response 
{
  "service": "tally-api",
  "ts": "2024-11-01T12:00:00.000Z",
  "version": "1.4.2",
  "node": "v22.3.0",
  "env": "production",
  "gitSha": "a3f9c12b",
  "builtAt": "2024-11-01T08:30:00.000Z"
}
FieldTypeDescription
servicestringAlways "tally-api"
tsISO 8601 datetimeCurrent server timestamp at request time
versionstringPackage version of the running API
nodestringNode.js runtime version
envstringActive NODE_ENV value
gitShastringGit commit SHA of the deployed build
builtAtISO 8601 datetimeTimestamp when the build artifact was created

​
Pagination

List endpoints in the Tally API use cursor-based pagination. Every paginated response includes a page object: 
{
  "data": [...],
  "page": {
    "limit": 50,
    "next_cursor": "eyJpZCI6ImFiYzEyMyJ9"
  }
}
FieldTypeDescription
limitintegerThe maximum number of items returned in this page
next_cursorstring | nullAn opaque cursor pointing to the next page. null when you have reached the last page.
To fetch the next page, pass the next_cursor value as the cursor query parameter: 
GET /v1/tenants/:tenant_id/snapshots?cursor=eyJpZCI6ImFiYzEyMyJ9&limit=50
Cursors are opaque base64url-encoded strings. Do not decode, construct, or store cursors beyond a single pagination session — their internal structure is not part of the public API contract and may change without notice.
If next_cursor is null or absent, you have retrieved all available results. There is no need to make an additional request.

​
Rate Limiting

Rate limits may apply to your API requests depending on your Tally plan and deployment configuration. When a rate limit is exceeded, the API returns a 429 Too Many Requests response. Contact your account team to review or adjust your plan’s limits.