Files & storage

Two different problems, two different stores, and the whole design follows from telling them apart:

  • Someone hands your agent a document. It lands on the platform's upload buffer, you get an opaque file id, and it disappears after 3 days.
  • Your agent produces something worth keeping. That goes in a data bucket your organization connected — addressed by a key you choose, kept until someone deletes it.
from im_sdk import ImCore, im_agent
 
 
@im_agent("archivar")
async def main(core: ImCore, data: dict) -> str:
    file_id = data["datei"]                       # an io.json input of "type": "file"
 
    # Read what the user uploaded.
    doc = await core.file_store.get(file_id)
 
    # Keep it past its 3 days: buffer → bucket, server-side.
    stored = await core.object_store.put_from_upload("archiv", file_ref=file_id)
 
    return f"{doc.output.filename} archiviert als {stored.output.key}"
Upload buffer (core.file_store)Data bucket (core.object_store)
Whose it isthe platform'syour organization's
Addressed byPortal file id (a uuid)object key you choose
Lifetime3 days, then pruneduntil someone deletes it
Grant needednonethe service and each operation
Written bythe upload surfacesyour agent
Read byany agent in that workspaceany agent granted the service

Getting a file to your agent

Declare the input

Add it to .im/io.json with "type": "file". That is what makes the Portal playground render an uploader for the field instead of a text box:

{
  "inputs": [
    { "name": "datei", "type": "file" },
    { "name": "frage", "type": "string" }
  ],
  "output": { "type": "multiline" },
  "example": {
    "inputs": { "frage": "Worum geht es?" },
    "output": "Es geht um …"
  }
}

A file input takes no example value, and validation exempts it: the only value you could write there is a file id from some other workspace or an invented one, and the playground would offer it as a default — which is how a run ends up failing on a file_ref that never existed while a real upload sat unused.

See The io.json contract for the rest of the shape.

Upload it

WhereHow
PortalThe playground's file field, or the workspace's Files list
CLIim-cli files upload report.pdf — prints the id on stdout, pipe-friendly
Your appPOST /api/external/v1/…/workspaces/{ws}/files with an org API key
im-cli files upload report.pdf          # → 2247c37d-…
im-cli run --input 'datei=2247c37d-…'

Files belong to a workspace, not to a run and not to an agent: every agent in that workspace can read every live file in it, and im-cli files list shows them all. The server enforces a 25 MB cap plus two independent allow-lists — the filename's extension and the sniffed content type must both pass, so renaming a binary does not get it in.

Agents that take several documents conventionally read a list under the input key files; that is what im-cli run --input 'files=["…","…"]' produces.

Reading a file

As bytes — core.file_store.get(file_ref)

result = await core.file_store.get(file_id)
 
result.output.text          # decoded when the bytes are text — "" otherwise
result.output.content_b64   # Base64 bytes, always
result.output.filename      # what the uploader called it
result.output.mime_type
result.output.size_bytes

.text is a convenience for the common case (CSV, JSON, plain text). A binary object — or one that simply does not decode — yields "", not an error and not None, so branch on the mime type rather than on the emptiness of .text; otherwise a PDF looks exactly like an empty file. The same contract holds for object_store's .text.

No service, and no grant. The buffer is the platform's own disk, so there is no third party to name and nothing to authorize against: the gateway resolves the ref against your execution's workspace, which is the entire tenancy story.

Without the bytes touching your process — document_parse

If all you want is the text, do not download it. Pass the ref and let the gateway fetch the bytes server-side:

result = await core.document_parse.partition(service="unstructured", file_ref=file_id)
text = result.text

Same for extract() and ocr(). This is the better default for anything large: the document never enters your agent's memory and never crosses the wire twice.

Keeping a file — put_from_upload

An upload expires. One call moves it into a bucket that does not:

stored = await core.object_store.put_from_upload("archiv", file_ref=file_id)
stored.output.key           # "uploads/2247c37d-…-report.pdf"

The bytes go buffer → bucket server-side — they never pass through your process, which is what makes archiving a 25 MB upload cheap. Omit key and the object is stored as uploads/<file-id>-<filename>, keeping the uploader's original name (sanitized: a name containing a slash would otherwise pick its own place in the bucket). Pass key= to file it your own way.

