# Store a file for a pack tool's call

POST

/v1/tool-files

```sh
curl --request POST \
  --url https://example.com/v1/tool-files \
  --header 'Content-Type: */*' \
  --data binary
```

A pack tool that declares `storesFiles` gets the call’s tool files with each call, and its pack service posts each file the tool stores here. No API key: `Authorization: Bearer` carries the call’s token (`kgi_tf_…`), which names one call of one run and what it may do: store files for that call, read files its run may be shown (`GET /v1/tool-files/{artifactId}`), or both. The body is the file’s bytes, at most 10 MB read; `Content-Type` is the type its source declares, and `Kindgi-File-Name` its name, percent-encoded UTF-8 (an empty name is stored as `unnamed`). The runtime checks the bytes, and only they decide the type. The stored file is owned by the call’s run, in its project. The same bytes again in the same call, a re-run of it included, answer the first file. A call stores at most 10 files. The token closes when the call answers, when its time passes, or when its run ends.

## Parameters

### Header Parameters

**Kindgi-File-Name**

string

The file’s name, percent-encoded UTF-8. Absent or empty: `unnamed`.

## Request Bodyrequired

The file’s bytes, with the type its source declares as `Content-Type`.

\*/\*

string format: binary

## Responses

### 200

The stored file (`file`), for the tool to return in its result’s top-level `files`; or nothing stored, and why (`notStored`): `type` (not a type a model is shown, or the bytes aren’t the type they claim), `size` (over its type’s limit, or a body past 10 MB, not read to its end), `limit` (the call has stored 10 files), `storage` (the tenant’s storage is full).

application/json

One of:

- **object**

  object

  **file**

  required

  A stored file as a value: in a run’s input, a tool’s result or a conversation message. Only `artifactId` is trusted: the runtime shows a model a file by its own checked record of it, never by the value’s other fields. A message’s files are the ones its run admitted, with the record’s fields.

  object

  **type**

  required

  string

  Allowed value: kindgi.file

  **artifactId**

  required

  The stored file (`POST /v1/artifacts`): its `blobId`.

  string

  \>= 1 characters

  **name**

  The file’s name.

  string

  **contentType**

  required

  Its type, as checked from its bytes.

  string

  **size**

  required

  Its size in bytes.

  integer

  **sha256**

  required

  Sha256 of its bytes, hex-encoded, lowercase.

  string

  /^\[0-9a-f]{64}$/

  **pages**

  A PDF’s page count, as checked from its bytes.

  integer

  \>= 1

  **notShown**

  Set when the model isn’t shown it, and reads a line naming it instead: `type` (not a type a model is shown), `size` (over its type’s limit), `model` (the agent or its model doesn’t take images and PDFs), `limit` (over a call’s or a list’s limits), `store` (no file store), `gone` (no longer stored), `changed` (not the bytes that were checked), `refused` (the model couldn’t read it when it was attached), `storage` (a tool’s store found the tenant’s storage full), `reading` (what the model is sent in its place, an image or a text made from it, isn’t made yet).

  string

  Allowed values: type size model limit store gone changed refused storage reading

- **object**

  object

  **notStored**

  required

  Why nothing was stored: `type` (not a type a model is shown, or the bytes aren’t the type they claim), `size` (over its type’s limit), `limit` (the call has stored 10 files), `storage` (the tenant’s storage is full). The tool returns it as the file’s `notShown` reason.

  string

  Allowed values: type size limit storage

##### Example

```json
{
  "file": {
    "type": "kindgi.file",
    "notShown": "type"
  }
}
```

### 400

`bad-input`: `Kindgi-File-Name` is not percent-encoded UTF-8.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 404

`tool-file-token-not-found`: no tool call’s files match the bearer (none sent, an unknown token, a wrong secret, and a call that doesn’t store files alike), or this runtime stores no files.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 409

`tool-file-token-closed`: the call has answered, its time has passed, or its run has ended. `tenant-closing`, `tenant-suspended` (`details.state`) or `project-suspended`: nothing runs where the run is, so nothing was stored. Told only for a token that matches.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 413

The request body is over the API’s limit (`request-too-large`; `details.maxBytes` says how much).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 429

`rate-limit-exceeded`: too many requests from this client in a minute, counted before the token is looked up, so nothing was stored. `Retry-After` says when to store the file again.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 503

`tenant-state-unavailable`: the run’s tenant’s state couldn’t be read, so nothing was stored. `tool-files-busy`: the runtime’s memory for files had no room for the bytes in time, so nothing was stored. `Retry-After` says when to store the file again.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [Kindgi 0.4.0](https://docs.kindgi.com/v0.4.0/releases/0.4.0.md)
- [Error code `bad-input`](https://docs.kindgi.com/v0.4.0/reference/errors.md#bad-input)
- [Error code `project-suspended`](https://docs.kindgi.com/v0.4.0/reference/errors.md#project-suspended)
- [Error code `rate-limit-exceeded`](https://docs.kindgi.com/v0.4.0/reference/errors.md#rate-limit-exceeded)
- [Error code `request-too-large`](https://docs.kindgi.com/v0.4.0/reference/errors.md#request-too-large)
- [Error code `tenant-closing`](https://docs.kindgi.com/v0.4.0/reference/errors.md#tenant-closing)
- [Error code `tenant-state-unavailable`](https://docs.kindgi.com/v0.4.0/reference/errors.md#tenant-state-unavailable)
- [Error code `tenant-suspended`](https://docs.kindgi.com/v0.4.0/reference/errors.md#tenant-suspended)
- [Error code `tool-file-token-closed`](https://docs.kindgi.com/v0.4.0/reference/errors.md#tool-file-token-closed)
- [Error code `tool-file-token-not-found`](https://docs.kindgi.com/v0.4.0/reference/errors.md#tool-file-token-not-found)
- [Error code `tool-files-busy`](https://docs.kindgi.com/v0.4.0/reference/errors.md#tool-files-busy)
- [Every error code](https://docs.kindgi.com/v0.4.0/reference/errors.md)