REST API

All endpoints are under /api/v1. Requests and responses use JSON.

Authentication

There are two authentication modes depending on the operation:

Bearer tokenCLI / server operations — upload, release, list. Use your organization secret key (otakit_sk_...) or a user access token from otakit login. The app ID is part of the URL path.

X-App-IdPlugin / read-only operations — manifest fetch, event reporting. Uses the app ID (no secret needed).

# CLI / server operations
Authorization: Bearer otakit_sk_...   # or OTAKIT_ACCESS_TOKEN

# Plugin operations
X-App-Id: app_uuid

Apps

POST/api/v1/apps

Create a new app. The slug should match your Capacitor app identifier. Returns an appId for plugin and CLI usage.

Auth: Bearer

Request body

{ "slug": "com.example.myapp" }

Response

{
  "id": "uuid",
  "slug": "com.example.myapp",
  "createdAt": "ISO timestamp"
}

Bundles

POST/api/v1/apps/:appId/bundles/initiate

Start a bundle upload session. Returns a presigned PUT URL. Upload your zip file to this URL with Content-Type: application/zip.

Auth: Bearer

Request body

{
  "version": "1.0.1",       // semver string
  "size": 1048576,          // bundle size in bytes
  "sha256": "64-char hex checksum of the zip file",
  "minNativeBuild": 100     // optional
}

Response

{
  "uploadId": "uuid",
  "presignedUrl": "https://...",
  "storageKey": "...",
  "expiresAt": "ISO timestamp"
}

POST/api/v1/apps/:appId/bundles/finalize

Finalize a bundle upload session. The server checks that the uploaded object exists and that its size matches the initiated session, then creates the bundle record from the stored session data.

Auth: Bearer

Request body

{
  "uploadId": "uuid"
}

Response

{
  "id": "uuid",
  "version": "1.0.1",
  "sha256": "...",
  "size": 1048576,
  "minNativeBuild": null,
  "createdAt": "ISO timestamp"
}

GET/api/v1/apps/:appId/bundles

List bundles sorted by creation date (newest first).

Auth: Bearer · Query: ?limit=20&offset=0

Response

{
  "bundles": [{ id, version, sha256, size, createdAt }],
  "total": 42
}

DELETE/api/v1/apps/:appId/bundles/:bundleId

Delete a bundle. Bundles that are part of a release history cannot be deleted.

Auth: Bearer

Response

{ "deleted": true, "id": "uuid" }

Releases

POST/api/v1/apps/:appId/releases

Release a bundle to the base stream or a named channel. One bundle = one release event.

Auth: Bearer

Request body

{
  "bundleId": "uuid",
  "channel": "staging"   // optional; omit or null for base stream
}

Response

{
  "release": {
    "id": "uuid",
    "channel": null,
    "bundleId": "uuid",
    "bundleVersion": "1.0.1",
    "promotedAt": "ISO timestamp"
  },
  "previousRelease": { ... } | null
}

GET/api/v1/apps/:appId/releases

List release history sorted newest first. Omit channel to list every stream, or pass an empty channel value to query only the base stream.

Auth: Bearer · Query: ?channel=staging&limit=20&offset=0

Response

{
  "releases": [{
    id, channel, bundleId, bundleVersion, promotedAt
  }],
  "total": 12
}

Manifest (Plugin)

GET/api/v1/manifest

Check for the latest bundle on the base stream or an optional named channel. Used by the Capacitor plugin. Returns a signed download URL with 10-minute TTL. X-Native-Build is the installed native app build number, and minNativeBuild blocks OTA bundles that require a newer native binary from the app store.

Auth: X-App-Id

Headers

X-App-Id: app_uuid
X-Platform: ios
X-Channel: staging              // optional
X-Current-Version: 1.0.0        // optional
X-Native-Build: 100             // optional native app build number

Response

// 204 No Content — already up to date

// 200 OK — update available
{
  "version": "1.0.1",
  "channel": null,
  "releaseId": "release_uuid",
  "url": "https://... (signed, 10min TTL)",
  "sha256": "...",
  "size": 1048576,
  "minNativeBuild": null,
  "signature": { "kid": "...", "sig": "...", "iat": ..., "exp": ... }
}

// 406 Not Acceptable — native build too old
{ "error": "native_build_too_old", "minNativeBuild": 200 }

Device Events

POST/api/v1/stats

Record a device event for analytics. Used by the plugin to report update lifecycle events.

Auth: X-App-Id

Request body

{
  "platform": "ios",
  "action": "downloaded",      // downloaded, success, error
  "bundleVersion": "1.0.1",   // optional
  "channel": "staging",       // optional named channel
  "releaseId": "release_uuid",// optional
  "errorMessage": "..."       // optional, max 500 chars
}

Response

{ "success": true }

CLI Config

The otakit CLI reads project values from capacitor.config.*. Environment variables and CLI flags can override them.

plugins: {
  OtaKit: {
    appId: "app_xxxxxxxx",
    // Optional named track
    // channel: "staging"
  }
}

webDir: "out"