> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Play CLI REST API

> Call any hosted gps operation over HTTP with your Appeeky API key.

The hosted server exposes the same operations as the MCP tools over plain HTTP, for scripts and backends that do not speak MCP.

```
Base URL: https://gps-api.appeeky.com
```

## Endpoints

| Method | Path | Description |
| - | - | - |
| `GET` | `/v1/apps` | Apps the connected service account can use |
| `GET` | `/v1/ops` | Operations you can run (`name`, `group`, `summary`, `write`) |
| `POST` | `/v1/ops/{name}` | Run one operation; the JSON body holds its arguments |
| `POST` | `/mcp` | Remote MCP (streamable HTTP, stateless) |
| `GET` | `/health` | Liveness |

Authenticate with `Authorization: Bearer <key>` or `X-API-Key: <key>`, using your [Appeeky API key](/docs/authentication.md). Request bodies are limited to 1 MB.

## List apps

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://gps-api.appeeky.com/v1/apps \
  -H "Authorization: Bearer $APPEEKY_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "serviceAccountEmail": "play@my-project.iam.gserviceaccount.com",
    "defaultPackageName": "com.example.app",
    "apps": [{ "packageName": "com.example.app", "displayName": "My App" }],
    "note": "Apps the connected service account was last seen with in Appeeky. ..."
  }
}
```

## List operations

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://gps-api.appeeky.com/v1/ops \
  -H "Authorization: Bearer $APPEEKY_API_KEY"
```

Write operations appear only when the request carries `X-GPS-Allow-Writes: true`.

## Run an operation

```bash Read theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://gps-api.appeeky.com/v1/ops/gps_list_tracks \
  -H "Authorization: Bearer $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"packageName":"com.example.app"}'
```

```bash Write theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://gps-api.appeeky.com/v1/ops/gps_reply_to_review \
  -H "Authorization: Bearer $APPEEKY_API_KEY" \
  -H "X-GPS-Allow-Writes: true" \
  -H "Content-Type: application/json" \
  -d '{"packageName":"com.example.app","reviewId":"REVIEW_ID","replyText":"Thanks!"}'
```

Successful calls return the Google Play response under `data`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "data": { "...": "..." } }
```

Operation names and arguments match the [MCP tools](/docs/store-cli-google-play-mcp-tools.md) and the [operations reference](https://gps.appeeky.com/reference/operations).

## Errors

Errors have one shape:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "error": { "code": "WRITES_DISABLED", "message": "gps_update_rollout changes your Play Console. Send X-GPS-Allow-Writes: true to run it." } }
```

| Status | Code | Meaning |
| - | - | - |
| 400 | `INVALID_JSON` | Body is not JSON |
| 400 | `INVALID_ARGS` | Arguments failed validation (see `details`) |
| 401 | `MISSING_API_KEY` | No Appeeky key on the request |
| 403 | `WRITES_DISABLED` | A write without `X-GPS-Allow-Writes: true` |
| 404 | `UNKNOWN_OPERATION` | Unknown operation, or a CLI-only one (uploads, downloads, local accounts) |
| 404 | `NOT_FOUND` | Unknown path or method |
| 405 | `METHOD_NOT_ALLOWED` | `/mcp` called with anything but `POST` |
| 413 | `BODY_TOO_LARGE` | Body over 1 MB |
| 502 | `GOOGLE_PLAY_ERROR` | Google refused the call; the message carries Google's error |
| 503 | `APPEEKY_UNREACHABLE` | Appeeky could not be reached; retry shortly |

Refusals from Appeeky (invalid key, no Google Play connection, credits used up) come back with Appeeky's status and code.

## Credits

Each `POST /v1/ops/{name}` and `GET /v1/apps` opens one Appeeky session, which is one metered API call. `GET /v1/ops` is free, and arguments are validated before the session opens, so a rejected call costs nothing. See [Rate Limits & Credits](/docs/rate-limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.