openapi: 3.0.0
info:
  title: Auto Drive APIs Auto Drive API API
  version: 1.1.0
  description: 'Auto-Drive consists of multiple APIs that are used to interact with the Auto-Drive platform.


    ## Authentication


    All requests to the Auto-Drive APIs require authentication. The following authentication methods are supported:


    - API Key

    - JWT Token (rarely used)


    ## How to use an API key?


    The API key is a string that is used to authenticate requests to the Auto-Drive APIs, you can create one in the [Auto-Drive Dashboard](https://ai3.storage).


    To use an API key, include it in the Authorization header with the Bearer prefix:


    ```

    Authorization: Bearer your-api-key

    X-Auth-Provider: apikey

    ```


    API keys should be kept secure and not shared with unauthorized parties.


    ## Purchasing Storage Credits (Pay with AI3)


    Third-party applications can purchase storage credits programmatically using the Intents API. The flow is:


    1. **Create an account** — Register at [ai3.storage](https://ai3.storage) via Google OAuth

    2. **Generate an API key** — From the dashboard, create an API key

    3. **Get contract info** — `GET /intents/contract` returns the contract address, chain ID, and ABI

    4. **Check current price** — `GET /intents/price` returns the current price per byte and per GB to display to the user

    5. **Create an intent** — `POST /intents` with your API key returns an `intentId` with the price locked in

    6. **Pay on-chain** — Call `payIntent(intentId)` on the contract, sending AI3 as native value

    7. **Submit tx hash** — `POST /intents/:id/watch` with the transaction hash

    8. **Poll for completion** — `GET /intents/:id` until status is `completed`

    9. **Upload content** — Use the Auto Drive SDK with the same API key (credits are now on the account)


    **Note:** A Google-verified account is currently required to purchase credits. API keys inherit the auth provider of the account that created them, so an API key from a Google-registered account satisfies this requirement.


    ## Auto-Drive Services


    Auto-Drive consists of two main services:


    ### 1. Auto-Drive API


    The Storage Service handles all file operations including uploads, downloads, and object management. It provides APIs for:

    - File uploads (single and multipart)

    - Object metadata management

    - Access control and permissions

    - Account management

    - Credit purchases (Pay with AI3)


    ### 2. Auto-Drive Download Gateway


    The Auto-Drive Download Gateway is a service that allows you to download files from the Auto-Drive API. It provides APIs for:

    - File downloads

    - Async downloads'
security:
- apiKey: []
  provider: []
tags:
- name: Auto Drive API
paths:
  /accounts/@me:
    get:
      summary: Accounts - Get current user account information
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      responses:
        '200':
          description: Successfully retrieved account information
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    $ref: '#/components/schemas/AccountInfo'
                required:
                - id
                - organizationId
                - uploadLimit
                - downloadLimit
                - model
                - pendingUploadCredits
                - pendingDownloadCredits
        '401':
          description: Unauthorized
        '500':
          description: Failed to get user info
  /uploads/file:
    post:
      summary: Uploads - Upload a file
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filename:
                  type: string
                mimeType:
                  type: string
                uploadOptions:
                  $ref: '#/components/schemas/UploadOptions'
              required:
              - filename
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        '400':
          description: Invalid input
        '500':
          description: Failed to create upload
  /uploads/folder:
    post:
      summary: Uploads - Create a new folder upload
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                fileTree:
                  $ref: '#/components/schemas/FolderTree'
                uploadOptions:
                  $ref: '#/components/schemas/UploadOptions'
              required:
              - fileTree
      responses:
        '200':
          description: Folder created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        '400':
          description: Invalid input
        '500':
          description: Failed to create upload
  /uploads/folder/{folderUploadId}/file:
    post:
      summary: Uploads - Create a file in a folder provided by the folder upload id
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: folderUploadId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the file
                mimeType:
                  type: string
                  description: The mime type of the file
                relativeId:
                  type: string
                  description: The id of the uploaded file within the file tree
                uploadOptions:
                  $ref: '#/components/schemas/UploadOptions'
              required:
              - name
              - relativeId
      responses:
        '200':
          description: File created in folder successfully
        '400':
          description: Invalid input
        '500':
          description: Failed to create file in folder
  /uploads/file/{uploadId}/chunk:
    post:
      summary: Uploads - Upload a chunk of a file
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: uploadId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                index:
                  type: integer
              required:
              - file
              - index
      responses:
        '200':
          description: Chunk uploaded successfully
        '400':
          description: Invalid input
        '500':
          description: Failed to upload chunk
  /uploads/{uploadId}/complete:
    post:
      summary: Uploads - Complete the upload returning the file or folder CID
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: uploadId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Upload completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  cid:
                    type: string
        '500':
          description: Failed to complete upload
  /objects/roots:
    get:
      summary: Objects - Get root objects
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: scope
        in: query
        required: false
        schema:
          type: string
          enum:
          - global
          - user
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Successfully retrieved root objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ObjectSummary'
        '401':
          description: Unauthorized
        '500':
          description: Failed to retrieve root objects
  /objects/roots/shared:
    get:
      summary: Objects - Get shared root objects
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Successfully retrieved shared root objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ObjectSummary'
        '401':
          description: Unauthorized
        '500':
          description: Failed to retrieve shared root objects
  /objects/roots/deleted:
    get:
      summary: Objects - Get deleted root objects
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Successfully retrieved deleted root objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ObjectSummary'
        '401':
          description: Unauthorized
        '500':
          description: Failed to retrieve deleted root objects
  /objects/search:
    get:
      summary: Objects - Search for objects by CID or name
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: cid
        description: The CID or name of the object to search for
        in: query
        required: true
        schema:
          type: string
      - name: scope
        description: The scope of the search
        in: query
        required: false
        schema:
          type: string
          enum:
          - user
          - global
      - name: limit
        description: The maximum number of results to return
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Successfully retrieved search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ObjectSearchResult'
        '400':
          description: Missing or invalid cid value
        '500':
          description: Failed to search metadata
  /objects/{cid}/summary:
    get:
      summary: Objects - Get summary of an object by CID
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: cid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved object summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectSummary'
        '404':
          description: Metadata not found
        '500':
          description: Failed to retrieve metadata
  /objects/{cid}/metadata:
    get:
      summary: Objects - Get metadata of an object by CID
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: cid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved object metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffchainMetadata'
        '404':
          description: Metadata not found
        '500':
          description: Failed to retrieve metadata
  /objects/{cid}/status:
    get:
      summary: Objects - Get upload status of an object by CID
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: cid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved upload status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadStatus'
        '500':
          description: Failed to retrieve upload status
  /objects/{cid}/share:
    post:
      summary: Objects - Share an object by CID
      tags:
      - Auto Drive API
      parameters:
      - name: cid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                publicId:
                  type: string
              required:
              - publicId
      responses:
        '200':
          description: Successfully shared object
        '400':
          description: Missing `publicId` in request body
        '401':
          description: Unauthorized
        '500':
          description: Failed to share object
  /objects/{cid}/download:
    get:
      deprecated: true
      summary: Objects - Download an object by CID
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: cid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved object for download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Metadata not found
        '500':
          description: Failed to retrieve data
  /objects/{cid}/delete:
    post:
      summary: Objects - Delete an object by CID
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: cid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted object
        '401':
          description: Unauthorized
        '500':
          description: Failed to delete object
  /objects/{cid}/restore:
    post:
      summary: Objects - Restore a deleted object by CID
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: cid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully restored object
        '401':
          description: Unauthorized
        '500':
          description: Failed to restore object
  /objects/{cid}/publish:
    post:
      summary: Objects - Publish an object by CID and return the object id
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: cid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully published object
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
        '401':
          description: Unauthorized
        '500':
          description: Failed to publish object
  /objects/{cid}/unpublish:
    post:
      summary: Objects - Unpublish an object by CID
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: cid
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Successfully unpublished object
        '401':
          description: Unauthorized
        '500':
          description: Failed to unpublish object
  /objects/{id}/public:
    get:
      summary: Objects - Download a published object by id
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved object for download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Published object not found
        '500':
          description: Failed to retrieve data
  /intents/price:
    get:
      summary: Intents - Get current storage price
      description: Returns the current price per byte (in shannons) and price per GB (in AI3). This endpoint does not require authentication.
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      security: []
      responses:
        '200':
          description: Current price information
          content:
            application/json:
              schema:
                type: object
                properties:
                  price:
                    type: number
                    description: Price per byte in shannons
                  pricePerGB:
                    type: number
                    description: Price per GB in AI3 tokens
  /intents/contract:
    get:
      summary: Intents - Get smart contract info
      description: Returns the on-chain contract address, EVM chain ID, and the minimal ABI needed to call `payIntent`. This endpoint does not require authentication. Use this to build the on-chain transaction for step 4 of the integration flow.
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      security: []
      responses:
        '200':
          description: Contract information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractInfo'
  /intents:
    post:
      summary: Intents - Create a purchase intent
      description: 'Creates a PENDING intent with the current price locked in. The intent has a time-limited price-lock window (default 10 minutes) during which the price is guaranteed.


        **Authentication:** Currently requires a Google-verified account. You can authenticate via:

        - Google OAuth session

        - API key from a Google-registered account (set `X-Auth-Provider: apikey`)


        **Third-party integration pattern:**

        1. Create an Auto Drive account via Google OAuth at https://ai3.storage

        2. Generate an API key from the dashboard

        3. Call `GET /intents/contract` to get the contract address, chain ID, and ABI

        4. Call `GET /intents/price` to get the current price per byte and per GB

        5. Call `POST /intents` with the API key to get an `intentId` with the price locked in

        6. Have the end user call `payIntent(intentId)` on the contract, sending AI3 as native value

        7. Call `POST /intents/:id/watch` with the transaction hash

        8. Poll `GET /intents/:id` until status is `completed`

        9. Upload content via the Auto Drive SDK using the same API key'
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      responses:
        '200':
          description: Intent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Intent'
        '401':
          description: Unauthorized — missing or invalid credentials
        '403':
          description: Google-verified account required — the authenticated account was not registered via Google OAuth
        '404':
          description: Feature not available — the buyCredits feature flag is not active for this user
  /intents/{id}:
    get:
      summary: Intents - Get intent status
      description: Returns the current status of a purchase intent. Use this to poll for completion after calling `/intents/:id/watch`.
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The intent ID returned by POST /intents
      responses:
        '200':
          description: Intent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Intent'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden — the intent belongs to a different user
        '404':
          description: Intent not found
        '410':
          description: Intent has expired (price-lock window elapsed)
  /intents/{id}/watch:
    post:
      summary: Intents - Submit transaction hash for watching
      description: Attaches a transaction hash to a pending intent and queues on-chain confirmation watching. Call this after the user has submitted the `payIntent` transaction on-chain.
      tags:
      - Auto Drive API
      servers:
      - url: https://mainnet.auto-drive.autonomys.xyz/api
        description: Mainnet Auto Drive API
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The intent ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                txHash:
                  type: string
                  description: The transaction hash from the on-chain payIntent call
              required:
              - txHash
      responses:
        '204':
          description: Transaction hash accepted — watching started
        '400':
          description: Missing or invalid txHash
        '401':
          description: Unauthorized
        '403':
          description: Forbidden — the intent belongs to a different user
        '410':
          description: Intent has expired
components:
  schemas:
    EncryptionOptions:
      type: object
      properties:
        algorithm:
          type: string
          enum:
          - AES_256_GCM
        chunkSize:
          type: integer
          default: 1024
    OffchainMetadata:
      type: object
      oneOf:
      - $ref: '#/components/schemas/OffchainFileMetadata'
      - $ref: '#/components/schemas/OffchainFolderMetadata'
    OffchainFileMetadata:
      type: object
      properties:
        type:
          type: string
          enum:
          - file
        dataCid:
          type: string
        name:
          type: string
          nullable: true
        mimeType:
          type: string
          nullable: true
        totalSize:
          type: string
        totalChunks:
          type: integer
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/ChunkInfo'
        uploadOptions:
          $ref: '#/components/schemas/UploadOptions'
    UploadStatus:
      type: object
      properties:
        uploadedNodes:
          type: integer
          nullable: true
        totalNodes:
          type: integer
          nullable: true
        archivedNodes:
          type: integer
          nullable: true
        minimumBlockDepth:
          type: integer
          nullable: true
        maximumBlockDepth:
          type: integer
          nullable: true
    UploadOptions:
      type: object
      properties:
        compression:
          $ref: '#/components/schemas/CompressionOptions'
        encryption:
          $ref: '#/components/schemas/EncryptionOptions'
    ChunkInfo:
      type: object
      properties:
        size:
          type: string
        cid:
          type: string
    FolderTree:
      oneOf:
      - $ref: '#/components/schemas/FolderTreeFolder'
      - $ref: '#/components/schemas/FolderTreeFile'
    AccountInfo:
      type: object
      properties:
        id:
          type: string
        organizationId:
          type: string
        uploadLimit:
          type: number
        downloadLimit:
          type: number
        module:
          type: string
          enum:
          - monthly
          - one_off
        pendingUploadCredits:
          type: number
        pendingDownloadCredits:
          type: number
      required:
      - id
      - organizationId
      - uploadLimit
      - downloadLimit
      - model
      - pendingUploadCredits
      - pendingDownloadCredits
    ContractInfo:
      type: object
      required:
      - chainId
      - contractAddress
      - payIntentAbi
      properties:
        chainId:
          type: integer
          description: EVM chain ID where the contract is deployed (e.g. 870 for Auto-EVM Mainnet)
        contractAddress:
          type: string
          description: Address of the AutoDriveCreditsReceiver contract (checksummed)
        payIntentAbi:
          type: array
          description: Minimal ABI for the payIntent function — pass directly to viem/ethers/web3.js
          items:
            type: object
    CompressionOptions:
      type: object
      properties:
        algorithm:
          type: string
          enum:
          - ZLIB
        level:
          type: integer
          default: 8
    FolderTreeFolder:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          enum:
          - folder
          - file
        children:
          $ref: '#/components/schemas/FolderTree'
    FolderTreeFile:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          enum:
          - file
        id:
          type: string
    ChildrenMetadata:
      type: object
      properties:
        type:
          type: string
          enum:
          - file
          - folder
        cid:
          type: string
        name:
          type: string
          nullable: true
        totalSize:
          type: string
      required:
      - type
      - cid
      - totalSize
    OffchainFolderMetadata:
      type: object
      properties:
        type:
          type: string
          enum:
          - folder
        dataCid:
          type: string
        name:
          type: string
          nullable: true
        totalSize:
          type: string
        totalFiles:
          type: integer
        children:
          type: array
          items:
            $ref: '#/components/schemas/ChildrenMetadata'
        uploadOptions:
          $ref: '#/components/schemas/UploadOptions'
    Intent:
      type: object
      properties:
        id:
          type: string
          description: Unique intent identifier (hex string)
        userPublicId:
          type: string
          description: Public ID of the intent owner
        status:
          type: string
          enum:
          - pending
          - confirmed
          - completed
          - failed
          - expired
          - over_cap
          description: Current intent status
        txHash:
          type: string
          description: On-chain transaction hash (set after /watch)
        paymentAmount:
          type: string
          description: Payment amount in shannons (bigint as string)
        shannonsPerByte:
          type: string
          description: Locked price per byte in shannons (bigint as string)
        expiresAt:
          type: string
          format: date-time
          description: Price-lock expiry timestamp
    ObjectSummary:
      type: object
      properties:
        headCid:
          type: string
        name:
          type: string
          nullable: true
        size:
          type: string
        owners:
          type: array
          items:
            type: object
            properties:
              oauthProvider:
                type: string
              oauthUserId:
                type: string
              role:
                type: string
                enum:
                - admin
                - viewer
        uploadStatus:
          $ref: '#/components/schemas/UploadStatus'
        createdAt:
          type: string
          format: iso8601
        type:
          type: string
          enum:
          - file
          - folder
        mimeType:
          type: string
          nullable: true
        children:
          type: array
          items:
            type: object
          nullable: true
      required:
      - headCid
      - size
      - owners
      - uploadStatus
      - createdAt
      - type
    ObjectSearchResult:
      type: object
      properties:
        cid:
          type: string
        name:
          type: string
      required:
      - cid
      - name
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Bearer token for authentication. Example: Bearer <token>. Could be either an API key or a JWT token.'
    provider:
      type: apiKey
      in: header
      name: X-Auth-Provider
      description: 'Used for differentiating between different auth providers. For most use cases: X-Auth-Provider: apikey'