T
testing
API Reference: Core Documentation Managing Versioning States via API

Manage the lifecycle of your documentation versions programmatically using the GitDocAI API. These endpoints allow you to create new versions, organize their sections, and control their visibility states such as marking them as default, latest, or deprecated.

Before interacting with these endpoints, ensure you have your organization_id and documentation_id handy, as they are required path parameters for almost all versioning requests.

Version Lifecycle

Documentation versions typically move through several states as they are drafted, published, and eventually retired.

stateDiagram-v2
    [*] --> Draft: Create Version
    Draft --> Latest: set-latest
    Latest --> Default: set-default
    Default --> Deprecated: set-deprecated
    Deprecated --> [*]: Delete Version

Managing Version States

Controlling which version your users see is critical for maintaining accurate documentation. Use the following endpoints to update the state of a specific version.

ActionMethodEndpointDescription
Set DefaultPOST/v1/documentation/{organization_id}/{documentation_id}/version/{version_id}/set-defaultSets the version as the primary documentation loaded by default.
Set LatestPOST/v1/documentation/{organization_id}/{documentation_id}/version/{version_id}/set-latestMarks the version as the most recent release.
Set DeprecatedPOST/v1/documentation/{organization_id}/{documentation_id}/version/{version_id}/set-deprecatedFlags the version as outdated, usually displaying a warning to users.

Example: Setting a version as default

curl -X POST "https://api.gitdocai.com/v1/documentation/org_123/doc_456/version/ver_789/set-default" 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json"

Deprecating a version that is currently set as your Default may cause your documentation site to display warnings to all incoming visitors. Always set a new default version before deprecating an old one.

Core Version Operations

If you are building custom tooling or migrating from another platform, you can perform standard CRUD (Create, Read, Update, Delete) operations on your documentation versions.

OperationMethodEndpoint
List versionsGET/v1/documentation/{organization_id}/{documentation_id}/version
Create versionPOST/v1/documentation/{organization_id}/{documentation_id}/version
Get version detailsGET/v1/documentation/{organization_id}/{documentation_id}/version/{version_id}
Update versionPUT/v1/documentation/{organization_id}/{documentation_id}/version/{version_id}
Delete versionDELETE/v1/documentation/{organization_id}/{documentation_id}/version/{version_id}

Typical Versioning Workflow

If you are automating your documentation releases (for example, via CI/CD), you will typically follow this sequence:

  1. 1

    Create a new version

    Call POST /v1/documentation/{organization_id}/{documentation_id}/version to initialize a new version container (e.g., "v2.0").

  2. 2

    Populate sections

    Use the Section endpoints (like POST /v1/documentation/.../version/{version_id}/section) to create and reorder the content hierarchy for this specific version.

  3. 3

    Publish the documentation

    Trigger a publish job using POST /documentations/{documentation_id}/publish to build the new version. You can check the status at /documentations/{documentation_id}/publish/status.

  4. 4

    Update version states

    Once published successfully, call the set-latest and set-default endpoints to route your users to the new content.

Managing Sections within a Version

Every version is made up of Sections (folders and pages). The API provides granular control over the content structure of any given version.

View Section Endpoints

Use these endpoints to manage the content hierarchy within a specific {version_id}:

  • GET .../version/{version_id}/section — List all sections

  • POST .../version/{version_id}/section — Create a new section

  • GET .../version/{version_id}/section/{section_id} — Get section details

  • PUT .../version/{version_id}/section/{section_id} — Update a section

  • DELETE .../version/{version_id}/section/{section_id} — Remove a section

  • POST .../version/{version_id}/section/reorder — Reorder sections in the sidebar

  • GET .../version/{version_id}/section/{section_id}/source — Retrieve the source-of-truth summary for a section

Changes made to sections within a draft version will not be visible to your end-users until you trigger a new publish job for that documentation.