T
testing
API Reference: Core Documentation Managing Documentation Structure via API

Manage your entire documentation lifecycle programmatically using the GitDocAI API. Whether you are building a custom dashboard, automating imports, or syncing content from external sources, these endpoints allow you to create documentation projects and organize their internal hierarchies (pages and folders) exactly how you want them.

Understanding the Hierarchy

Before using the API, it helps to understand how GitDocAI structures documentation. Every piece of content lives within a strict hierarchy:

flowchart TD
    Org["Organization"] --> Doc["Documentation Project"]
    Doc --> Ver["Version"]
    Ver --> Sec["Section"]
    Sec --> Ent1["Doc Entry (Folder)"]
    Sec --> Ent2["Doc Entry (Page)"]
    Ent1 --> Ent3["Doc Entry (Sub-page)"]

What is a Doc Entry? An "entry" is the core building block of your documentation. It can represent either a readable page or a folder used to group other pages together.

Managing Documentation Projects

A "Documentation Project" is the top-level container for your site. Use these endpoints to create, configure, and delete projects within your organization.

ActionMethodEndpoint
CreatePOST/v1/documentation/{organization_id}
List allGET/v1/documentation/{organization_id}/list
Get detailsGET/v1/documentation/{organization_id}/{documentation_id}
Update detailsPUT/v1/documentation/{organization_id}/{documentation_id}
Update configPUT/v1/documentation/{organization_id}/{documentation_id}/config
DeleteDELETE/v1/documentation/{organization_id}/{documentation_id}

Initializing a New Project

When you first create a documentation project, it starts in a "pending" state. You must initialize it with content before it can be published or edited. GitDocAI provides several powerful initialization endpoints depending on your source material.

All initialization endpoints use the POST method and share the base path:
/v1/documentation/{organization_id}/{documentation_id}

Source MaterialEndpoint PathDescription
Blank/initialize-blankStarts a fresh project with a default scaffold.
AI Prompt/initialize-from-aiGenerates a complete structure based on a text prompt.
OpenAPI/initialize-from-openapiBuilds API reference docs from a Swagger/OpenAPI spec.
GitHub/initialize-from-repositoryImports markdown files directly from a linked repository.
Files/initialize-from-fileUploads and parses a local directory or ZIP file.
Website/initialize-from-websiteCrawls an existing website to migrate its content.
Template/initialize-from-templateUses a pre-configured GitDocAI template.

Managing Entries (Pages & Folders)

Once your documentation is initialized, you can manipulate the individual pages and folders (entries) within a specific section.

All entry endpoints share this base path:
/v1/documentation/{organization_id}/{documentation_id}/version/{version_id}/section/{section_id}/entry

Retrieving Content

ActionMethodPathEffect
List entriesGET/Returns a flat list of all entries in the section.
Get treeGET/treeReturns entries nested in their folder hierarchy.
Get by IDGET/{entry_id}Retrieves metadata and content for a specific entry.

Use the /tree endpoint when you need to render a sidebar navigation menu. It automatically nests child pages under their respective parent folders, saving you from having to reconstruct the hierarchy on the client side.

Modifying Content

ActionMethodPathEffect
Create entryPOST/Creates a single new page or folder.
Batch createPOST/batchCreates multiple entries in a single request.
Update entryPUT/{entry_id}Updates an entry's title, content, or metadata.
Delete entryDELETE/{entry_id}Removes an entry (and its children, if it's a folder).

Organizing the Hierarchy

ActionMethodPathEffect
ReorderPOST/reorderUpdates the display order of entries within a folder.
MovePOST/{entry_id}/moveMoves an entry to a different parent folder or section.

Moving a parent folder automatically moves all of its child entries. Ensure you update any hardcoded links in your application that might point to the old paths.

Managing Documentation Backups

GitDocAI allows you to safeguard your projects by creating backups and restoring them when necessary. You can also configure a specific external repository to store these backups.

All backup endpoints share this base path:
/v1/documentation/{organization_id}/{documentation_id}/backup

ActionMethodPathEffect
List backupsGET/Lists all available backups for the documentation project.
Create backupPOST/Makes a new backup of the documentation.
Get repositoryGET/repositoryRetrieves the configured backup repository.
Set repositoryPUT/repositorySets the repository used for storing backups.
RestorePOST/restoreRestores the documentation from a previous backup.

Example Workflow: Creating a New API Reference

Here is how you might combine these endpoints to programmatically generate a new set of API documentation:

  1. 1

    Create the project container

    Make a POST request to /v1/documentation/{organization_id} to create the empty documentation shell. Save the returned documentation_id.

  2. 2

    Initialize from OpenAPI

    Make a POST request to /initialize-from-openapi, passing your documentation_id and the URL to your Swagger file. GitDocAI will parse the spec and generate the initial pages.

  3. 3

    Add a custom welcome page

    Make a POST request to the /entry endpoint to create a new "Welcome" page at the root of your new documentation section.

  4. 4

    Reorder the navigation

    Make a POST request to /entry/reorder to ensure your new "Welcome" page appears at the very top of the sidebar, above the generated API routes.