API overview — Voidhash Docs

The base URL, request conventions, and endpoint groups of the Voidhash HTTP API.

The Voidhash HTTP API is for server integrations and custom tooling. Use it when you need to read or change project data from your own backend or scripts. Mobile apps should use one of the mobile SDKs instead. The SDKs handle device headers, identity, caching, and store transactions for you.

Base URL

All requests go to the same host:

https://api.voidhash.com

Management endpoints live under /api/v1. Analytics ingestion uses a separate surface under /i/v1.

Every management path names what it acts on. A project's resources live under /api/v1/projects/{projectId}/..., an organization's under /api/v1/organizations/{organizationId}/..., and your own under /api/v1/me/.... A project or organization your credential cannot use answers 404, like one that does not exist.

First request

Create a project secret key in Studio. Then call the session endpoint to confirm the key works and see what it resolves to:

curl https://api.voidhash.com/api/v1/session \
  -H "Authorization: Bearer $VOIDHASH_SECRET_KEY"

For a secret key, projects in the response holds the one project the key belongs to. Its id is the projectId of every project endpoint:

curl https://api.voidhash.com/api/v1/projects/$VOIDHASH_PROJECT_ID/products \
  -H "Authorization: Bearer $VOIDHASH_SECRET_KEY"

Keep secret keys on the server. See Authentication for every credential type and where each one belongs.

Endpoint groups

The API is organized into the following groups.

Group	Use
Session and me	Check a credential, and manage your own profile and connected apps.
Organizations and projects	Organizations, their members and notices, projects, their settings and audit log.
API keys	List a project's keys, and create, edit and roll secret keys while signed in to Studio.
Persons	Look up customers with their access, purchases and subscriptions, and erase their data.
Products and perks	The project catalog and the perks each product grants.
Payment providers	Store and payment source connections, product mappings, history imports and payments.
Paywalls and locations	Paywalls with their builds and deploys, and the locations that show them.
Components	Paywall components, your organization's registry and the components a project installs.
Feature flags and experiments	Flags with their variants and overrides, and experiments with their results.
Analytics and ads	Reports, stored events, the ingest policy, tracking domains, and ad accounts and reports.
Push notifications	Provider configurations, and notifications with their deliveries.
Webhooks	Manage endpoints, inspect deliveries, rotate secrets, and retry events.
Schema	Fetch the consolidated project schema and version.
SDK	Device-facing endpoints used by official SDKs.

The generated endpoint pages contain request schemas, response schemas, and an interactive client for each group.

Conventions

Lists answer { "data": [...], "pageInfo": { "endCursor", "hasNextPage" } }. Pass limit (at most 100) and, for the next page, the previous page's endCursor as cursor. Filters are plain query parameters named after the field.
Creating answers 201 with the new object and a Location header. Deleting answers 204. Archiving is an action, POST .../{id}/archive, never a delete.
Objects carry their own id. Field names are camelCase, booleans start with is or has, enumerations are snake_case strings, times are ISO 8601, and money is an integer number of minor units next to its currency.

Errors

Every management API error has the same JSON body:

{
  "error": {
    "type": "not_found",
    "code": "product_not_found",
    "message": "This project has no product prod_123.",
    "param": "productId"
  }
}

type is the broad outcome and matches the HTTP status. code is the specific reason, and each endpoint page lists the codes it can return. param, when present, names the field at fault. Branch on type and code. Do not parse the human-readable message. It can change without notice.

Status	`type`	Meaning
`400`	`invalid_request`	The request is malformed or breaks a rule.
`401`	`unauthenticated`	The credential is missing, invalid or expired.
`403`	`permission_denied`	The credential does not permit the action.
`404`	`not_found`	The resource does not exist in this scope.
`409`	`conflict`	The request conflicts with the current state.
`429`	`rate_limited`	Too many requests. Retry after the indicated delay.
`500`	`internal`	Server failure. Retry safe requests with backoff.
`503`	`unavailable`	This deployment or a service it depends on cannot do it now.

Every response carries a Request-Id header. Include it when you contact support about a request.

OpenAPI

Machine-readable specifications are available for both API surfaces. Fetch GET /api/openapi.json for the management and SDK API, and GET /i/docs/openapi.json for event capture.