Moatgator Public API

Version 1.0.0 · REST API for CI, scripts and integrations.

The public API v1 of Moatgator. This file is the source of truth: the server validates requests and (outside production) responses against it, src/publicapi/types.gen.ts is generated from it, and the reference page is built from it.

Authentication

Send an API key as Authorization: Bearer mg_live_... (or mg_test_...). A key belongs to one app and carries scopes (builds:write, builds:read, scans:read, threats:read, attest:verify); ask only for what the integration needs. For CI there is no key to store: a GitHub Actions job exchanges its own OIDC token for a short-lived access token (POST /v1/auth/oidc, valid 10 minutes) and sends it as Authorization: Bearer <token> in place of the key. The app must have a trust rule that names the repository and ref (or environment) allowed to do so; with no rule, nobody gets in. Access tokens never carry device scopes (attest:verify, events:ingest).

Errors

Errors use RFC 9457 application/problem+json. code is a stable machine-readable identifier; detail is for people.

Rate limits

Per API key, by the plan of the app. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets); a 429 also carries Retry-After.

Idempotency

POST operations that create something accept an Idempotency-Key header (8 to 128 characters). Repeating the same key with the same body within 24 hours returns the original response (with Idempotent-Replayed: true); the same key with a different body is a 422.

Pagination

List endpoints use opaque cursors: pass next_cursor from the previous page as cursor. Never build or parse a cursor.

Versioning

The major version is in the path (/v1). Additive changes (new fields, new endpoints) are not breaking. Deprecated operations send Deprecation and Sunset headers at least 6 months before removal. See docs/api/versioning.md.

Auth

POST`/v1/auth/oidc`

Exchange a CI OIDC token for an access token · No API key (signed URL)

In a GitHub Actions job with permissions: id-token: write, request an OIDC token with audience equal to this API's base URL and send it here with the id of the app. If a trust rule of the app matches the token (issuer, repository, ref or environment), the response is a short-lived access token (10 minutes) with the scopes granted by the matching rules. An OIDC token can be exchanged once. The same 401 answers every refusal (unknown app, no rule, wrong repository, expired, replayed token): the reason is recorded in the organization's audit trail, not revealed to the caller.

Request body `application/json`

Field	Type	Description
`token` required	string	The OIDC token issued to the CI job.
`appId` required	string (pattern `^app_[A-Za-z0-9_-]{6,40}$`)

Responses

Status	Meaning	Body
`200`	The access token.	OidcExchangeResponse
`400`	Malformed request.	Problem
`401`	Missing, malformed, revoked or expired API key.	Problem
`429`	Rate limit exceeded. See `Retry-After`.	Problem

GET`/v1/whoami`

Who am I · API key

Identifies the credential (API key or OIDC access token) without needing any scope: the app it belongs to, the plan, the scopes and when it expires. Used by moatgator whoami and moatgator doctor. Never returns the secret.

Responses

Status	Meaning	Body
`200`	The credential.	Whoami
`401`	Missing, malformed, revoked or expired API key.	Problem
`429`	Rate limit exceeded. See `Retry-After`.	Problem

Builds

POST`/v1/builds`

Register a build · API key

Registers a build of the app that owns the API key. Declare the artifact (sizeBytes, sha256) to receive a short-lived signed uploadUrl for the file. Requires scope builds:write.

Parameters

Name	In	Type
`Idempotency-Key`	header	string (pattern `^[A-Za-z0-9_.:-]+$`)

Request body `application/json`

Field	Type	Description
`platform` required	Platform
`version` required	string
`commit`	string \| null
`artifact`	ArtifactDeclaration

{
  "platform": "android",
  "version": "3.4.1",
  "commit": "9fceb02",
  "artifact": {
    "sizeBytes": 48211023,
    "sha256": "3f9c1a7e5b2d4086a1c3e5f70912b4d63f9c1a7e5b2d4086a1c3e5f70912b4d6"
  }
}

Responses

Status	Meaning	Body
`201`	Build registered.	Build
`400`	Malformed request.	Problem
`401`	Missing, malformed, revoked or expired API key.	Problem
`403`	The key lacks the required scope, or the signed URL is invalid or expired.	Problem
`409`	Conflicts with the current state (for example an idempotent request still in progress).	Problem
`422`	Well-formed but invalid (validation failed, or the idempotency key was reused with another body).	Problem
`429`	Rate limit exceeded. See `Retry-After`.	Problem

GET`/v1/builds/{id}`

Get a build · API key

Requires scope builds:read. A build of another app is a 404.

Parameters

Name	In	Type
`id` required	path	string (pattern `^bld_[A-Za-z0-9_-]{6,40}$`)

Responses

