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

# List prompt lifecycle versions

> List prompt drafts and published versions with stale-draft and current-publication metadata.

Returns lifecycle metadata, not full prompt content. Use [Get prompt draft version](https://docs.usefini.com/en/api-reference/get-prompt-draft-version.md) to fetch the stored arrays for a specific version.

The response is an object with `versions` and `currentPublishedVersionId`, not the legacy history array. `isStale` is true for a draft whose non-null parent differs from the current published version. If no lifecycle versions exist yet, this read may initialize the current prompt's version history.

## Headers

**Authorization** `string` *required*

Bearer token containing your Fini workspace API key. Format: `Bearer fini_...` The key needs `read` scope.

## Path parameters

**id** `string` *required*

Agent ID.

## Response

**versions** `object[]`

Version IDs, numbers, status, creation/publication metadata, isCurrentPublished, and isStale. An agent without versions can return an empty list.

**currentPublishedVersionId** `string | null`

ID of the current published lifecycle version, or null.

```bash cURL theme={null}
curl --request GET \
  --url 'https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public' \
  --header 'Authorization: Bearer fini_your_api_key'
```

```javascript Node.js theme={null}
const response = await fetch('https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public', {
  method: 'GET',
  headers: { Authorization: 'Bearer fini_your_api_key' }
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
```

```python Python theme={null}
import requests

response = requests.get(
    "https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-prompt/versions/public",
    headers={"Authorization": "Bearer fini_your_api_key"},
)
response.raise_for_status()
data = response.json()
```

```json 200 OK theme={null}
{
  "versions": [
    {
      "id": "9c59b2df-5d5f-4c9e-a070-9ac3c2b1b24e",
      "versionNumber": 12,
      "status": "DRAFT",
      "createdAt": "2026-10-29T12:00:00.000Z",
      "createdBy": null,
      "publishedAt": null,
      "isCurrentPublished": false,
      "isStale": false
    }
  ],
  "currentPublishedVersionId": null
}
```

## Errors

Invalid agent IDs are rejected. The agent must belong to the API key's workspace.

All requests can return 401 for an invalid or revoked key, or 403 when the required scope is missing.


## Related topics

- [API overview](https://docs.usefini.com/en/api-reference/overview.md)
- [Restore prompt version as draft](https://docs.usefini.com/en/api-reference/restore-prompt-version-as-draft.md)
- [Publish prompt draft version](https://docs.usefini.com/en/api-reference/publish-prompt-draft-version.md)


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