Using Backup Services via API

Manage your documentation's lifecycle programmatically using our advanced API endpoints. Whether you are initializing a new project from scratch or setting up automated backups to a remote repository, these endpoints give you full control over your data.

Documentation Lifecycle

flowchart TD
    A[Initialize Documentation] --> B[Configure Backup Repository]
    B --> C[Create Backup]
    C --> D[List Backups]
    C --> E[Restore Documentation]

Initializing Documentation

Before you can back up a documentation project, it must be initialized. We offer several endpoints to scaffold your documentation based on your starting point. All initialization requests are made via POST to the base URL:

https://api.gitdocai.com/v1/documentation/{organization_id}/{documentation_id}

Method	Endpoint Suffix	Description
`POST`	`/initialize-blank`	Creates a pending documentation project with a default scaffold.
`POST`	`/initialize-from-template`	Starts a project using a pre-configured preset template.
`POST`	`/initialize-from-ai`	Generates initial documentation structure and content from an AI prompt.
`POST`	`/initialize-from-openapi`	Imports an OpenAPI/Swagger specification to generate API reference docs.
`POST`	`/initialize-from-repository`	Pulls existing markdown files directly from a connected GitHub repository.
`POST`	`/initialize-from-file`	Initializes the project by uploading local files.
`POST`	`/initialize-from-website`	Scrapes and imports content from an existing website URL.

If you already have existing documentation, we recommend using the /initialize-from-repository or /initialize-from-openapi endpoints to get up and running quickly.

Configuring Backup Repositories

To ensure your documentation is safely stored, you can configure a dedicated backup repository. This tells the system where to send your backup data when a backup is triggered.

Set the backup repository

Use the PUT method to define where your backups should be stored.

curl -X PUT https://api.gitdocai.com/v1/documentation/{organization_id}/{documentation_id}/backup/repository 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"repository_url": "https://github.com/your-org/docs-backup"}'

Verify the configuration

You can confirm your settings at any time by retrieving the current configuration using a GET request to the same endpoint.

curl -X GET https://api.gitdocai.com/v1/documentation/{organization_id}/{documentation_id}/backup/repository 
  -H "Authorization: Bearer YOUR_API_TOKEN"

Creating and Managing Backups

Once your repository is configured, you can create backups on demand and view your backup history.

Trigger a Backup

To create a new backup of your current documentation state, send a POST request:

curl -X POST https://api.gitdocai.com/v1/documentation/{organization_id}/{documentation_id}/backup 
  -H "Authorization: Bearer YOUR_API_TOKEN"

Depending on the size of your documentation project, the backup process may take a few moments to complete.

List Existing Backups

To view a history of all backups for a specific documentation project, use the GET method:

curl -X GET https://api.gitdocai.com/v1/documentation/{organization_id}/{documentation_id}/backup 
  -H "Authorization: Bearer YOUR_API_TOKEN"

This endpoint returns a list of backup records, including their unique IDs and timestamps, which you will need if you ever want to restore your data.

Restoring Documentation

If you need to roll back changes or recover lost data, you can restore your documentation from a previous backup.

To initiate a restore, you will need the specific backup ID retrieved from the list endpoint.

curl -X POST https://api.gitdocai.com/v1/documentation/{organization_id}/{documentation_id}/backup/restore 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"backup_id": "your-backup-uuid"}'

Restoring from a backup will overwrite the current state of your documentation. Make sure to verify the backup_id before executing this command to avoid accidental data loss.

Managing Assets

In addition to backups, you can programmatically manage the assets (such as images and downloadable files) associated with your documentation project. These endpoints append to the standard v1/documentation/{organization_id}/{documentation_id} base URL.

Method	Endpoint Suffix	Description
`GET`	`/asset`	Get all assets for a documentation project.
`POST`	`/asset`	Upload a new asset.
`GET`	`/asset/{asset_id}`	Get a specific asset by its ID.
`PUT`	`/asset/{asset_id}`	Update an asset's metadata.
`DELETE`	`/asset/{asset_id}`	Delete an asset.
`GET`	`/asset/{asset_id}/file`	Serve the actual asset file.

AI Image Generation

You can also generate images for your documentation using our AI integration endpoint.

Method	Endpoint Suffix	Description
`POST`	`/ai/generate-image`	Generates an image from an AI prompt. (Note: This endpoint omits the `/v1` prefix in its path).

Frequently Asked Questions

Currently, the API supports on-demand backups via the POST endpoint. To automate this, you can set up a cron job or a scheduled CI/CD pipeline step that calls the backup endpoint at your preferred intervals.

A backup includes all markdown content, configuration files, and assets associated with that specific documentation project at the time the backup was triggered.

Next Steps

api

API Reference

Explore the complete list of available API endpoints and parameters.

Authentication

Learn how to generate and manage your API tokens securely.