Add Favorites

POST /clients/{client_id}/apps/favorites

Add one or more apps to the client's favorites list. This operation is idempotent -- adding an already-favorited app is treated as a success.

Path Parameters

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

Request Body

Field	Type	Required	Description
app_ids	string (uuid)[]	Yes	List of app IDs to add to favorites

Example Request Body

{
  "app_ids": [
    "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "g2b3c4d5-e6f7-8901-bcde-f12345678901",
    "h3c4d5e6-f7a8-9012-cdef-234567890123"
  ]
}

Response

Returns status 200 OK with a bulk operation result.

Field	Type	Description
succeeded	string (uuid)[]	App IDs successfully added to favorites (includes already-favorited apps)
failed	object[]	App IDs that failed with error details
failed[].id	string (uuid)	The app ID that failed
failed[].error	string	Reason for the failure

All succeeded

{
  "succeeded": [
    "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "g2b3c4d5-e6f7-8901-bcde-f12345678901"
  ],
  "failed": []
}

Partial success

{
  "succeeded": [
    "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
  ],
  "failed": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "error": "App not found"
    }
  ]
}

Example Request

curl -X POST "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/apps/favorites" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "app_ids": [
      "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "g2b3c4d5-e6f7-8901-bcde-f12345678901"
    ]
  }'

Error Responses

Status	Description
400	Invalid request (missing app_ids, empty array, invalid uuid format)
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Notes

Idempotency

Apps that are already favorited are included in succeeded, not failed. The desired state is achieved regardless of how many times the request is sent.

When to use this vs PATCH

Use this endpoint for multi-select operations (e.g. favoriting 10 apps from a table). Use Update App for single-app toggles from a detail view.

Related Endpoints

• Remove Favorites — Bulk remove apps from favorites
• Update App — Toggle favorite on a single app
• List Apps — Filter by is_favorite status