Status	Meaning	Body
`200`	The build.	Build
`401`	Missing, malformed, revoked or expired API key.	Problem
`403`	The key lacks the required scope, or the signed URL is invalid or expired.	Problem
`404`	The resource does not exist (or belongs to another app).	Problem
`429`	Rate limit exceeded. See `Retry-After`.	Problem

PUT`/v1/uploads/{token}`

Upload a build artifact · No API key (signed URL)

Uploads the file declared when the build was created, as the raw request body (application/octet-stream). The URL is the signed uploadUrl returned by createBuild; the token in the path is the credential, so it needs no Authorization header and expires in 15 minutes. The size and SHA-256 must match what was declared.

Parameters

Name	In	Type
`token` required	path	string

Request body `application/octet-stream`

Responses

Status	Meaning	Body
`200`	Artifact stored.	Build
`400`	Malformed request.	Problem
`403`	The key lacks the required scope, or the signed URL is invalid or expired.	Problem
`404`	The resource does not exist (or belongs to another app).	Problem
`409`	Conflicts with the current state (for example an idempotent request still in progress).	Problem
`413`	The body is larger than allowed.	Problem
`422`	Well-formed but invalid (validation failed, or the idempotency key was reused with another body).	Problem

Threats

GET`/v1/apps/{id}/threats`

List security events of an app · API key

Newest first. Requires scope threats:read; the key must belong to this app. Device identifiers are never returned.

Parameters

Name	In	Type
`id` required	path	string
`limit`	query	integer (min 1, max 100)
`cursor`	query	string
`detection`	query	string: `root_jailbreak`, `emulator`, `debugger`, `hooking`, `tamper`, `overlay`, `accessibility_abuse`, `screen_capture`, `remote_access`

Responses

Status	Meaning	Body
`200`	A page of events.	ThreatList
`400`	Malformed request.	Problem
`401`	Missing, malformed, revoked or expired API key.	Problem
`403`	The key lacks the required scope, or the signed URL is invalid or expired.	Problem
`404`	The resource does not exist (or belongs to another app).	Problem
`429`	Rate limit exceeded. See `Retry-After`.	Problem

Scans

GET`/v1/scans/{id}`

Get a scan · API key

Requires scope scans:read. A scan of another app is a 404.

Parameters

Name	In	Type
`id` required	path	string (pattern `^scn_[A-Za-z0-9_-]{6,40}$`)

Responses

Status	Meaning	Body
`200`	The scan.	Scan
`401`	Missing, malformed, revoked or expired API key.	Problem
`403`	The key lacks the required scope, or the signed URL is invalid or expired.	Problem
`404`	The resource does not exist (or belongs to another app).	Problem
`429`	Rate limit exceeded. See `Retry-After`.	Problem

Attest

POST`/v1/attest/verify`

Verify an attestation token · API key

Checks the attestation token an app sent to your backend. Requires scope attest:verify. The attestation backend is a stub in this version (engine: stub): the contract is stable, the verdicts are not yet backed by real platform checks.

Parameters

Name	In	Type
`Idempotency-Key`	header	string (pattern `^[A-Za-z0-9_.:-]+$`)

Request body `application/json`

Field	Type	Description
`token` required	string
`nonce` required	string
`platform` required	Platform

Responses

Status	Meaning	Body
`200`	The verdict.	AttestResult
`400`	Malformed request.	Problem
`401`	Missing, malformed, revoked or expired API key.	Problem
`403`	The key lacks the required scope, or the signed URL is invalid or expired.	Problem
`422`	Well-formed but invalid (validation failed, or the idempotency key was reused with another body).	Problem
`429`	Rate limit exceeded. See `Retry-After`.	Problem

Schemas

`Problem`

RFC 9457 problem details.

Field	Type	Description
`type` required	string (format uri)
`title` required	string
`status` required	integer (min 400, max 599)
`detail`	string
`instance`	string
`code` required	string	Stable machine-readable identifier.
`errors`	array of object	Field-level validation errors.
`retryAfter`	integer (min 1)	Seconds to wait (rate limits).

`Platform`

string: android, ios

`Sha256`

string (pattern ^[0-9a-f]{64}$)

`ArtifactDeclaration`

Field	Type	Description
`sizeBytes` required	integer (min 1, max 524288000)
`sha256` required	Sha256

`BuildCreate`

Field	Type	Description
`platform` required	Platform
`version` required	string
`commit`	string \| null
`artifact`	ArtifactDeclaration

`Artifact`

Field	Type	Description
`status` required	string: `pending`, `uploaded`
`sizeBytes` required	integer
`sha256` required	Sha256
`uploadUrl`	string (format uri)	Signed URL to PUT the file to; present while `status` is `pending`.
`uploadUrlExpiresAt`	string (format date-time)

