Skip to content

Translation out of date

The source content changed after this translation. See the Português version. View original

File search

Built-in RAG: file upload, vector stores and responses grounded in your documents.

Updated on Aug 10, 2026

File search gives your assistant knowledge that isn't in the model — manuals, policies, reports, any document of yours. You upload the files to vector stores; the platform extracts the text, chunks it, generates embeddings and indexes them. At execution, the model decides when to search, and the response comes grounded in the passages found.

Quickstart

  1. 1

    Create the assistant with file_search

    Add {"type": "file_search"} to tools — the documents can come later.

  2. 2

    Upload the files

    A POST /v1/files multipart with purpose=assistants for each document.

  3. 3

    Create the vector store and add the files

    A POST /v1/vector_stores, then POST /v1/vector_stores/{id}/files with each file_id. Ingestion is asynchronous — wait for the completed status.

  4. 4

    Link to the assistant

    Update tool_resources.file_search.vector_store_ids with the store id.

  5. 5

    Run

    Ask something that's in the documents. The run shows the search in the steps and the response cites the content.

# 1. assistente
ASST=$(curl -s https://api.hinow.ai/v1/assistants \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "hinow/himax",
    "name": "RH",
    "instructions": "Responda com base nos documentos internos.",
    "tools": [{"type": "file_search"}]
  }' | jq -r .id)

# 2. arquivo
FILE=$(curl -s https://api.hinow.ai/v1/files \
  -H "Authorization: Bearer hi_SUA_API_KEY" \
  -F "file=@politica_ferias.pdf" -F "purpose=assistants" | jq -r .id)

# 3. vector store + arquivo
VS=$(curl -s https://api.hinow.ai/v1/vector_stores \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Docs RH"}' | jq -r .id)
curl -s https://api.hinow.ai/v1/vector_stores/$VS/files \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d "{\"file_id\": \"$FILE\"}"
# aguarde: GET /v1/vector_stores/$VS/files/$FILE até status=completed

# 4. vincular
curl -s https://api.hinow.ai/v1/assistants/$ASST \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d "{\"tool_resources\": {\"file_search\": {\"vector_store_ids\": [\"$VS\"]}}}"

# 5. perguntar
curl -s https://api.hinow.ai/v1/threads/runs \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d "{\"assistant_id\": \"$ASST\", \"thread\": {\"messages\": [\
       {\"role\": \"user\", \"content\": \"Quantos dias de férias posso vender?\"}]}}"

How it works

At execution, file_search becomes a tool that the model calls with the query it formulates itself. The search is semantic, runs over the vector stores of the assistant and the thread, and returns the most relevant passages (up to 8 per search) for the model to compose the response.

What was found is recorded in the run steps — each search appears as a tool_calls step with file_id, file_name and score for each result:

{
  "type": "tool_calls",
  "tool_calls": [{
    "type": "file_search",
    "file_search": {
      "results": [
        {"file_id": "file-8bcac8...", "file_name": "politica_ferias.pdf", "score": 0.59}
      ]
    }
  }]
}

Files

POSThttps://api.hinow.ai/v1/filesBearer

Upload a file (multipart/form-data).

Parâmetros

  • filefile· bodyobrigatório

    Up to 25 MB. PDF, TXT, Markdown, DOCX and other text formats.

  • purposestring· bodyobrigatório

    `assistants` for file search.

Respostas

200The `file` object — save the `id`

The rest of the CRUD: GET /v1/files (accepts ?purpose=), GET /v1/files/{id}, GET /v1/files/{id}/content (the binary) and DELETE /v1/files/{id}.

Vector stores

Full CRUD at /v1/vector_stores (create, list, read, edit, remove) and store files at /v1/vector_stores/{id}/files. The object brings file_counts with ingestion progress:

{"total": 2, "completed": 2, "in_progress": 0, "failed": 0, "cancelled": 0}

For larger volumes, file batches add multiple files in one call and give aggregated progress — this is what the SDK helpers upload_and_poll use:

# vários arquivos de uma vez
curl -s https://api.hinow.ai/v1/vector_stores/$VS/file_batches \
  -H "Authorization: Bearer hi_SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"file_ids": ["file-aaa", "file-bbb", "file-ccc"]}'

# progresso
curl -s https://api.hinow.ai/v1/vector_stores/$VS/file_batches/$BATCH \
  -H "Authorization: Bearer hi_SUA_API_KEY"

Threads also have documents

A thread can carry its own tool_resources.file_search.vector_store_ids — useful for combining the assistant's permanent documents with a file specific to that conversation. The search covers both.

Was this page helpful?