Manage your documentation's lifecycle programmatically using the GitDocAI API. This guide covers how to create and manage versions, organize content into sections, and trigger automated publishing workflows.

Documentation Lifecycle

The typical flow for managing documentation via the API involves creating a version, populating it with sections, and then publishing the changes.

flowchart TD
    A["Create Version"] --> B["Create Sections"]
    B --> C["Reorder Sections"]
    C --> D["Trigger Publish Job"]
    D --> E["Monitor Publish Status"]

Managing Versions

Versions allow you to maintain multiple iterations of your documentation (e.g., v1.0, v2.0, beta). All version endpoints are scoped to an organization and a specific documentation project.

Core Version Endpoints

Version States

You can programmatically control the lifecycle state of a version using dedicated endpoints. This is useful for automating release pipelines.

Managing Sections

Sections act as the organizational folders or categories within a specific documentation version.

Core Section Endpoints

Advanced Section Management

Beyond basic CRUD operations, the API provides endpoints for organizing and verifying your sections:

• Reorder Sections (POST .../section/reorder): Update the display order of sections within the navigation menu.

• Get Source Summary (GET .../section/{section_id}/source): Retrieve a source-of-truth summary for a specific section, which is helpful for auditing content synchronization.

Managing Assets and Files

You can also manage file resources and import assets directly via the API to support your documentation content.

Accessing Changelogs

If your documentation includes automated changelogs, you can retrieve them using the tasks endpoints.

Publishing Workflows

Once your versions and sections are configured, you need to publish the documentation to make the changes live. Publishing is handled asynchronously via a job queue.

1. 1

   Start a publish job

   Trigger a new build and publish process for your documentation.

   curl -X POST https://api.gitdocai.com/documentations/{documentation_id}/publish 
     -H "Authorization: Bearer $YOUR_API_TOKEN"

2. 2

   Monitor job status

   Because publishing happens asynchronously, use the status endpoint to poll for completion.

   curl https://api.gitdocai.com/documentations/{documentation_id}/publish/status 
     -H "Authorization: Bearer $YOUR_API_TOKEN"

3. 3

   Review publish history

   You can audit past publish jobs or retrieve the details of the most recent successful deployment.

   • Get publish history: GET /documentations/{documentation_id}/publish/history

   • Get latest publish: GET /documentations/{documentation_id}/publish/latest