Versions API

Manage product versions with the Versions API. Track version releases, development status, and release notes. Ideal for CI/CD automation.

Endpoints

GET/v1/products/:id_or_slug/versions

List versions

Returns a list of versions for a product.

POST/v1/products/:id_or_slug/versions

Create version

Creates a new version entry.

GET/v1/products/:id_or_slug/versions/:id

Retrieve a version

Retrieves the details of a version.

Version Object

The version object represents a product version with its status and release information.

Attribute	Type	Description
`id`	string	Unique identifier for the version (e.g., ver_abc123)
`productId`	string	ID of the associated product
`version`	string	Version number in semver format (e.g., 1.2.0), without 'v' prefix
`goal`	string \| null	Version goal or objective
`status`	string	Version status: PLANNED, DEV, TESTING, RELEASED
`releaseNotes`	string \| null	Release notes for the version
`plannedAt`	string \| null	Planned release date in ISO 8601 format
`releasedAt`	string \| null	Actual release date in ISO 8601 format
`createdAt`	string	ISO 8601 timestamp of creation
`updatedAt`	string	ISO 8601 timestamp of last update

Version Statuses

The status indicates the current state of the version in its lifecycle.

Attribute	Type	Description
`PLANNED`	string	Version is planned but not yet started
`DEV`	string	Version is currently in development
`TESTING`	string	Version is in testing/QA phase
`RELEASED`	string	Version has been released to production

GET

List Versions

Returns a list of versions for a specific product. Results are ordered by creation date (newest first).

Request

Bash

curl https://api.myopcs.com/api/v1/products/prod_abc123/versions \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: PLANNED, DEV, TESTING, RELEASED

Response

{}JSON

{
  "data": [
    {
      "id": "ver_abc123",
      "productId": "prod_abc123",
      "version": "1.2.0",
      "goal": "Add dark mode and improve performance",
      "status": "RELEASED",
      "releaseNotes": "This release includes dark mode support and various performance improvements.",
      "plannedAt": "2024-01-15T00:00:00Z",
      "releasedAt": "2024-01-20T14:30:00Z",
      "createdAt": "2024-01-10T09:00:00Z",
      "updatedAt": "2024-01-20T14:30:00Z"
    },
    {
      "id": "ver_def456",
      "productId": "prod_abc123",
      "version": "1.3.0",
      "goal": "API v2 and webhooks",
      "status": "DEV",
      "releaseNotes": null,
      "plannedAt": "2024-02-15T00:00:00Z",
      "releasedAt": null,
      "createdAt": "2024-01-18T11:00:00Z",
      "updatedAt": "2024-01-25T10:00:00Z"
    }
  ]
}

POST

Create Version

Creates a new version for a product. The version number must be unique within the product. Use this endpoint in your CI/CD pipeline to automatically record version releases.

Request

Bash

curl -X POST https://api.myopcs.com/api/v1/products/prod_abc123/versions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.4.0",
    "goal": "Add export functionality",
    "status": "RELEASED",
    "releasedAt": "2024-01-25",
    "releaseNotes": "Added CSV and PDF export for all reports."
  }'

Body Parameters

Parameter	Type	Required	Description
`version`	string	Yes	Version number in semver format (e.g., 1.2.0). 'v' prefix will be stripped automatically.
`goal`	string	No	Version goal or objective
`status`	string	No	Version status: PLANNED (default), DEV, TESTING, RELEASED
`plannedAt`	string	No	Planned release date in YYYY-MM-DD format
`releasedAt`	string	No	Actual release date in YYYY-MM-DD format (use when status is RELEASED)
`releaseNotes`	string	No	Release notes for the version

Response

{}JSON

{
  "data": {
    "id": "ver_new123",
    "productId": "prod_abc123",
    "version": "1.4.0",
    "goal": "Add export functionality",
    "status": "RELEASED",
    "releaseNotes": "Added CSV and PDF export for all reports.",
    "plannedAt": null,
    "releasedAt": "2024-01-25T00:00:00Z",
    "createdAt": "2024-01-25T16:00:00Z",
    "updatedAt": "2024-01-25T16:00:00Z"
  }
}

GET

Retrieve a Version

Retrieves the details of an existing version by its ID.

Request

Bash

curl https://api.myopcs.com/api/v1/products/prod_abc123/versions/ver_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{}JSON

{
  "data": {
    "id": "ver_abc123",
    "productId": "prod_abc123",
    "version": "1.2.0",
    "goal": "Add dark mode and improve performance",
    "status": "RELEASED",
    "releaseNotes": "This release includes dark mode support and various performance improvements.",
    "plannedAt": "2024-01-15T00:00:00Z",
    "releasedAt": "2024-01-20T14:30:00Z",
    "createdAt": "2024-01-10T09:00:00Z",
    "updatedAt": "2024-01-20T14:30:00Z"
  }
}