---
updatedAt: 2025-07-28T18:59:28.000Z
agentTools:
  projectIndex: https://docs.ducky.ai/llms.txt
---

# Index a document by uploading a file

Index a document into the specified index by uploading a file. Supports UTF-8 encoded text-based files and PDF files. The file size must be less than 60MB.


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "contact": {
      "email": "support@ducky.ai",
      "name": "Ducky Developer Support"
    },
    "description": "API for managing and retrieving data from Ducky.",
    "title": "Ducky API",
    "version": "1.0.1"
  },
  "servers": [
    {
      "url": "https://api.ducky.ai"
    }
  ],
  "security": [
    {
      "api_key": []
    }
  ],
  "paths": {
    "/v1/documents/index-file": {
      "post": {
        "description": "Index a document into the specified index by uploading a file. Supports UTF-8 encoded text-based files and PDF files. The file size must be less than 60MB.\n",
        "operationId": "indexFile",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/indexFile_request"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentIndexedResponse"
                }
              }
            },
            "description": "Document indexing request accepted. The file will be processed asynchronously."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request (e.g., missing index_name, malformed metadata JSON)"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Index not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "File type not supported or file size exceeds the maximum limit of 60MB"
          }
        },
        "summary": "Index a document by uploading a file",
        "tags": [
          "documents"
        ],
        "x-speakeasy-name-override": "indexFile",
        "x-speakeasy-usage-example": true,
        "x-code-samples": [
          {
            "language": "python",
            "label": "indexFile",
            "code": "from duckyai import DuckyAI\nclient = DuckyAI(api_key=\"api_key\")\nwith open(\"path/to/document.md\", \"rb\") as f:\n    res = client.documents.index_file(\n        index_name=\"my-index\",\n        file=f,\n        doc_id=\"optional-doc-id\",\n        metadata={\"author\": \"Mr Quack\"}\n    )",
            "install": "pip install duckyai"
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "DocumentIndexedResponse": {
        "example": {
          "doc_id": "doc_id"
        },
        "properties": {
          "doc_id": {
            "description": "The ID of the indexed document",
            "title": "doc_id",
            "type": "string"
          }
        },
        "title": "DocumentIndexedResponse",
        "type": "object"
      },
      "ErrorResponse": {
        "example": {
          "error": "error"
        },
        "properties": {
          "error": {
            "description": "Error message explaining the issue",
            "title": "error",
            "type": "string"
          }
        },
        "title": "ErrorResponse",
        "type": "object"
      },
      "indexFile_request": {
        "properties": {
          "index_name": {
            "description": "The name of the index to which the document will be added",
            "type": "string"
          },
          "file": {
            "description": "Text-based files and PDF files are supported.",
            "format": "binary",
            "type": "string"
          },
          "doc_id": {
            "description": "The ID of the document. If not provided, a unique document ID will be automatically generated by the server",
            "type": "string"
          },
          "title": {
            "description": "Title of the document to be indexed",
            "type": "string"
          },
          "url": {
            "description": "URL associated with the document to be indexed",
            "type": "string"
          },
          "metadata": {
            "description": "Metadata associated with the document as JSON string. Accepts key value pairs where the value can be a string, number, boolean, or list of strings.",
            "type": "string"
          }
        },
        "required": [
          "file",
          "index_name"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "api_key": {
        "description": "API key providing access to a project.",
        "in": "header",
        "name": "x-api-key",
        "type": "apiKey"
      }
    }
  },
  "x-google-backend": {
    "address": "api.ducky.ai"
  },
  "x-samples-languages": [
    "python",
    "shell"
  ]
}
```