List Apps

GET /clients/{client_id}/apps

Returns a paginated list of the client's applications. Each app includes its full catalog metadata (name, logo, vendor, categories) alongside client-specific fields.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization

Query Parameters

Parameter	Type	Default	Description
q	string	-	Search against canonical_name (case-insensitive, partial match)
category_id	string (uuid)	-	Filter to apps in a specific catalog category
vendor_id	string (uuid)	-	Filter to apps from a specific catalog vendor
type	string	-	Filter by catalog app type
is_favorite	boolean	-	Filter by favorite status: true (favorites only), false (non-favorites only)
is_approved	boolean	-	Filter by approval status: true (approved only), false (unapproved only)
sort_by	string	canonical_name	Sort field: canonical_name, created_at, updated_at
sort_order	string	asc	Sort direction: asc, desc
page_size	integer	50	Items per page. Max: 500
cursor	string	-	Pagination cursor from a previous response

Response

Field	Type	Description
data	App[]	Array of app objects
total_count	integer	Total number of apps matching the current filters
next_cursor	string | null	Cursor for the next page. null when on the last page.

Example Requests

List all apps

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/apps" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Search by name

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/apps?q=slack" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filter favorites by category

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/apps?is_favorite=true&category_id=a7b8c9d0-e1f2-3456-abcd-789012345678" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "data": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "catalog_app": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "canonical_name": "Slack",
        "description": "A messaging and collaboration platform for teams",
        "display_colour": "#4A154B",
        "logo": "https://cdn.example.com/logos/slack.png",
        "type": "desktop",
        "vendor": {
          "id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
          "name": "Salesforce, Inc.",
          "url": "https://www.salesforce.com"
        },
        "categories": [
          { "id": "a7b8c9d0-e1f2-3456-abcd-789012345678", "name": "Communication" }
        ],
        "created_at": "2025-06-15T10:00:00.000Z",
        "updated_at": "2026-02-10T09:15:00.000Z"
      },
      "is_favorite": true,
      "is_approved": true,
      "license_count": 25,
      "created_at": "2026-01-15T10:00:00.000Z",
      "updated_at": "2026-02-20T14:30:00.000Z"
    },
    {
      "id": "g2b3c4d5-e6f7-8901-bcde-f12345678901",
      "catalog_app": {
        "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
        "canonical_name": "GitHub",
        "description": "Code hosting and collaboration platform",
        "display_colour": "#24292F",
        "logo": "https://cdn.example.com/logos/github.png",
        "type": "browser",
        "vendor": {
          "id": "a8b9c0d1-e2f3-4567-abcd-890123456789",
          "name": "GitHub, Inc.",
          "url": "https://github.com"
        },
        "categories": [
          { "id": "b8c9d0e1-f2a3-4567-bcde-901234567890", "name": "Development" }
        ],
        "created_at": "2025-06-15T10:00:00.000Z",
        "updated_at": "2026-01-20T14:30:00.000Z"
      },
      "is_favorite": false,
      "is_approved": false,
      "license_count": null,
      "created_at": "2026-01-20T08:00:00.000Z",
      "updated_at": "2026-01-20T08:00:00.000Z"
    }
  ],
  "total_count": 78,
  "next_cursor": "eyJsYXN0X2lkIjoiZzJiM2M0ZDUifQ"
}

Empty Result

{
  "data": [],
  "total_count": 0,
  "next_cursor": null
}

Pagination

This endpoint uses cursor-based pagination.

1. Omit cursor on the first request
2. If next_cursor is not null, pass its value as cursor on the next request
3. Repeat until next_cursor is null

Error Responses

Status	Description
400	Invalid query parameters (e.g. unknown sort_by value)
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Related Endpoints

• Get App — Full profile for a specific app
• Update App — Update favorite, approved, or license count
• List Catalog Apps — Browse the shared catalog (not scoped to a client)