T
testing
Backups & Restorations Managing File Metadata via API

Managing your files (assets) and their metadata programmatically gives you full control over your documentation's resources. Using our API, you can seamlessly upload files, update their associated metadata, and ensure your entire documentation state is safely backed up or restored.

Looking for API Keys?

Before you begin, ensure you have generated an API token from your dashboard to authenticate your requests.

All endpoints on this page require your organization_id and documentation_id. You can find these in your dashboard URL or settings page.

File and Asset Management

Every image, document, or attachment in your documentation is treated as an "Asset". You can manage the metadata for these assets (like alt text, tags, or descriptions) directly through the API.

Asset Endpoints Overview

ActionMethodAPI Endpoint
List all filesGET/v1/documentation/{org_id}/{doc_id}/asset
Upload a filePOST/v1/documentation/{org_id}/{doc_id}/asset
Get file metadataGET/v1/documentation/{org_id}/{doc_id}/asset/{asset_id}
Update metadataPUT/v1/documentation/{org_id}/{doc_id}/asset/{asset_id}
Delete a fileDELETE/v1/documentation/{org_id}/{doc_id}/asset/{asset_id}
Download fileGET/v1/documentation/{org_id}/{doc_id}/asset/{asset_id}/file

Updating File Metadata

Here is a common workflow for finding a file and updating its metadata programmatically.

  1. 1

    Retrieve your assets

    First, list your assets to find the specific asset_id you want to update.

    curl -X GET "https://api.gitdoc.ai/v1/documentation/{organization_id}/{documentation_id}/asset" 
  -H "Authorization: Bearer YOUR_API_TOKEN"
  2. 2

    Update the metadata

    Once you have the asset_id, use a PUT request to update its metadata properties.

    curl -X PUT "https://api.gitdoc.ai/v1/documentation/{organization_id}/{documentation_id}/asset/{asset_id}" 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"metadata": {"alt_text": "Architecture Diagram", "category": "diagrams"}}'
  3. 3

    Verify the update

    You can fetch the specific asset to confirm your metadata was saved successfully.

    curl -X GET "https://api.gitdoc.ai/v1/documentation/{organization_id}/{documentation_id}/asset/{asset_id}" 
  -H "Authorization: Bearer YOUR_API_TOKEN"

If you need to display the actual image or file in a custom frontend, use the /asset/{asset_id}/file endpoint to serve the raw file content rather than the metadata JSON.

AI Image Generation

You can also generate new image assets for your documentation using our AI capabilities.

ActionMethodAPI Endpoint
Generate AI imagePOST/documentation/{org_id}/{doc_id}/ai/generate-image

Backups and Restorations

Because your assets and documentation are critical, the API provides a dedicated suite of endpoints to manage backups to your configured repository.

flowchart LR
    A["Documentation"] -->|Contains| B["Assets (Files)"]
    A -->|Configures| C["Backup Repository"]
    B -->|Backed up to| C
    C -->|Restores| A

Backup Endpoints Overview

ActionMethodAPI Endpoint
List backupsGET/v1/documentation/{org_id}/{doc_id}/backup
Create backupPOST/v1/documentation/{org_id}/{doc_id}/backup
Get repositoryGET/v1/documentation/{org_id}/{doc_id}/backup/repository
Set repositoryPUT/v1/documentation/{org_id}/{doc_id}/backup/repository
Restore backupPOST/v1/documentation/{org_id}/{doc_id}/backup/restore

Triggering a restore via POST /backup/restore will overwrite your current documentation state (including all asset metadata) with the state from the backup. Ensure you have saved any recent changes before initiating a restore.

Initializing Documentation

If you need to bootstrap your documentation state from an external source before creating backups, you can initialize it directly from an existing website.

ActionMethodAPI Endpoint
Initialize from websitePOST/v1/documentation/{org_id}/{doc_id}/initialize-from-website

Frequently Asked Questions

What is the difference between getting an asset and serving an asset file?

The GET /asset/{asset_id} endpoint returns a JSON object containing the file's metadata (like its name, size, upload date, and custom tags). The GET /asset/{asset_id}/file endpoint returns the actual binary file (e.g., the raw PNG or PDF data) so it can be downloaded or rendered in a browser.

Can I restore a single file's metadata from a backup?

Currently, the /backup/restore endpoint restores the entire documentation environment, including all files and their metadata at the time the backup was created. If you only need to fix a single file's metadata, it is safer to update it manually using the PUT /asset/{asset_id} endpoint.