API surface map¶

This page is the human-readable map of AppGantry's public HTTP surfaces. Use it to find the right resource family; use the interactive API reference for exact parameters, request bodies, responses, and per-operation authorization.

Base URLs¶

Surface	Production base	Purpose
Customer API	`https://api.appgantry.com/api/v1`	Authenticated account, organization, project, build, release, and automation operations
Public install API	`https://api.appgantry.com/public/v1`	Unauthenticated or capability-token install and device-enrollment flows
In-app update API	`https://api.appgantry.com/sdk/v1`	SDK enrollment, token refresh, update checks, downloads, and install reports

Before choosing an operation¶

Pick the surface from the table above.
Pick the resource family below.
Check the operation's authentication and role requirements in the interactive reference.
Follow API conventions for envelopes, pagination, uploads, retries, and parent scoping.

Do not infer a universal URL shape. Some project operations use a project identifier plus an organization_id query parameter; others are nested below an organization. Follow the individual operation.

Resource families¶

Each heading below matches a tag in the published OpenAPI schema. Most families belong to the customer API; the two that do not are annotated in place — Public covers /public/v1 and SDK covers /sdk/v1.

Audit¶

Read an organization's audit trail, or the calling developer's own. Both answer a single UTC day by default and accept a date range for export, each with its own event cap; a truncated result is flagged with the X-Audit-Truncated response header. The organization feed is Admin-only and masks operator-sensitive values; the per-developer feed is self-only and needs an interactive sign-in. See Audit events.

Builds¶

List and read builds, initiate and complete the three-phase upload, download an artifact, edit a build's release notes after upload, revoke a build, or permanently delete it. Release notes are the only editable field: everything else about a build is fixed from initiate time onward. Start with Uploading a build.

Channels¶

List, create, read, edit, and delete channels; inspect channel analytics; and manage direct channel testers and short-lived channel tester invitations.

Developers¶

Create and read an account, edit the profile, manage the avatar and email address, verify email, request or complete password reset, request and download a personal data export, and schedule or cancel deletion.

Devices¶

List and remove enrolled Apple devices and mint a device-enrollment flow. The related public operations serve the enrollment landing page, configuration profile, and callback.

Feature Flags¶

Read the effective feature-flag set for an organization. It is a diagnostic read, not a control surface: there is no write operation here, and a customer cannot change a flag. Reach for it when a capability is missing and you need to tell "off here" from "broken".

The response is an object with two properties, both always present: organization_id, which echoes the organization you asked about, and flags. flags is the flat {flag_key: boolean} map — the body itself is not — and each value already has any organization-specific setting applied. Two keys are published:

Flag key	Default	What it gates
`new_org_signups_enabled`	On	Whether new organizations can be created. It is a kill switch: once it is off platform-wide, a per-organization setting cannot turn it back on.
`beta_dashboard`	Off	A dark-launch gate for an in-development dashboard, switched on per organization during rollout.

Three properties matter when you read flags:

Archived flags are omitted. A retired flag stops appearing rather than flipping to false.
A key you do not see is off. Treat an absent key as false rather than as an error, so a flag added or retired later does not break your client.
The key set is closed and the names are stable. They are declared in code, not invented per organization.

Reading it needs the organization Read role. Note that the deployment and plan gates described in Feature availability are configuration rather than entries in this map, so a capability can be unavailable to you without a flag saying so.

Sign in with email/password, complete MFA, sign in with a passkey, refresh or revoke a session, and exchange an SSO handoff code.

MFA¶

Read MFA status; begin and confirm TOTP enrollment; regenerate recovery codes; and disable MFA.

Miscellaneous¶

Read service metadata and platform version information, obtain a captcha challenge, and preview or accept organization/project invitations.

Organizations¶

List the organizations you belong to, create one, then read, rename, or delete it. Manage the organization icon, members, invitations, ownership, tier changes, leaving, payment setup, prepaid credit, usage, usage estimates and events, spend caps, MFA policy, organization testers, and tester groups. Organization tester operations include a per-tester read that returns one active tester's direct grant alongside the tester groups they belong to.

SAML SSO configuration and storage-backend (BYOSA) management are also in this family, because both are organization-scoped:

SSO — read, create or replace, and delete the SAML connection; enable or disable it; enforce require-SSO; claim and verify email domains; fetch the service-provider metadata; plus the browser-facing login, assertion-consumer, logout and Single Logout endpoints. Configuring SSO is a Business capability. See Single sign-on.
BYOSA — read the organization's storage backend, submit or withdraw an onboarding request, read its status, and re-run the storage validation checks on demand. See BYOSA setup.

