API Reference

The Grantiva API is organized around REST. All requests and responses use JSON. The base URL is:

https://api.grantiva.io/api/v1/

Health check

curl https://api.grantiva.io/health

{
  "status": "healthy",
  "timestamp": "2026-07-26T12:00:00Z",
  "commit": "1ab5619"
}

See Health for the detailed and per-component checks.

Surfaces

Surface	Path prefix	Who calls it
SDK / device	`/api/v1/attestation`, `/api/v1/flags`, `/api/v1/heartbeat`, `/api/v1/feedback`, `/api/v1/support`	The iOS SDK, after attestation
Server-to-server	`/api/v1/analytics`, `/api/v1/vrt`	Your backend or CI, with an API key
Console	`/api/v1/org/*`	The dashboard, and the `grantiva` CLI with an API key

See Authentication for what each surface accepts.

Errors

Errors return a JSON envelope with a stable machine-readable code:

{
  "error": "Feature request not found",
  "code": "not_found",
  "requestId": "0AF2-4C61"
}

Status	Description
`400`	Bad request — invalid input
`401`	Unauthorized — missing or invalid authentication
`402`	Monthly active device quota exhausted
`403`	Forbidden — insufficient permissions, tier limit, or inactive tenant
`404`	Not found
`409`	Conflict — duplicate resource, or re-attestation required
`422`	Validation failed — see the `fields` array
`429`	Rate limited
`500`	Server error

The full envelope, including hint and fields, is described in API Conventions.

Rate limiting

Rate limits vary by plan and by endpoint bucket. When exceeded, the API returns 429 Too Many Requests with a Retry-After header. See API Conventions for the per-tier table.

Pagination

Paginated endpoints take page and a page-size parameter, but the response envelope differs by surface:

{
  "items": [],
  "metadata": { "page": 1, "per": 20, "total": 142 }
}

items + metadata — feature requests, devices under /api/v1/devices, audit log.
items + page + per + total (flat) — the /api/v1/org/* console endpoints.
data + meta (page, perPage, total, totalPages) — GET /api/v1/analytics/events.

Each endpoint page states which envelope it returns and what its page-size parameter is called.

Overview

Attestation

Platform

Feedback

Feature Flags

Custom Claims

Analytics

Webhooks

Organization

Push

Entitlements

Visual Regression Testing

Auth

Health check

Surfaces

Errors

Rate limiting

​Health check

​Surfaces

​Errors

​Rate limiting

​Pagination

Health check

Surfaces

Errors

Rate limiting

Pagination