Manage your project's images, documents, and other file assets programmatically. This guide covers how to upload files, manage asset metadata, and leverage AI to generate and edit content directly within your documentation.

Whether you are migrating existing files, allowing users to upload attachments, or using AI to generate missing diagrams, the Asset API provides a complete suite of tools to handle your media.

flowchart TD
    subgraph "Asset Creation"
        A["Direct Upload"] 
        B["URL Import"] 
        C["AI Image Generation"] 
    end
    
    D[("Asset Storage")]
    
    A --> D
    B --> D
    C --> D
    
    D --> E["Serve Asset File"]
    D --> F["Manage Metadata"]

Managing Assets

Assets represent the media files attached to your documentation. Every asset belongs to a specific documentation project within your organization.

All standard asset endpoints share the following base path:
/v1/documentation/{organization_id}/{documentation_id}/asset

Uploading and Importing Files

Depending on your architecture and file sizes, you can add files to your documentation in three different ways.

1. Direct Import from URL

If your file is already hosted elsewhere (like a public S3 bucket or an external website), you can instruct the API to fetch and import it directly.

curl -X POST "https://api.gitdocai.com/v1/documentation/{org_id}/{doc_id}/asset/import" 
  -H "Authorization: Bearer YOUR_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"url": "https://example.com/images/architecture.png"}'

2. Standard Upload

For smaller files, you can use the standard POST /asset endpoint using multipart/form-data to send the file directly in your request.

3. Signed URL Uploads (For Large Files)

For large files or client-side uploads, it is best practice to use signed URLs. This offloads the heavy lifting from your server and uploads the file directly to our storage infrastructure.

1. 1

   Request a signed URL

   Call POST /v1/documentation/{organization_id}/{documentation_id}/file-resources/upload-url. The API will return a temporary, secure URL destination.

2. 2

   Upload the file

   Perform a PUT request directly to the provided signed URL with your file's binary data.

3. 3

   Finalize the upload

   Once the upload finishes, call POST /v1/documentation/{organization_id}/{documentation_id}/file-resources/finalize to confirm the upload and generate the official Asset record in your documentation.

AI-Driven Content Generation

GitDocAI includes powerful AI endpoints that can generate assets and edit content on the fly.

Generating Images

Instead of manually creating and uploading diagrams or illustrations, you can prompt the AI to generate an image for you. The generated image is automatically saved to your project as an asset.

Endpoint: POST /documentation/{organization_id}/{documentation_id}/ai/generate-image

curl -X POST "https://api.gitdocai.com/documentation/{org_id}/{doc_id}/ai/generate-image" 
  -H "Authorization: Bearer YOUR_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "prompt": "A modern, minimalist flowchart showing a user authentication process",
    "style": "diagram"
  }'

AI Content Editing

You can also leverage AI to refine, expand, or format your written documentation content.

Endpoint: POST /documentation/{organization_id}/{documentation_id}/ai/edit

Pass the raw text and instructions (e.g., "Make this sound more professional" or "Format this as a markdown table") to receive the optimized content back.