ONBF
DocumentationFiles

Files — artifacts in a conversation

Markdown

Artifacts include both files the user attached and files your agent delivered. Browse their metadata with ONBF Tools, then use short-lived HTTPS links for the bytes.

Transport

With MCP your agent calls these tools itself; with the HTTP API your backend makes the calls. The tools are identical.

#What artifacts are

An artifact is a file stored in the current conversation. direction: "from_user" means the user attached it; direction: "from_agent" means your agent delivered it. Artifacts persist across runs in that conversation.

  • Reading a file the user sent — the webhook already carries input.files[], and your agent can also find it later with list_artifacts + get_artifact.
  • Delivering a file that's already online — your agent calls upload_artifact_from_url with a public HTTPS URL and ONBF fetches it.
  • Delivering a file it produced itself — your agent calls get_artifact_upload_info and sends the bytes to the link it gets back.

#List and download files

list_artifacts argumentMeaning
directionOptional from_user or from_agent; omit for both.
kindOptional image, document, data, archive or other.
queryOptional case-insensitive filename substring.
limitDefaults to 50; maximum 100; newest first.

The list returns artifactId, filename, kind, mimeType, sizeBytes, direction and createdAt, without download URLs. Passing one artifactId to get_artifact returns its metadata plus a fresh signed downloadUrl. That URL is short-lived and purpose-bound: it's fetched over plain HTTPS, and a new one is requested once it expires.

#Deliver a file from a URL

When the file is already available at a public https:// URL, upload_artifact_from_url is the whole delivery: ONBF fetches it server-side, blocks private and internal destinations, validates its real type and size, and returns an artifactId once it's in the conversation.

#Deliver a file your agent created

For a file that only exists inside your agent's runtime — a PDF it just generated, a chart it rendered — ONBF hands out an upload link instead of accepting the bytes through a tool call. Your agent calls get_artifact_upload_info, then its runtime sends the bytes straight to the returned uploadUrl.

Why the bytes travel separately: Tool calls carry structured JSON, not megabytes of binary. Splitting it keeps the file transfer on plain HTTPS, so a large delivery can't stall or bloat a tool call. The upload link is single-purpose and expiring, and once it accepts a file that file is already visible in the conversation — there's no finalize step.

For developers: upload raw bytes by hand

Only needed if you're implementing the upload yourself rather than letting your agent's platform do it. POST multipart/form-data with a single field named file. Don't send an Authorization header — the credential is already inside the URL — and don't set the multipart Content-Type boundary manually. The same link accepts multiple files until it expires or hits a quota.

Complete raw-byte upload

bash
export ONBF_BASE="https://onbf.ai"
export ONBF_TOKEN="onbf_sess_FROM_WEBHOOK"

UPLOAD_URL=$(curl -s "$ONBF_BASE/api/passport/v1/tools/get_artifact_upload_info" \
  -H "Authorization: Bearer $ONBF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' | node -p 'JSON.parse(require("fs").readFileSync(0,"utf8")).uploadUrl')

curl "$UPLOAD_URL" -F "file=@./report.pdf"

#Limits & access

  • Maximum 25 MB per file and 50 files per conversation.
  • Supported types include common images, PDF, text/CSV/Markdown, JSON, ZIP and Office documents.
  • All artifact tools are run-session-only. Deliver tools require conversation:write; read tools require conversation:read.
  • The run credential selects the user and conversation, so your agent can't reach another conversation's files — a foreign artifactId returns found: false.

#Who calls the file tools

Nothing for you to build. Once your platform is pointed at ONBF's MCP server, your agent already has the file tools in its tool list and does the calling itself, mid-run, whenever it decides to. There is no per-tool setup and no code on your side — connecting happens once on the MCP transport page.

The one thing MCP never carries is the file itself: upload and download URLs are fetched over plain HTTPS by whatever is holding the bytes.

Files — artifacts in a conversation · ONBF