> ## 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.

# Competitors

> List, add, and remove competitor apps for any app in your tracked list

Track competitor apps against each of your tracked apps. Competitors are displayed on the **Competitors** tab in the appeeky.com dashboard.

<Info>
  All Competitor endpoints cost **0 credits** and require the `apps:read` scope for reads and `apps:write` for writes.
</Info>

***

## List Competitors

```
GET /v1/user/apps/:appId/competitors
```

Returns all competitor apps tracked for a given app.

**Path Parameters:**

| Name    | Type   | Description                              |
| ------- | ------ | ---------------------------------------- |
| `appId` | number | Numeric App Store ID of your tracked app |

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/user/apps/6443843426/competitors" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/user/apps/6443843426/competitors",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  res = requests.get(
      "https://api.appeeky.com/v1/user/apps/6443843426/competitors",
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**Response (200 OK):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "a4b1d302-...",
      "competitor_app_id": 1547223625,
      "competitor_name": "Voice Tape Record",
      "competitor_icon_url": "https://...",
      "created_at": "2026-03-19T15:47:06.270736+00:00"
    }
  ]
}
```

***

## Add a Competitor

```
POST /v1/user/apps/:appId/competitors
```

Add a competitor app by its numeric App Store ID.

**Path Parameters:**

| Name    | Type   | Description                              |
| ------- | ------ | ---------------------------------------- |
| `appId` | number | Numeric App Store ID of your tracked app |

**Request Body:**

| Field             | Type   | Required | Description                            |
| ----------------- | ------ | -------- | -------------------------------------- |
| `competitorAppId` | number | Yes      | Numeric App Store ID of the competitor |
| `competitorName`  | string | No       | Display name for the competitor        |

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.appeeky.com/v1/user/apps/6443843426/competitors" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"competitorAppId": 1547223625, "competitorName": "Sensor Tower"}'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/user/apps/6443843426/competitors",
    {
      method: "POST",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ competitorAppId: 1547223625, competitorName: "Sensor Tower" }),
    }
  );
  const { data } = await res.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  res = requests.post(
      "https://api.appeeky.com/v1/user/apps/6443843426/competitors",
      headers={"X-API-Key": "YOUR_API_KEY"},
      json={"competitorAppId": 1547223625, "competitorName": "Sensor Tower"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**Response (201 Created):** Returns the created competitor row.

***

## Remove a Competitor

```
DELETE /v1/user/apps/:appId/competitors/:competitorAppId
```

Remove a competitor from a tracked app.

**Path Parameters:**

| Name              | Type   | Description                                      |
| ----------------- | ------ | ------------------------------------------------ |
| `appId`           | number | Numeric App Store ID of your tracked app         |
| `competitorAppId` | number | Numeric App Store ID of the competitor to remove |

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X DELETE "https://api.appeeky.com/v1/user/apps/6443843426/competitors/1547223625" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/user/apps/6443843426/competitors/1547223625",
    { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  requests.delete(
      "https://api.appeeky.com/v1/user/apps/6443843426/competitors/1547223625",
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  ```
</CodeGroup>

**Response (200 OK):**

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

***

## Errors

| Status | Code                 | When                                         |
| ------ | -------------------- | -------------------------------------------- |
| 400    | `BAD_REQUEST`        | `appId` or `competitorAppId` is not a number |
| 403    | `FORBIDDEN`          | Key scope does not allow this operation      |
| 404    | `USER_APP_NOT_FOUND` | `appId` is not in your tracked list          |
| 404    | `NOT_FOUND`          | Competitor not found                         |
| 409    | `DUPLICATE`          | Competitor already tracked for this app      |