Appearance

Peer & Flow Versioning ​

Cognipeer keeps version snapshots for Peers and Flows so teams can publish stable configurations, inspect earlier snapshots, and roll back when needed.

Version Model ​

The current versioning model uses two statuses:

  • draft: Editable or unpublished snapshot.
  • published: Snapshot that can be selected as the latest published version.

Peers and Flows keep pointers on the main record:

  • latestPublishedVersion: Version number used as the current published version.
  • currentDraftVersion: Draft version number when a draft exists.

There is no separate active or archived status in the current runtime model. Version tags, compare endpoints, and semantic version names are not part of the current API surface.

What a Version Contains ​

A version stores a snapshot of the Peer or Flow configuration plus audit metadata. List and detail responses can include creator and publisher user metadata when available.

Typical fields include:

json
{
  "entityType": "flow",
  "entityId": "flow_id",
  "version": 3,
  "status": "published",
  "data": {
    "name": "Renewal Workflow",
    "definition": {
      "steps": []
    }
  },
  "audit": {
    "summary": "updated trigger and final output",
    "createdByUser": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  },
  "publishedAt": "2025-10-21T10:00:00.000Z"
}

Flow Draft and Publish ​

Flows expose draft-oriented routes in addition to version routes:

http
POST /v1/flow/:flowId/autosave
POST /v1/flow/:flowId/publish

Autosave updates the current draft snapshot. Publish turns the selected draft/version into a published version and updates latestPublishedVersion.

Listing and Reading Versions ​

Peer versions:

http
GET /v1/peer/:peerId/versions
GET /v1/peer/:peerId/versions/:version

Flow versions:

http
GET /v1/flow/:flowId/versions
GET /v1/flow/:flowId/versions/:version

Optional query parameters on list routes:

  • status: Filter by draft or published.
  • limit: Page size. Defaults to 20.
  • skip: Offset. Defaults to 0.

Publishing a Version ​

Publish an existing version and make it the latest published version:

http
POST /v1/peer/:peerId/versions/:version/publish
POST /v1/flow/:flowId/versions/:version/publish

Response:

json
{
  "success": true,
  "version": 3
}

If the version is already published, the route updates the latest pointer.

Set Latest Published Version ​

Point the base entity to an already published version:

http
POST /v1/peer/:peerId/versions/:version/set-latest
POST /v1/flow/:flowId/versions/:version/set-latest

Only published versions can be set as latest. Draft versions return a validation error.

Roll Back ​

Rollback creates a new version from an older snapshot, publishes that new version, and updates the latest pointer.

http
POST /v1/peer/:peerId/versions/:version/rollback
POST /v1/flow/:flowId/versions/:version/rollback

Response:

json
{
  "success": true,
  "version": 4,
  "published": {
    "version": 4,
    "status": "published"
  }
}

The original version remains in history. Rollback does not delete the current version.

Unpublish and Delete ​

Unpublish converts a published version back to draft and recomputes the latest published pointer:

http
POST /v1/peer/:peerId/versions/:version/unpublish
POST /v1/flow/:flowId/versions/:version/unpublish

Delete removes a draft version:

http
DELETE /v1/peer/:peerId/versions/:version
DELETE /v1/flow/:flowId/versions/:version

Published versions cannot be deleted directly. Unpublish first, then delete the resulting draft if you really want to remove it.

Retention ​

Publishing and rollback enforce configured retention limits. The default retention is read from the runtime configuration, and an entity-specific versionRetention value can override it.

Practical Workflow ​

  1. Work on a draft version.
  2. Test the draft through the editor or a controlled execution path.
  3. Publish the draft when it is ready.
  4. Use set-latest to switch among already published versions when needed.
  5. Use rollback when you need a new published version copied from an older snapshot.

Best Practices ​

  • Keep published versions stable for production integrations.
  • Use clear draft summaries when the UI asks for a change note.
  • Test both the happy path and error branches before publishing a Flow.
  • Prefer rollback over manual reconstruction when reverting to a known-good snapshot.
  • Avoid deleting draft history unless it is noise or accidental work.

Built with VitePress

© 2026 cognipeer. All rights reserved.