Learn how to securely upload files and import external assets into your documentation projects using the API. Whether you are uploading local files directly from a user's device or pulling in existing assets from the web, the API provides dedicated endpoints to handle your media efficiently.

How file management works

Handling files in the API is divided into two distinct workflows. The Mermaid diagram below illustrates the difference between a direct file upload (a secure, multi-step process) and an asset import (a simple, single-step process).

sequenceDiagram
    participant Client
    participant API as GitDocAI API
    participant Storage as Cloud Storage
    
    rect rgb(240, 248, 255)
    Note over Client, Storage: Direct File Upload Workflow
    Client->>API: 1. Request signed upload URL
    API-->>Client: Returns secure URL
    Client->>Storage: 2. Upload file directly to Storage
    Client->>API: 3. Finalize the upload
    API-->>Client: File resource created
    end
    
    rect rgb(245, 245, 245)
    Note over Client, API: Asset Import Workflow
    Client->>API: 1. Send public URL to import
    API-->>Client: Asset imported successfully
    end

Direct file uploads

To securely handle large files without routing all the data through our core API servers, we use a signed URL approach. This allows your application to upload files directly to our cloud storage providers.

1. 1

   Request a signed upload URL

   First, you need to ask the API for a secure, temporary URL where you can upload your file.

   Make a request to the upload URL endpoint:
   POST /v1/documentation/{organization_id}/{documentation_id}/file-resources/upload-url

   The API will return a unique, time-limited URL specifically generated for your file.

2. 2

   Upload your file

   Using the signed URL provided in the previous step, upload your file directly to the storage provider. This is typically done using an HTTP PUT request with the file's raw binary data.

3. 3

   Finalize the upload

   Once the file has been successfully uploaded to the signed URL, you must tell the API that the process is complete so the file can be registered in your documentation project.

   Make a request to the finalize endpoint:
   POST /v1/documentation/{organization_id}/{documentation_id}/file-resources/finalize

Importing assets from a URL

If your images, videos, or documents are already hosted online (for example, on a public CDN or another server), you don't need to download and re-upload them. You can instruct the API to import them directly.

To import an asset, use the import endpoint:
POST /v1/documentation/{organization_id}/{documentation_id}/asset/import

Pass the public URL of the asset in your request payload. The system will fetch the file and attach it to your documentation project automatically.

Managing existing assets

Once your files are uploaded or imported, you can manage their metadata and lifecycle through the API. The system provides standard endpoints to retrieve, update, and delete assets, as well as serve the raw file content directly to users.

Endpoint reference summary

Here is a quick reference of the endpoints used for file and asset management: