---
title: "Upload one asset"
method: POST
path: "/reports/{id}/assets"
tags: ["Assets"]
---

# Upload one asset

`POST /reports/{id}/assets`

## Request

- Base URL: `https://commareports.com/api/v1`
- URL: `https://commareports.com/api/v1/reports/{id}/assets`
- Auth: HTTP bearer

Binary content travels base64-encoded in `content_base64` (a `data:` URL prefix is tolerated). Re-uploading the same `relative_path` replaces the prior asset. Limits: 25 MB per file (413), 250 MB total per report (413), 500 files per report (422). Requires edit access. Scope: `reports:write`.

## Request body

- AssetUploadRequest
  - `relative_path` string, required: e.g. 'images/hero.png' — no leading slash, no '.'/'..' segments, no '%', '?' or '#'.
  - `content_base64` string, required: Base64 bytes ('data:' URL prefix tolerated). Max 25 MB decoded.
  - `content_type` string: Defaults to application/octet-stream.

## Response `201`

Asset stored.

- Asset
  - `id` string, uuid, required
  - `relative_path` string, required
  - `mime` string, required
  - `size_bytes` integer, required
  - `created_at` string, date-time, required
  - `url` string, uri, required: Stable public URL.

## Other responses

- `400`: Malformed body or invalid field.
- `401`: Missing, invalid, revoked, or expired token.
- `403`: Token missing the required scope, or no access to the resource.
- `404`: Resource not found (also returned instead of 403 where existence must not leak).
- `413`: Payload exceeds a size limit (HTML > 5 MB; asset > 25 MB per file or > 250 MB per report).
- `422`: Semantically invalid (e.g. plan ceiling exceeded, per-report asset count over 500).
- `429`: Rate limit exceeded. Rate limit: per-token sliding window (plan-aware — Free 60 req/min, Pro 600, Team/Enterprise 6000 by default); 429 responses carry a Retry-After header.
- `500`: Unexpected server error.

---

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