Like put, it is create-only: archiving never overwrites.

The data bucket — core.object_store

Service-addressed: the first argument is the name of a connected service, not a provider and not a bucket. Read which ones your agent has with im-cli agent services rather than guessing.

await core.object_store.put("archiv", key="berichte/q3.csv", content_b64=csv_b64)
 
text = (await core.object_store.get("archiv", "berichte/q3.csv")).output.text
 
page = await core.object_store.list("archiv", prefix="berichte/")
keys = [o.key for o in page.output.objects]
while page.output.next_cursor:
    page = await core.object_store.list("archiv", prefix="berichte/", cursor=page.output.next_cursor)
    keys += [o.key for o in page.output.objects]
MethodoutputNotes
get(service, key)ObjectOutput.content_b64, .text, .content_type, .size_bytes, .filename
stat(service, key)ObjectStatOutputmetadata only — the cheap "is it there / how big"
list(service, prefix=…, limit=…, cursor=…)ObjectListOutput.objects, .next_cursor (None on the last page)
put(service, key=…, content_b64=…)ObjectWriteOutputcreate-only — an existing key raises object_exists
replace(service, key=…, content_b64=…)ObjectWriteOutputwrites whether or not the key exists
put_from_upload(service, file_ref=…, key=…)ObjectWriteOutputbuffer → bucket, server-side; create-only
delete(service, key)ObjectDeleteOutputone key; .deleted is False when there was nothing there

list defaults to 100 entries per page and caps at 1000. The cursor is the store's own continuation token — opaque, pass it back verbatim.

Keys are relative to the service

Each connected service owns one prefix inside its bucket. The gateway adds it on the way in and strips it on the way out, so the key you send is the key you get back and no key you can write reaches another service's objects.

Refused before the store is ever touched: .., a leading /, empty segments, backslashes, control characters, unpaired surrogates, a key too long once the service prefix is added, and the reserved .im- namespace.

What list actually returns

Keys — not filenames. filename and content_type are None on every entry of a listing, because ListObjectsV2 carries neither, and a HEAD per entry would turn one listing into N round trips. What you get per entry is key, size_bytes, etag and last_modified.

That is usually fine, because the default key from put_from_upload already contains the original filename. But if you need the recorded filename or the content type, ask per object with stat() — and budget a call each.

Every operation is a separate grant

put and replace are different permissions on purpose: an agent granted only put can add objects to an archive and can never destroy one. Expect to be told which ones you have.

A call outside the granted set raises ImForbiddenError with POLICY_ACTION_NOT_GRANTED, and the error's context carries granted_actions — so the remedy is visible without opening the Portal:

from im_sdk import ImForbiddenError
 
try:
    await core.object_store.replace("archiv", key=k, content_b64=b64)
except ImForbiddenError as exc:
    (exc.context or {}).get("granted_actions")     # e.g. ["get", "list", "put"]

Errors

CodeRaised asMeans
file_not_foundImValidationErrorthe file id is unknown, expired, or from another workspace — deliberately indistinguishable
object_not_foundImValidationErrornothing at that key; another service's object answers the same way
object_existsImValidationErrorput / put_from_upload onto a live key — use replace
POLICY_ACTION_NOT_GRANTEDImForbiddenErrorthat operation is not granted (or the quota withdrew it)

The indistinguishability is deliberate in both directions: an error must never tell you that something exists somewhere you cannot reach.

delete is the exception to all of this — deleting a key that holds nothing is not an error. .deleted is False and the call succeeds, so a cleanup loop can safely run twice.

Limits

Upload size25 MB (FILES_MAX_KILOBYTES)
Upload lifetime3 days (FILES_TTL_DAYS)
Object read/write26 MiB per object, in and out
list page100 by default, 1000 maximum
Object key987 bytes (S3's 1024, less the service prefix the gateway adds)

For anything past the object ceiling the bucket is not the transport — write it where your agent already streams.

Notes for the operator side

What an admin configures (connecting a bucket, the connection check on save, the per-operation grants, the size cap, how the store is backed up) lives in the platform repository: docs/agent-data-bucket.md for buckets and docs/file-uploads.md for the buffer.