---
title: "Upload a knowledge file"
method: POST
path: "/v1/accounts/{accountId}/business-agent/files"
tags: ["Business Agent"]
---

# Upload a knowledge file

`POST /v1/accounts/{accountId}/business-agent/files`

Accepted types: pdf, doc, docx, png, jpg, jpeg, plus csv and xlsx when Meta enabled
extraction on the asset. Meta's limit is 100 MB. Two ways to send the file:
- JSON `{ url, fileName }`: Zernio downloads the file (public https URL, no redirects,
  capped at 100 MB) and forwards it. Use this for anything above a few megabytes.
- multipart form-data with a `file` part (and an optional `fileName`): bounded by the
  request body limit of about 4.5 MB; larger uploads must use the `url` form.
Not idempotent.

## Path parameters

- `accountId` string, required

## Request body

- object
  - `url` string, uri, required — Publicly downloadable file URL.
  - `fileName` string — Defaults to the last path segment of the URL.

## Response `201`

File uploaded

- BusinessAgentKnowledgeFile
  - `id` string, required
  - `file_name` string, required

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `403` — Inbox add-on required, the WhatsApp token lacks the Business Agent permissions (code reconnect_required), or the merchant has not accepted the Meta Business Agent terms in WhatsApp Manager (code business_agent_terms_not_accepted).
- `404` — Account not found, or no agent exists on the number yet or the referenced item does not exist (code business_agent_not_found).
- `413` — File larger than 100 MB (code payload_too_large). A multipart body above the request limit is rejected by the host before the route runs.

## Changes

- **2026-09-25** `2c04683ce694` — 12 info
  - added the optional property `details/adAccountId` to the response with the `400` status
  - added the optional property `details/adAccountId` to the response with the `403` status
  - added the optional property `details/adAccountId` to the response with the `404` status
  - added the optional property `details/createdObjects` to the response with the `400` status
  - …8 more
- **2026-09-16** `3e6ddf2a99ea` — 3 info
  - added the optional property `details/budgetScope` to the response with the `400` status
  - added the optional property `details/budgetScope` to the response with the `403` status
  - added the optional property `details/budgetScope` to the response with the `404` status
- **2026-09-15** `0dba7d004d75` — 6 info
  - added the optional property `details/quotaExhausted` to the response with the `400` status
  - added the optional property `details/quotaExhausted` to the response with the `403` status
  - added the optional property `details/quotaExhausted` to the response with the `404` status
  - added the optional property `details/quotaScope` to the response with the `400` status
  - …2 more
- **2026-09-09** `41eff0cffb2d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/accounts/:accountId/business-agent/files/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/b2325332041a?raw)