File storage for AI agents

An agent uploads a file into a namespace. Tillpad stores the bytes, extracts text from PDF and Excel, and indexes the text so a later search can find it. For developers storing files for AI agents. Pro is $9 a month.

What an upload does

Upload a file and Tillpad makes it searchable shortly after.

  • POST /api/files/:namespace accepts multipart form data with a field named file. The worker writes the bytes to object storage, inserts a files row, and queues an index job.
  • The row moves from indexing to ready when chunking and embedding finish, or it stores an error if extraction fails.
  • Text is split into chunks of 1,200 characters with a 150 character overlap, embedded with the Workers AI model @cf/baai/bge-base-en-v1.5 (768 dimensions), and written to the vector index. Delete removes the object and those vector ids.
  • The upload call meters one kvp_ops. Chunk indexing later meters rag_index. Stored bytes count toward storage_bytes.
  • GET /api/files lists up to 200 rows. GET /api/files/:id returns one row, including status.

Which files are accepted

GET /api/files/types returns the live catalog. Plain text and source files are decoded as UTF-8. PDF text is extracted before indexing. Scanned PDFs that contain only images are not supported. Excel .xls and .xlsx sheets are converted to CSV text, with the sheet title, before indexing.

Images, audio, video, archives, Word, and PowerPoint are rejected with HTTP 415 and code unsupported_media_type. A text upload that looks binary is rejected the same way.

REST and MCP

PDF and Excel go through the multipart REST upload. The MCP tool index_document with kind=file accepts UTF-8 text only. It requires namespace, text, and filename. contentType defaults to text/plain. list_files view=files lists metadata. list_files view=supported_types returns the same catalog as GET /api/files/types and does not spend quota.

The key must be allowed to use that namespace. An active Pro plan is required before metered uploads run. See pricing and the scratchpad loop.

curl -s -X POST "https://tillpad.dev/api/files/$NS" \
  -H "Authorization: Bearer tp_…" \
  -F "file=@/tmp/notes.txt;type=text/plain"

curl -s -H "Authorization: Bearer tp_…" "https://tillpad.dev/api/files/$FILE_ID"

Related

Questions people ask

Can an agent upload a PDF?

Yes, through multipart POST /api/files/:namespace. Text is extracted and indexed. Image-only PDFs are not supported. The MCP index_document tool accepts UTF-8 text, not PDF bytes.

When can search see a new file?

After the file row status is ready. Indexing is queued, so the upload response is not the search result. Poll GET /api/files/:id until status is ready.