When building and managing documentation, you often need to bring in external files, images, or even AI-generated content. The GitDocAI API provides a comprehensive suite of endpoints to handle direct file uploads, URL imports, AI content generation, and tracking the progress of multi-step setup wizards.

This guide walks you through the various ways you can import and manage assets programmatically.

Direct File Uploads

To securely upload physical files (like images or PDFs) into your documentation, GitDocAI uses a two-step signed URL process. This ensures files are uploaded directly to our secure storage without bottlenecking the main API.

sequenceDiagram
    participant C as Client
    participant A as GitDocAI API
    participant S as Cloud Storage
    
    C->>A: POST /file-resources/upload-url
    A-->>C: Returns Signed URL
    C->>S: PUT File to Signed URL
    S-->>C: 200 OK Upload Successful
    C->>A: POST /file-resources/finalize
    A-->>C: Asset Created & Linked

1. 1

   Request a signed upload URL

   First, request a secure, temporary URL where you can upload your file.

   Endpoint:
   POST /v1/documentation/{organization_id}/{documentation_id}/file-resources/upload-url

2. 2

   Upload your file

   Using the URL returned in the previous step, perform a standard PUT request containing your file's binary data directly to the cloud storage provider.

3. 3

   Finalize the upload

   Once the file is successfully uploaded to the signed URL, notify GitDocAI so the asset can be registered and linked to your documentation project.

   Endpoint:
   POST /v1/documentation/{organization_id}/{documentation_id}/file-resources/finalize

Importing Assets from a URL

If your asset is already hosted publicly on the internet, you can instruct GitDocAI to fetch and import it directly, skipping the manual download and upload process.

Endpoint:
POST /v1/documentation/{organization_id}/{documentation_id}/asset/import

Pass the source URL in your request body, and GitDocAI will download the asset, store it securely, and make it available in your documentation's media library.

Managing Assets

Once assets are imported or uploaded into your documentation project, you can manage them using the standard asset endpoints. This allows you to retrieve, update, or delete existing assets, as well as serve the underlying files.

AI-Generated Assets and Content

You can leverage GitDocAI's built-in artificial intelligence to generate new assets or refine existing content on the fly.

Tracking Wizard Progress

When users are importing large amounts of documentation or going through a complex onboarding setup, you can track their progress using the Wizard Progress endpoints. This allows you to save their state and let them resume later if they get interrupted.