The configuration operations in both groups require an interactive sign-in: a personal or project access token is refused whatever its scope. Three SSO endpoints are the deliberate exception — the sign-in redirect, the assertion-consumer callback and the Single Logout service the identity provider calls back on carry no AppGantry credential at all, because nothing has signed in by the time they are reached. Beginning SP-initiated Single Logout is a signed-in call and is not one of them.

Passkeys¶

List passkeys, begin and finish registration, rename a passkey, or delete it. Passwordless and MFA passkey sign-in live under Login.

PATs¶

Create and list personal access tokens, discover grantable scopes, rotate, revoke, and permanently delete a token. Organization Admins can also list every PAT in an organization and revoke one during offboarding.

Platforms¶

List the platform identifiers accepted when creating projects and uploading builds. This operation requires no authentication.

Project Access Tokens¶

Create and list project-bound automation tokens, then rotate, revoke, or permanently delete them. See CI uploads.

Projects¶

List, create, read, update, and delete projects; manage project icons, members, invitations, and project-level testers, including a per-tester read that returns one active tester's direct project grant alongside the tester groups they belong to. The schema contains both organization-nested and project-addressed forms where the service supports both.

Public¶

Read the current release of a public channel and obtain public or capability-token downloads and iOS install manifests. These operations live on the /public/v1 surface and do not accept a normal developer session.

Publish¶

Create a store-publish job, list a project's jobs, and read one back. Creating needs the project Editor role; the reads need Read.

Publishing is not operational

A job can be created and read back, but no store provider is connected yet, so every job ends failed and no artifact reaches the store. Use App Store Connect or the Google Play Console for store releases today. See Store connections & publishing.

Releases¶

Create, list, and read releases; find current releases; inspect analytics and install status; mark a release mandatory or optional; disable, enable, roll back, or delete it.

SDK¶

Enroll an app install and mint its update token, rotate that token, fetch app display metadata, check for the latest release, download it, obtain the iOS install manifest, and report install state. Seven operations, all on the /sdk/v1 surface. No developer credential is sent here — not a JWT, not a personal or project access token — but the surface is not open either: every operation except enrollment and the iOS manifest carries the per-install update token that enrollment mints. See the SDK HTTP API for the wire-level flow and the SDK documentation for the Swift package.

SDK Apps¶

Create, list, and revoke the app credentials that connect a channel to the in-app updates SDK. These are customer API operations; the installs they enroll then talk to /sdk/v1.

Sessions¶

List active sessions, revoke one session, or revoke all sessions. Long-lived access tokens are refused on this account-security surface.

Store Connections¶

Create, list, read, update, and delete provider connections and register Apple test devices through a connection. Secret credentials are write-only and are not returned after creation.

Testers¶

Preview and accept channel tester invitations; list the organizations, projects, channels, and releases available to the signed-in tester; manage per-channel email preferences; and mint platform-specific install links.

Webhooks¶

Create, list, read, update, and delete subscriptions; list delivery attempts; send a test delivery; and rotate the signing secret. All five resource events are delivered; webhook.test is delivery-only and cannot be subscribed to. See Webhook events.

Credentials by surface¶

Authentication → Credential types is the canonical table of credentials, what each one is for, and how it is carried.

Some sensitive account, organization and token-management operations require an interactive access JWT and reject PATs and project access tokens with 403. The categories are listed in Authentication → Where long-lived tokens are refused; Authorization explains why each one is drawn where it is.

Rate limiting and 429¶

No operation in the published schema declares a 429 response, and that is a gap in the schema rather than a promise: throttling is applied both at the edge and inside the application, so any operation can answer 429. Handle it by status class rather than by looking it up per operation. See Rate limits.

Common automation paths¶

Goal	Operations
Upload from CI	`POST /api/v1/builds/initiate` → storage `PUT` → `POST /api/v1/builds/{pending_upload_id}/complete`
Promote a build	Create a release under Releases, then manage mandatory/enable/rollback state there
Maintain tester access	Use organization/project tester operations, channel tester operations, or tester groups
Receive changes	Create a Webhook, store the one-time secret, then monitor Webhook deliveries
Run an in-app update client	Create an SDK App, enroll through `/sdk/v1`, then check and report updates — see the SDK HTTP API
Investigate access	Read roles and token grants, then read the organization audit feed under Audit

Schema and compatibility¶

The raw schema is available at /api/openapi.json. The interactive reference is generated from that same committed document.

The /api/v1, /public/v1, and /sdk/v1 version segments are part of the contract. Within a version, clients must tolerate additive fields and ignore fields they do not recognize. Breaking changes use a new versioned path.