Create files

Makes an object in one of the caller's org buckets a workspace file.

POST /v1/knowledge/files

Knowledge → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/knowledge/files`
Method	`POST`
Operation	`post_knowledge_files`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Makes an object in one of the caller's org buckets a workspace file. Upload the bytes first — POST /v1/s3/buckets/{bucket}/objects mints a presigned PUT, POST /v1/s3/buckets/{bucket}/uploads starts a multipart upload for a large one — then register the key here. The object's name, type and size are read from the store. The file is recorded as queued, a file_stored event is stated on the org's event plane, and a durable ingest is queued that extracts its text and structure, summarizes its table of contents, cuts and embeds its passages and links it into the org's graph. An archive (.zip) is unpacked and every file inside becomes a workspace file of its own. Poll GET /v1/knowledge/files/{id} for status. Registering an object again answers the same file, and re-indexes it only when the object changed or its last ingest failed.

Request

3 fields, body application/json (required).

Field	In	Type	Required	Description
`bucket`	body	string	—	Bucket is one of the org's buckets, by the friendly name /v1/s3/buckets lists.
`key`	body	string	—	Key is the object's key in that bucket, as the upload wrote it.
`project`	body	string	—	Project indexes the file under one project scope.

Response

Status	Body	Meaning
`200`	knowledge.File	ok
`default`	problem-details	refused

200 body — 21 fields.

Field	In	Type	Always	Description
`bucket`	body	string	—	Bucket is the org bucket the object is in, by the friendly name /v1/s3/buckets lists.
`chars`	body	integer (int64)	—	Chars is the length of the text read out of the file, in bytes.
`clipped`	body	boolean	—	Clipped is true when only the file's beginning is indexed: its text ran past the org's bound or the room the index has.
`created`	body	integer (int64)	—	Created is when the file was first registered, in unix seconds.
`done`	body	integer (int64)	—	Done is how far the running stage has come, of Total: bytes of the file read (extract), sections summarized (toc), cut into passages (passages) and linked (graph), passages embedded (embed).
`embedded`	body	integer (int64)	—	Embedded is how many of those passages carry a vector — Passages once the embed stage is done, unless Note says the file is embedded in part.
`error`	body	string	—	Error is why a stored or failed file was not indexed — or, on a ready file, why it is searched by its words alone — in words a person can act on.
`id`	body	string	—	ID names the file in its org.
`key`	body	string	—	Key is the object's key in that bucket.
`name`	body	string	—	Name is the object's file name, the last segment of its key.
`note`	body	string	—	Note says in words where the file is indexed less than whole and why: its text past the org's bound or the room the index has, its passages past the bound on vectors.
`parent`	body	string	—	Parent is the id of the archive this file was unpacked from.
`passages`	body	integer (int64)	—	Passages is how many passages its text was cut into.
`project`	body	string	—	Project is the project scope it is indexed under.
`sections`	body	integer (int64)	—	Sections is how many nodes its table of contents has, the document's own root included.
`size`	body	integer (int64)	—	Size is the object's length in bytes, as the store reports it.
`stage`	body	string	—	Stage is the ingest stage the file is in: extract, toc, passages or graph while indexing, embed while a ready file's vectors are written.
`status`	body	string	—	Status is queued, indexing, ready, stored (kept but not indexed — Error says why) or failed.
`total`	body	integer (int64)	—	Total is what the running stage has to do in all, in Done's units.
`type`	body	string	—	Type is the object's media type as the store holds it, or the one its name implies when the store holds only the generic default.
`updated`	body	integer (int64)	—	Updated is when its record last changed, in unix seconds.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.

.ts

.py

.go

.rs

.java

import { Configuration, KnowledgeApi } from 'hanzoai';

const api = new KnowledgeApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postKnowledgeFiles({ bucket: "<bucket>", key: "<key>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import KnowledgeApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = KnowledgeApi(client).post_knowledge_files(bucket="<bucket>", key="<key>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.KnowledgeAPI.PostKnowledgeFiles(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, knowledge_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = knowledge_api::post_knowledge_files(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.KnowledgeApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new KnowledgeApi(client).postKnowledgeFiles();

curl -X POST https://api.hanzo.ai/v1/knowledge/files \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "bucket": "<bucket>",
       "key": "<key>"
     }'

MCP reaches knowledge through the knowledge tool, which names its 9 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_knowledge_connectors"
         }
       }
     }'

Knowledge API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousSearch files NextImport knowledge