Files

A file is an uploaded trace, for use in a batch. To twin a single trace, send it to create a twin instead.

Formats

A twin keeps its trace’s format and extension. Other formats, such as PDFs or archives, return 400 file_unsupported.

{
  "id": "file_3a9e...",
  "object": "file",
  "filename": "trace-0001.jsonl",
  "bytes": 482113,
  "created": 1760054400,
  "livemode": true
}

Field	Type	Description
`id`	string	Unique identifier, prefixed `file_`
`object`	string	`file`
`filename`	string or null	Name of the uploaded file
`bytes`	integer	Size in bytes
`created`	integer	Time of upload, in Unix seconds
`livemode`	boolean	`false` for a test-mode file

POST /v1/kennet/files Uploads one trace. Send multipart/form-data. Each file can be used in one batch request.

Parameter	Type	Required	Description
`file`	file	yes	The trace, in a supported format. Max 50 MiB (2 MiB in test mode). Name: 1 to 200 letters, digits, `.`, `-` and `_`, not starting with `.`

curl https://api.metaphi.ai/v1/kennet/files \
  -H "Authorization: Bearer $API_KEY" \
  -F file=@trace-0001.jsonl

Returns 200 with a file object.

Status	Code	Cause
400	`invalid_filename`	Invalid file name
400	`file_empty`	The file is empty
400	`file_unsupported`	Not JSON, JSON Lines or UTF-8 text
413	`file_too_large`	Over 50 MiB (2 MiB in test mode). Split the trace and upload each part

GET /v1/kennet/files/{id} Retrieves a file. Returns a file object, or 404 resource_missing.

GET /v1/kennet/files Lists files, newest first.

Parameter	Type	Required	Description
`limit`	integer	no	1 to 100. Default 10
`starting_after`	string	no	A file ID. Returns the page after it

Returns {object: "list", data, has_more, url}, with file objects in data.

DELETE /v1/kennet/files/{id} Deletes a file not used in a batch. Returns {id, object: "file", deleted: true}.

Status	Code	Cause
404	`resource_missing`	No such file
409	`file_in_use`	The file is in a batch