Skip to content
Kindgi

Store a file for a pack tool's call

View as Markdown
POST
/v1/tool-files
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

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Kindgi-File-Name
string

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

Request Bodyrequired

Section titled “Request Bodyrequired”

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

Media type*/*
string format: binary

Responses

Section titled “Responses”

200

Section titled “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 workspace’s storage is full).

Media typeapplication/json
One of:
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 workspace’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
Example
{
  "file": {
    "type": "kindgi.file",
    "notShown": "type"
  }
}

400

Section titled “400”

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

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “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.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “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.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

Section titled “413”

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

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

429

Section titled “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.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

Section titled “503”

tenant-state-unavailable: the run’s workspace’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.

Media typeapplication/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
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also