Developer API

App Management API

The /v2/apps endpoints let you list, create, and retrieve your Dots apps programmatically. Understanding which response fields are included in each endpoint helps you build reliable integrations.

Response Shape Differences

The app management API returns different response shapes depending on the endpoint:

  • List and create endpoints return app objects without a metrics field.

  • Single-app detail endpoint returns the app object with a metrics field.

This distinction exists to avoid performance overhead when listing multiple apps. If you need metrics, fetch the individual app by ID.

GET /v2/apps

Returns a paginated list of your apps. Each app object in the response omits metrics.

Response Fields

Field

Type

Description

has_more

boolean

Whether more results are available

data

array

Array of app objects

Each app object in data includes:

  • id — App identifier

  • name — App name

  • status — App status

  • metadata — App metadata object

  • settings — App settings object

Example Response

{
  "has_more": false,
  "data": [
    {
      "id": "app_abc123",
      "name": "My Production App",
      "status": "active",
      "metadata": {},
      "settings": {}
    },
    {
      "id": "app_def456",
      "name": "My Sandbox App",
      "status": "active",
      "metadata": {},
      "settings": {}
    }
  ]
}

POST /v2/apps

Creates a new app and returns the created app object without metrics.

Response Fields

The response returns the created app object directly with HTTP 201:

  • id — App identifier

  • name — App name

  • status — App status

  • metadata — App metadata object

  • settings — App settings object

Example Response

{
  "id": "app_ghi789",
  "name": "New App",
  "status": "active",
  "metadata": {},
  "settings": {}
}

GET /v2/apps/:id

Retrieves a single app by ID. This endpoint includes the metrics field in the response.

Response Fields

  • id — App identifier

  • name — App name

  • status — App status

  • metadata — App metadata object

  • settings — App settings object

  • metrics — App metrics object (see below)

Metrics Object

The metrics object contains:

Field

Type

Description

wallet_balance

number

Current wallet balance for the app

money_out

number

Total amount paid out

connected_users

number

Number of connected users

Example Response

{
  "id": "app_abc123",
  "name": "My Production App",
  "status": "active",
  "metadata": {},
  "settings": {},
  "metrics": {
    "wallet_balance": 1000.00,
    "money_out": 5000.00,
    "connected_users": 150
  }
}

When to Use Each Endpoint

  • Listing apps: Use GET /v2/apps when you need an overview of all apps without detailed metrics.

  • Creating apps: Use POST /v2/apps to provision new apps; fetch metrics separately if needed.

  • Fetching metrics: Use GET /v2/apps/:id when you need wallet balance, payout totals, or user counts.

For authentication and API key setup, see Getting Started with the Dots Dashboard. For environment-specific behavior, see Understanding Sandbox vs Production Environments.

For user-level payout metrics, use GET /v2/users/{id}/metrics/payouts to retrieve payout volume for a specific user over a given timeframe.

Changing app settings

The /v2/apps endpoints return a settings object but do not write settings. To preview and apply app or organization settings changes, use the External Tooling Settings API.

Was this helpful?
Was this helpful?