# List push projects

`GET /v1/push-projects`

Requires an API key with the `push:read` scope. [About keys and scopes](/docs/api/authentication)

Each project groups the iOS, Android and web apps of one product, with whether any can send (`ready`). Rules that ask whether a contact is reachable by push name a project. Credentials are described, never returned.

## Query parameters

- `limit` (integer, optional, min > 0, max 100, default `20`)
- `cursor` (string, optional, 1–2048 characters)

## Returns

Returns `200 OK` with a list of `PushProject` objects in `data`, and the next page's cursor in `meta` (see [pagination](/docs/api/pagination)). Otherwise returns an error; [Errors](/docs/api/errors) lists every code and which to retry.

- `id` (string, required, uuid)
- `name` (string, required)
- `environment` (string, required, one of `sandbox`, `production`)
- `ready` (boolean, required) — At least one app can send; the others' devices are skipped until they can.
- `installationCount` (integer, required, min -9007199254740991, max 9007199254740991) — Across its apps: devices that can receive now.
- `lastRegisteredAt` (string | null, required, date-time) — Across its apps: when a device last registered; null until the first one.
- `apps` (PushApp[], required)
  - `id` (string, required, uuid)
  - `pushProjectId` (string, required, uuid) — The project the app belongs to.
  - `name` (string, required)
  - `platform` (string, required, one of `ios`, `android`, `web`)
  - `environment` (string, required, one of `sandbox`, `production`)
  - `ready` (boolean, required) — Whether the app can send: web apps, and native apps with a credential Apple or Google has not refused.
  - `credential` (object | null, required) — A native app's credential, without its key. Null until an admin uploads one.
    - One of: **APNs (iOS)**
      - `kind` ("apns", required)
      - `keyId` (string, required)
      - `teamId` (string, required)
      - `bundleId` (string, required)
    - One of: **FCM (Android)**
      - `kind` ("fcm", required)
      - `projectId` (string, required) — The Firebase project ID.
      - `clientEmail` (string, required) — The service account's email.
  - `credentialRefusal` (object | null, required) — Set when Apple or Google refused the credential while sending (a revoked key, a wrong team ID, a service account that lost permission). Sends stop until a new credential is uploaded.
    - `reason` (string, required) — The provider's own explanation.
    - `refusedAt` (string, required, date-time)
  - `vapidPublicKey` (string | null, required) — A web app's public key, passed to the browser when it subscribes; null for native apps.
  - `createdAt` (string, required, date-time)
  - `installationCount` (integer, required, min -9007199254740991, max 9007199254740991) — Devices that can receive now: registered, active, permission granted.
  - `lastRegisteredAt` (string | null, required, date-time) — When a device that can receive last registered or refreshed; null until then.
  - `updatedAt` (string, required, date-time)
- `createdAt` (string, required, date-time)
- `updatedAt` (string, required, date-time)

## Example

```bash
curl https://api.kirora.io/v1/push-projects \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": [
    {
      "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
      "name": "Weekend specials",
      "environment": "sandbox",
      "ready": true,
      "installationCount": -9007199254740991,
      "lastRegisteredAt": "2030-03-14T09:30:00Z",
      "apps": [
        {
          "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
          "pushProjectId": "018f2a4e-6b1c-7d3e-9f40-bc637fbb5a6b",
          "name": "Weekend specials",
          "platform": "ios",
          "environment": "sandbox",
          "ready": true,
          "credential": {
            "kind": null,
            "keyId": null,
            "teamId": null,
            "bundleId": null
          },
          "credentialRefusal": {
            "reason": null,
            "refusedAt": null
          },
          "vapidPublicKey": "vapidPublicKey_example",
          "createdAt": "2030-03-14T09:30:00Z",
          "installationCount": -9007199254740991,
          "lastRegisteredAt": "2030-03-14T09:30:00Z",
          "updatedAt": "2030-03-14T09:30:00Z"
        }
      ],
      "createdAt": "2030-03-14T09:30:00Z",
      "updatedAt": "2030-03-14T09:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    }
  }
}
```