T
testing
API Reference: Integrations & Infrastructure Uploading Files and Assets via API

Whether you need to add images, PDFs, or other downloadable resources to your documentation, our API provides flexible ways to handle files programmatically. You can either upload files directly from your local system or import them from an existing public URL.

Direct File Uploads

Securely upload files directly to our storage using a two-step signed URL process.

Import from URL

Provide a public link, and we'll automatically fetch and import the asset for you.

For all endpoints on this page, you will need your {organization_id} and {documentation_id}. You can find these in your dashboard URL or by querying the documentation list endpoint.

How File Uploads Work

To ensure fast and secure file transfers, direct uploads use a "signed URL" approach. Instead of sending the heavy file through our main API, you request a temporary, secure link to upload the file directly to our cloud storage. Once the upload finishes, you tell our API to finalize the process.

sequenceDiagram
    participant YourApp as Your Application
    participant API as GitDocAI API
    participant Storage as Cloud Storage

    YourApp->>API: 1. Request Signed URL
    API-->>YourApp: Returns Secure Upload URL
    YourApp->>Storage: 2. Upload File (PUT request)
    Storage-->>YourApp: Upload Successful
    YourApp->>API: 3. Finalize Upload
    API-->>YourApp: File Resource Created

Direct File Uploads

Follow these steps to upload a file from your local system or server.

  1. 1

    Request a signed upload URL

    First, ask the API for a secure location to put your file.

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

    The API will respond with a temporary URL specifically generated for your file.

  2. 2

    Upload your file

    Using the URL returned in Step 1, upload your file directly to the storage provider. This is typically done using a standard PUT request with the file's binary data in the body.

    Signed URLs expire shortly after they are generated (usually within 15 minutes). Make sure to start your upload immediately after requesting the URL.

  3. 3

    Finalize the upload

    Once your file has successfully uploaded to the signed URL, you need to notify the API so it can link the file to your documentation.

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

    Your file is now successfully attached to your documentation!

Importing Assets from a URL

If your files are already hosted online (like an image on a CDN or a document in a public S3 bucket), you can skip the direct upload process entirely. Just give us the link, and we'll pull it in.

To import an asset, make a POST request to:
/v1/documentation/{organization_id}/{documentation_id}/asset/import

Include the source URL in your request body. The API will fetch the file and register it as an asset in your documentation automatically.

Importing from a URL is generally faster and requires less code on your end. Use this method whenever your assets are already publicly accessible!

API Endpoint Reference

Here is a quick summary of the endpoints used for managing files and assets:

ActionHTTP MethodEndpoint Path
Request Upload URLPOST/v1/documentation/{org_id}/{doc_id}/file-resources/upload-url
Finalize UploadPOST/v1/documentation/{org_id}/{doc_id}/file-resources/finalize
Import AssetPOST/v1/documentation/{org_id}/{doc_id}/asset/import

Frequently Asked Questions

Why do I have to use a two-step process for direct uploads?

The two-step process (requesting a URL, then uploading) allows your application to upload files directly to our cloud storage infrastructure. This bypasses our main API servers, resulting in much faster upload speeds and allowing you to upload larger files without hitting API timeout limits.

What happens if I forget to finalize the upload?

If you upload the file to the signed URL but never call the finalize endpoint, the file will remain in temporary storage and won't appear in your documentation. Our system automatically cleans up unfinalized files after a few days.