📦 CAR File

CAR (Content Addressable aRchive) files are a format used in IPFS/IPLD ecosystems for storing and transferring content-addressed data. They bundle multiple blocks of data with their CIDs into a single archive, making them efficient for importing pre-structured IPLD data directly into IPFS nodes.

Use uploadCAR() when you have pre-built CAR files that you want to upload to Lighthouse.

info

The uploadCAR() function validates that the file has a .car extension before uploading.

JS SDK

Method 1: Node.js

import lighthouse from '@lighthouse-web3/sdk'

/**
 * Upload a CAR file to Lighthouse.
 * 
 * @param {string} path - The path to your .car file.
 * @param {string} apiKey - Your personal API key for Lighthouse.
 * @param {object} options - Optional configuration (onProgress, headers).
 * @return {object} - Returns details about the uploaded file.
 */
const uploadCAR = async () => {
  const filePath = '/path/to/your/archive.car'
  const apiKey = 'YOUR_API_KEY'
  
  const response = await lighthouse.uploadCAR(filePath, apiKey)
  
  console.log(response)
  
  /*
    Sample response:
    {
      data: {
        Name: 'archive.car',
        Hash: 'QmTzQ1JRkWErMdfKPMRh6cTP2yxVvZv4jmHqZ3LJmFLKV3',
        Size: '2048576'
      }
    }
  */
  
  console.log('Visit at https://gateway.lighthouse.storage/ipfs/' + response.data.Hash)
}

With Progress Tracking:

import lighthouse from '@lighthouse-web3/sdk'

const uploadCARWithProgress = async () => {
  const filePath = '/path/to/your/archive.car'
  const apiKey = 'YOUR_API_KEY'
  
  const response = await lighthouse.uploadCAR(filePath, apiKey, {
    onProgress: (progress) => {
      console.log(`Upload Progress: ${progress.progress}%`)
    }
  })
  
  console.log('Upload Complete!')
  console.log('IPFS Hash:', response.data.Hash)
}

With Custom Storage Type Header:

import lighthouse from '@lighthouse-web3/sdk'

const uploadCARWithStorageType = async () => {
  const filePath = '/path/to/your/archive.car'
  const apiKey = 'YOUR_API_KEY'
  
  const response = await lighthouse.uploadCAR(filePath, apiKey, {
    headers: {
      storageType: 'lifetime'  // Storage plan: "annual" or "lifetime"
    }
  })
  
  console.log('Uploaded to custom storage!')
  console.log('IPFS Hash:', response.data.Hash)
}

Method 2: Browser

import React from "react"
import lighthouse from '@lighthouse-web3/sdk'

function App() {

  const progressCallback = (progressData) => {
    console.log(`Upload Progress: ${progressData.progress}%`)
  }

  const uploadCAR = async (e) => {
    const file = e.target.files[0]
    
    // Validate file extension
    if (!file.name.endsWith('.car')) {
      console.error('Please select a .car file')
      return
    }
    
    const output = await lighthouse.uploadCAR(
      file, 
      "YOUR_API_KEY",
      { onProgress: progressCallback }
    )
    
    console.log('File Status:', output)
    /*
      output:
        data: {
          Name: "archive.car",
          Hash: "QmTzQ1JRkWErMdfKPMRh6cTP2yxVvZv4jmHqZ3LJmFLKV3",
          Size: 2048576
        }
      Note: Hash in response is CID.
    */
    
    console.log('Visit at https://gateway.lighthouse.storage/ipfs/' + output.data.Hash)
  }

  return (
    <div className="App">
      <input onChange={uploadCAR} type="file" accept=".car" />
    </div>
  )
}

export default App

API

curl -X POST \
  -H 'Authorization: Bearer API_KEY' \
  -F 'file=@/path/to/your/archive.car' \
  'https://upload.lighthouse.storage/api/v0/dag/import'

Parameters

Parameter	Type	Required	Description
pathOrFile	string | File	Yes	Node.js: File path string (e.g., "/path/to/file.car"). Browser: File object from file input
apiKey	string	Yes	Your Lighthouse API key
options	object	No	Upload configuration options

Options

Option	Type	Default	Description
onProgress	function	undefined	Callback function for tracking upload progress. Receives { progress: number } (0-100)
headers.storageType	string	undefined	Storage plan type: "annual" or "lifetime" (sent as X-Storage-Type header)