` — decoded and stored (base64 data URIs only)
Each ingested tag is rewritten in place to standard attachment markup (`src=""` + `data-uuid` + `alt`), and from then on behaves exactly like an uploaded image: stored under the note's case, hashed, and served through a fresh signed URL every time the note is read.
**Why this happens:** stored notes and their version history should only reference content the system controls. An external URL can change or vanish after the note is written — silently altering what a historical note appears to say — and every read of a hotlinked image tells the third-party host who is viewing the note, and when. Ingestion pins the image bytes at the moment of writing.
Details worth knowing:
* **Idempotent** — images already carrying a `data-uuid` are left untouched, so re-sending content or appending to a note never re-downloads anything.
* **Deduplicated** — the same `src` appearing multiple times in one write is stored once, with every tag pointing at the same attachment.
* **Bounded** — at most **10 images per write** are ingested, within an overall time budget of \~30 seconds. Images beyond the cap are reported (see below), not silently dropped.
* **Reads never fetch** — ingestion only runs when content is written.
* Unresolved external images render as broken/blank in PDF and DOCX exports; the exporters never fetch remote URLs.
### When ingestion fails: `unresolved_images`
A failed image **never fails the write**. The original tag stays in the content exactly as sent, and the response gains an `unresolved_images` array describing each image that was left behind (the field is absent when everything ingested cleanly):
```json
{
"data": { "...": "the created/updated note" },
"unresolved_images": [
{
"src": "https://example.com/photos/device-front.jpg",
"reason": "Image request failed with status 404"
}
]
}
```
Common reasons: the host was unreachable or returned an error, the URL resolves to a blocked (internal) address, the content type is not an allowed image type, the image exceeds 25 MB, or the write contained more than 10 new images. `data:` URI srcs are truncated in the report to keep responses small.
An unresolved external image is retried the next time the note's full body is rewritten via `PATCH` (its tag still has no `data-uuid`, so it is a candidate again). Appends only scan the appended fragment, not the existing body.
### Example — create a note with an external image
```python
create = session.post(f"{BASE_URL}/notes", json={
"case_uuid": case_uuid,
"note_tag": "OSINT findings",
"note_data": (
"Profile photo published by the account:
" '
'
),
})
create.raise_for_status()
note = create.json()
# Always check for images the server could not ingest
for image in note.get("unresolved_images", []):
print(f"NOT ingested: {image['src']} — {image['reason']}")
```
### Example — append a locally generated image as a data URI
Useful for automation that produces charts or screenshots: no separate upload call, and the server extracts the base64 payload into an attachment instead of bloating the stored note.
```python
import base64
with open("timeline-chart.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
result = session.patch(f"{BASE_URL}/notes/{note_uuid}/append", json={
"note_data": f'Reconstructed timeline:
',
})
result.raise_for_status()
```
### Example — fall back to a direct upload when ingestion fails
If the server can't reach a source (for example, it requires credentials the server doesn't have), fetch the bytes yourself and use the upload endpoint, embedding the returned markup:
```python
import requests
result = session.patch(f"{BASE_URL}/notes/{note_uuid}/append", json={
"note_data": html_with_images,
})
result.raise_for_status()
for failed in result.json().get("unresolved_images", []):
if not failed["src"].startswith("http"):
continue
# Fetch with our own credentials/network access...
img = requests.get(failed["src"], timeout=30)
img.raise_for_status()
# ...store it as a note attachment...
upload = session.post(
f"{BASE_URL}/notes/{note_uuid}/images",
files={"file": ("image", img.content,
img.headers.get("Content-Type", "image/png"))},
)
upload.raise_for_status()
# ...and embed the attachment markup. (The original tag with the
# unreachable src is still in the note body; replace it with a full
# PATCH of note_data if you want it gone.)
session.patch(f"{BASE_URL}/notes/{note_uuid}/append", json={
"note_data": upload.json()["markup"],
}).raise_for_status()
```
***
## Upload an image to a note (recommended)
Uploads the image, hashes and stores it, records the attachment, and returns ready-to-embed `Scene photo:
{image['markup']}", }).raise_for_status() ``` *** ## Errors {% hint style="info" %} Automatic ingestion failures are **not** HTTP errors: the note write still succeeds (`200`/`201`) and each failed image is reported in the response's `unresolved_images` array instead. The statuses below apply to the explicit upload endpoints. {% endhint %} | Status | Body | Cause | | ------ | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | `400` | `{"message": "Unsupported image type"}` | Content type not in the PNG/JPEG/GIF/WebP allowlist. | | `400` | `{"message": "Image exceeds maximum allowed size"}` | Larger than 25 MB. | | `400` | `{"message": "Image file is empty"}` | Zero-byte upload. | | `400` | `{"message": "Invalid multipart upload"}` | Malformed multipart body on `/{uuid}/images`. | | `400` | `{"message": "Note is not linked to a case"}` | Upload target note has no case, so there is no storage location. | | `400` | `{"message": "Case storage not provisioned"}` | The case has no storage path yet. | | `400` | `{"message": "filename must not contain path separators", ...}` | `filename` contains `/`, `\`, or `..`. | | `400` | Fetch-specific message | `download-image-from-url`: unreachable URL, non-image content, blocked internal address, too large. | | `404` | `{"message": "Note not found"}` / `{"message": "Note not found for case"}` / `{"message": "Case not found"}` | Bad `note_uuid` / `case_uuid`, or the note is not in the given case. | | `401` | `Unauthorized` | Missing or invalid API key. |