`GET /api/v1/apps` returns the apps your Orbit API token can read, in a `data` array.

This reference covers the list operation in the [Orbit API specification](https://api.orbitapps.io/openapi.json). For the project model, read [Apps](/concepts/apps).

## Request

Send the request to `https://api.orbitapps.io/api/v1/apps`. The API uses bearer authentication.

```sh
curl 'https://api.orbitapps.io/api/v1/apps' \
  -H "Authorization: Bearer $ORBIT_API_TOKEN"
```

Set `ORBIT_API_TOKEN` to your API token before you run this example. Keep the token private.

### Query parameter

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `org_id` | UUID | No | Restricts the result to apps in one organization. |

For example, to request apps in one organization:

```sh
curl "https://api.orbitapps.io/api/v1/apps?org_id=$ORBIT_ORG_ID" \
  -H "Authorization: Bearer $ORBIT_API_TOKEN"
```

Set `ORBIT_ORG_ID` to the actual organization UUID. Do not use an organization name in its place.

## Access rules

- A profile-scoped token can list apps across organizations where the caller has an active membership.
- An organization-scoped token lists apps only within its bound organization.
- An `org_id` the caller cannot access returns an empty `data` array, not an HTTP `403` response.

An empty result does not prove that an organization has no apps. Check which organization the token can access.

## Successful response

An HTTP `200` response contains a `data` array of app objects. Version 1 returns the entire visible set. The specification does not define pagination parameters for this operation.

An empty result has this shape:

```json
{"data": []}
```

Each app object has these fields:

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | UUID | Stable app identifier. Use this value in API paths that require an app ID. |
| `org_id` | UUID | Organization that owns the app. The API cannot transfer an app to another organization. |
| `slug` | String | Organization-unique identifier with 1 to 60 lowercase letters, digits, or hyphens. |
| `title` | String | Name shown in the interface, with 1 to 200 characters. |
| `description` | String or null | Optional short description. |
| `idea_id` | UUID or null | Linked idea identifier when an idea provided the app's starting point. |
| `icon` | String or null | Single emoji shown beside the title. The default is ✨. |
| `archived` | Boolean | Whether the app is archived. Version 1 does not expose archive or delete operations. |
| `settings` | Object or null | App settings. Treat this map as opaque rather than infer rules from its contents. |
| `themes` | Object or null | Theme catalog with `active` and `definitions` values. |
| `locales` | Object or null | Language configuration with `active`, `available`, and `glossary` values. |
| `created_at` | String | RFC 3339 creation timestamp. Updates do not change this value. |
| `updated_at` | String | RFC 3339 timestamp of the latest update. |

All fields in the table appear in each app object. A field marked as nullable can contain `null`.

## Use the result

For an example app named `Team tasks`, find the object whose `title` matches that name. Use that object's `id` for later app requests. The title and slug are not substitutes for the UUID.

The `locales` value describes configured languages, not translation progress. Translation information has a separate endpoint: `GET /api/v1/apps/{app_id}/translations`.

If you need to create a project rather than list projects, [build your first app](/get-started/build-your-first-app).