Media assets like images, diagrams, and downloadable files make your documentation more engaging and easier to understand. The Asset Management endpoints allow you to programmatically upload, retrieve, update, and delete these files within your documentation projects.

Understanding the Asset Lifecycle

Managing assets typically follows a straightforward lifecycle: you upload a file, use its metadata to embed it in your documentation, and eventually update or remove it if it becomes outdated.

flowchart LR
    A["Upload Asset (POST)"] --> B["Asset Stored"]
    B --> C["Serve File (GET)"]
    B --> D["Update Metadata (PUT)"]
    B --> E["Delete Asset (DELETE)"]

Path Parameters

All asset endpoints share a common base path:
/v1/documentation/{organization_id}/{documentation_id}/asset

Whenever you interact with these endpoints, you will need to provide the following parameters in your URL:

Available Endpoints

Here is a quick reference for all the actions you can perform on your documentation assets.

Managing the Asset Collection

• List all assets
  GET /v1/documentation/{organization_id}/{documentation_id}/asset
  Retrieves a list of all assets currently associated with the specified documentation project. Useful for auditing or building a media library UI.

• Upload an asset
  POST /v1/documentation/{organization_id}/{documentation_id}/asset
  Uploads a new file. The response will include the newly generated asset_id which you will need for future operations.

Managing Individual Assets

• Get asset metadata
  GET /v1/documentation/{organization_id}/{documentation_id}/asset/{asset_id}
  Retrieves the details of a specific asset, such as its filename, size, and upload date, without downloading the actual file.

• Update asset metadata
  PUT /v1/documentation/{organization_id}/{documentation_id}/asset/{asset_id}
  Updates the information associated with an asset (like renaming it or adding alt text).

• Serve asset file
  GET /v1/documentation/{organization_id}/{documentation_id}/asset/{asset_id}/file
  Returns the raw file content. This is the endpoint you should use as the src attribute in your <img> tags or download links.

• Delete an asset
  DELETE /v1/documentation/{organization_id}/{documentation_id}/asset/{asset_id}
  Permanently removes the asset from your documentation project.

Common Workflow: Uploading and Embedding

If you are building an integration that adds images to your documentation, follow these steps:

1. 1

   Upload the file

   Send a POST request to the upload endpoint with your file payload.

   curl -X POST https://api.gitdocai.com/v1/documentation/ORG_123/DOC_456/asset 
     -H "Authorization: Bearer YOUR_TOKEN" 
     -F "file=@/path/to/your/image.png"

2. 2

   Save the Asset ID

   The API will return a JSON response containing the new asset_id. Save this ID in your application.

3. 3

   Embed in your content

   Construct the file serving URL using the asset_id and use it in your Markdown or HTML content.

   ![My uploaded image](https://api.gitdocai.com/v1/documentation/ORG_123/DOC_456/asset/ASSET_789/file)