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

# Metadata Versions

> Create, update, and release versioned ASO metadata for your apps

Store and version your App Store metadata — title, subtitle, description, and keywords — directly through the API. Versions appear in the **Versions** tab of the appeeky.com dashboard.

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

***

## List Versions

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

Returns all saved metadata versions for an app, ordered newest first.

**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/versions" \
    -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/versions",
    { 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/versions",
      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": "b5c2e891-...",
      "version_name": "v2.1 Spring",
      "title": "Appeeky – ASO Intelligence",
      "subtitle": "Keyword & Rank Tracker",
      "description": "Track your keywords and grow your App Store rank...",
      "keywords": "aso, keyword tracker, app store optimization",
      "language": "en-US",
      "is_released": false,
      "released_at": null,
      "created_at": "2026-03-19T15:47:06.270736+00:00"
    }
  ]
}
```

***

## Create a Version

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

Save a new set of metadata as a named version.

**Path Parameters:**

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

**Request Body:**

| Field         | Type   | Required | Description                                     |
| ------------- | ------ | -------- | ----------------------------------------------- |
| `versionName` | string | Yes      | A label for this version (e.g. `"v2.1 Spring"`) |
| `title`       | string | No       | App title (max 30 chars for App Store)          |
| `subtitle`    | string | No       | App subtitle (max 30 chars)                     |
| `description` | string | No       | Full app description                            |
| `keywords`    | string | No       | Comma-separated keyword field                   |
| `language`    | string | No       | Locale code (default: `"en-US"`)                |

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.appeeky.com/v1/user/apps/6443843426/versions" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "versionName": "v2.1 Spring",
      "title": "Appeeky – ASO Intelligence",
      "subtitle": "Keyword & Rank Tracker",
      "keywords": "aso, keyword tracker, app store optimization",
      "language": "en-US"
    }'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/user/apps/6443843426/versions",
    {
      method: "POST",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        versionName: "v2.1 Spring",
        title: "Appeeky – ASO Intelligence",
        subtitle: "Keyword & Rank Tracker",
        keywords: "aso, keyword tracker, app store optimization",
        language: "en-US",
      }),
    }
  );
  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/versions",
      headers={"X-API-Key": "YOUR_API_KEY"},
      json={
          "versionName": "v2.1 Spring",
          "title": "Appeeky – ASO Intelligence",
          "subtitle": "Keyword & Rank Tracker",
          "keywords": "aso, keyword tracker, app store optimization",
          "language": "en-US",
      },
  )
  data = res.json()["data"]
  ```
</CodeGroup>

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

***

## Update a Version

```
PATCH /v1/user/apps/:appId/versions/:versionId
```

Update any metadata field on an existing version. Only include the fields you want to change.

**Path Parameters:**

| Name        | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| `appId`     | number | Numeric App Store ID of your tracked app |
| `versionId` | string | UUID of the version to update            |

**Request Body:** Same optional fields as Create (all optional).

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X PATCH "https://api.appeeky.com/v1/user/apps/6443843426/versions/b5c2e891-..." \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"keywords": "aso tool, keyword rank, app growth"}'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/user/apps/6443843426/versions/b5c2e891-...",
    {
      method: "PATCH",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ keywords: "aso tool, keyword rank, app growth" }),
    }
  );
  ```

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

  requests.patch(
      "https://api.appeeky.com/v1/user/apps/6443843426/versions/b5c2e891-...",
      headers={"X-API-Key": "YOUR_API_KEY"},
      json={"keywords": "aso tool, keyword rank, app growth"},
  )
  ```
</CodeGroup>

**Response (200 OK):** Returns the updated version row.

***

## Mark a Version as Released

```
POST /v1/user/apps/:appId/versions/:versionId/release
```

Mark a metadata version as the currently released version. Sets `is_released = true` and records a `released_at` timestamp.

**Path Parameters:**

| Name        | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| `appId`     | number | Numeric App Store ID of your tracked app |
| `versionId` | string | UUID of the version to mark as released  |

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.appeeky.com/v1/user/apps/6443843426/versions/b5c2e891-.../release" \
    -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/versions/b5c2e891-.../release",
    { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  ```

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

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

**Response (200 OK):** Returns the updated version row with `is_released: true`.

***

## Errors

| Status | Code                 | When                                                     |
| ------ | -------------------- | -------------------------------------------------------- |
| 400    | `BAD_REQUEST`        | `versionName` missing on create, or `appId` 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`          | Version not found                                        |