Sign in
apps

List apps

Retrieve a paginated list of apps within a project.

Use this to enumerate every app in a project. Results are ordered by app id and paginated; when hasMore is true, pass the returned cursor to fetch the next page.

Required Permissions

Your root key must have the following permission:

  • app.*.read_app (to read apps in any project)
post/v2/apps.listApps

Request body

projectstring required

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

limitinteger

Maximum number of apps to return per request. Balance between response size and number of pagination calls needed.

cursorstring

Pagination cursor from a previous response to fetch the next page. Use when hasMore: true in the previous response.

searchstring

Free-form text to filter apps. Returns apps whose ID, name, or slug contains the search string. Matching is case-insensitive.

Example request

{
  "project": "proj_1234abcd",
  "cursor": "app_1234abcd",
  "search": "checkout"
}

Response

Successfully retrieved a paginated list of apps. Use the pagination cursor for additional results when hasMore: true.

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "id": "app_1234abcd",
      "name": "Payments API",
      "slug": "payments-api",
      "git": {
        "repository": "unkeyed/unkey",
        "defaultBranch": "main"
      },
      "currentDeploymentId": "d_1234abcd",
      "createdAt": 1704067200000,
      "updatedAt": 1704153600000
    }
  ],
  "pagination": {
    "cursor": "eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ==",
    "hasMore": true
  }
}

Changes

Changed in 6 of the 90 revisions of this API.26

  • 2dcddab7f37411See the full diff
    • ▲

      removed the required property data/items/defaultBranch from the response with the 200 status

      response-required-property-removed

    • ○

      added the optional property data/items/git to the response with the 200 status

      response-optional-property-added

  • 43ad1ce9a1522See the full diff
    • ○

      the endpoint scheme security bearer was added to the API

      api-security-added

    • ○

      the endpoint scheme security rootKey was removed from the API

      api-security-removed

    This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • db25ebfde9a61See the full diff
    • ○

      the response property pagination became required for the status 200

      response-property-became-required

  • 0b9c06bab7071See the full diff
    • ○

      added the new optional request property search

      new-optional-request-property

  • 0f7e331eeffa1See the full diff
    • ▲

      removed the required property data/items/projectId from the response with the 200 status

      response-required-property-removed

  • c6b598b5f71f1See the full diff
    • ○

      endpoint added

      endpoint-added