feat(upload): Resumable uploads

[jjbayer]

Updates the spec on how to upload large files via the /upload endpoint.

Closes: INGEST-777

[linear-code]

INGEST-777

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Oct 19, 2026 7:33am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-docs	Ignored	Preview	Oct 19, 2026 7:33am UTC

[github-actions]

Please update the IS YOUR CHANGE URGENT? section of the PR description:

• Select exactly one option.
• If you selected an urgent or other deadline, provide the date as YYYY-MM-DD.

This information helps the Docs team prioritize your review.

[cursor]

The plan checks that the new upload guide is reachable.
It also checks that the parent attachments page still loads.
It watches 404s and client errors.
An issue escalates when those 404s appear or client errors rise.

Monitoring in production

Services: develop-docs.

Mention @change-monitor in a comment to update the plan.

Plan

What changed

Readers of the attachments spec now follow a link to a new resumable-upload guide for large files.
The new page tells SDKs to honor chunk-size headers, resume with HEAD, send X-Decoded-Content-Length, and use only the final Location as the placeholder.
This change is live after a production deploy of develop-docs.
The path match is develop-docs/ MDX only. The Vercel project develop-docs ships it.

Risk

A broken page or a bad link returns 404 for the new guide.
SDK authors then cannot follow the large-file upload protocol.
The attachments index can also fail to render if the remaining spec is invalid.
Incorrect protocol text cannot be seen in site telemetry.

Intended effect

The new guide must load at /sdk/telemetry/attachments/upload/.
confirmed is any docs.page.load count above zero on that path.
absent is the parent attachments page still loading while this path stays at zero and sdk/telemetry 404s rise.
If the parent path stays near four loads and 404s stay at zero, leave intended effect unknown. Traffic is too low to prove a miss.

Signal	Baseline	Rule	Source
docs.page.load on path */sdk/telemetry/attachments/upload*	0 in 2026-10-12T08:29:00Z to 2026-10-13T08:29:00Z. This path is new.	Hold is zero. Confirmed if the count rises above zero.	Sentry metrics, org sentry, project develop-docs. Query sentry.environment:production path:*/sdk/telemetry/attachments/upload*. Field sum(value, docs.page.load, counter, none).

Regression watch

A bad MDX page or a broken link 404s the attachments tree.
Client errors are the symptom on-call would see if the page crashes.
The parent attachments path is the sibling that this diff edited.
Daily error counts were lower on the weekend. A Saturday drop is not a success.

Signal	Baseline	Rule	Source
docs.page.not_found for requested_path matching sdk/telemetry	0 in 2026-10-12T08:29:00Z to 2026-10-13T08:29:00Z	Detected if the count rises above zero.	Sentry metrics, org sentry, project develop-docs. Query requested_path:*sdk/telemetry* environment:production. Field sum(value, docs.page.not_found, counter, none).
Production error events vs page loads	59 errors and 2360 docs.page.load counts in 2026-10-12T08:29:00Z to 2026-10-13T08:29:00Z. Ratio 2.5%. Complete UTC days 2026-10-06 through 2026-10-12 ranged 8-67 errors per day.	Detected if a complete UTC day rises above 67, or a rolling 24h error-to-load ratio rises well above 2.5% while page loads hold.	Sentry errors, query environment:production, field count(). Page-load denominator is docs.page.load with query environment:production.
docs.page.load on path */sdk/telemetry/attachments*	4 in 2026-10-12T08:29:00Z to 2026-10-13T08:29:00Z. Volume is low.	Detected if this count falls to zero while sitewide docs.page.load still holds near 2360 per 24h.	Sentry metrics. Query path:"*/sdk/telemetry/attachments*" sentry.environment:production. Field sum(value, docs.page.load, counter, none).
Sitewide docs.page.not_found	5 in 2026-10-12T08:29:00Z to 2026-10-13T08:29:00Z. Paths were sdk/foundations at 3 and self-hosted/experimental at 2.	Detected if a 24h total rises well above 5, or a new sdk/telemetry bucket appears.	Sentry metrics. Query environment:production. Group by requested_path. Field sum(value, docs.page.not_found, counter, none).

Not observable

Whether SDK authors send the new protocol to ingest is not visible on this site.
This change does not ship the upload endpoint.
Missing in-page anchors do not emit docs.page.not_found.

[tobias-wilfert]

Other than the small nit looks good.

[tobias-wilfert]

Should be Upload-Chunk-Granularity instead of Upload-Granularity. Changed this now.

[tobias-wilfert]

Wondering if it makes sense to include a summary of common possible errors, chunk to small, not aligned, to large, wrong offset etc?

[tobias-wilfert]

See comment about the error codes.