`Build`

Field	Type	Description
`id` required	string (pattern `^bld_[A-Za-z0-9_-]{6,40}$`)
`appId` required	string
`platform` required	Platform
`version` required	string
`commit`	string \| null
`status` required	string: `succeeded`
`engine` required	string: `preview`	Builds are recorded in preview mode (no signed artifact pipeline yet).
`createdAt` required	string (format date-time)
`artifact` required	null \| Artifact

`Threat`

Field	Type	Description
`id` required	string
`detection` required	string: `root_jailbreak`, `emulator`, `debugger`, `hooking`, `tamper`, `overlay`, `accessibility_abuse`, `screen_capture`, `remote_access`
`verdict` required	string: `clean`, `suspicious`, `compromised`
`confidence` required	number (min 0, max 1)
`action` required	string: `monitor`, `warn`, `block`, `end_session`
`signals` required	array of string
`platform`	null \| Platform
`appVersion`	string \| null
`buildId`	string \| null
`occurredAt` required	string (format date-time)
`count` required	integer (min 1)	How many identical events were merged into this one.

`ThreatList`

Field	Type	Description
`data` required	array of Threat
`hasMore` required	boolean
`nextCursor` required	string \| null	Pass as `cursor` to get the next page; null on the last page.

`Finding`

Field	Type	Description
`id` required	string
`severity` required	string: `low`, `medium`, `high`, `critical`
`title` required	string
`detail` required	string
`fix` required	string

`Scan`

Field	Type	Description
`id` required	string (pattern `^scn_[A-Za-z0-9_-]{6,40}$`)
`appId` required	string
`engine` required	string: `preview`, `static`	`static` = analysis of an uploaded package; `preview` = rules over declared metadata.
`grade` required	string (pattern `^[A-F][+-]?$`)
`score` required	integer (min 0, max 100)
`target` required	object
`findings` required	array of Finding
`createdAt` required	string (format date-time)

`Whoami`

Field	Type	Description
`appId` required	string
`plan` required	string: `hatchling`, `indie`, `startup`, `scale`, `enterprise`
`scopes` required	array of string
`auth` required	string: `api_key`, `oidc`
`expiresAt` required	string \| null (format date-time)

`OidcExchangeRequest`

Field	Type	Description
`token` required	string	The OIDC token issued to the CI job.
`appId` required	string (pattern `^app_[A-Za-z0-9_-]{6,40}$`)

`OidcExchangeResponse`

Field	Type	Description
`accessToken` required	string	Send as `Authorization: Bearer <accessToken>`. Never log it.
`tokenType` required	string: `Bearer`
`expiresIn` required	integer	Seconds until the token expires.
`scopes` required	array of string: `builds:write`, `builds:read`, `scans:read`, `threats:read`
`appId` required	string

`AttestRequest`

Field	Type	Description
`token` required	string
`nonce` required	string
`platform` required	Platform

`AttestResult`

Field	Type	Description
`valid` required	boolean
`verdict` required	string: `trusted`, `suspicious`, `untrusted`
`reasons` required	array of string
`engine` required	string: `stub`	The attestation backend is a stub in this version.

Moatgator Public API

Authentication

Errors

Rate limits

Idempotency

Pagination

Versioning

Auth

POST/v1/auth/oidc

Request body application/json

Responses

GET/v1/whoami

Responses

Builds

POST/v1/builds

Parameters

Request body application/json

Responses

GET/v1/builds/{id}

Parameters

Responses

PUT/v1/uploads/{token}

Parameters

Request body application/octet-stream

Responses

Threats

GET/v1/apps/{id}/threats

Parameters

Responses

Scans

GET/v1/scans/{id}

Parameters

Responses

Attest

POST/v1/attest/verify

Parameters

Request body application/json

Responses

Schemas

Problem

Platform

Sha256

ArtifactDeclaration

BuildCreate

Artifact

Build

Threat

ThreatList

Finding

Scan

Whoami

OidcExchangeRequest

OidcExchangeResponse

AttestRequest

AttestResult

POST`/v1/auth/oidc`

Request body `application/json`

GET`/v1/whoami`

POST`/v1/builds`

Request body `application/json`

GET`/v1/builds/{id}`

PUT`/v1/uploads/{token}`

Request body `application/octet-stream`

GET`/v1/apps/{id}/threats`

GET`/v1/scans/{id}`

POST`/v1/attest/verify`

Request body `application/json`

`Problem`

`Platform`

`Sha256`

`ArtifactDeclaration`

`BuildCreate`

`Artifact`

`Build`

`Threat`

`ThreatList`

`Finding`

`Scan`

`Whoami`

`OidcExchangeRequest`

`OidcExchangeResponse`

`AttestRequest`

`AttestResult`