Upload workflow

An AI tool gets a report into SnowDots in one of two ways:

• submit_content — one call, for HTML or Markdown up to 256 KB.
• create_upload → HTTP PUT → finalize_upload — for every PDF and for larger files, up to 25 MB.

Either way the result is a new, immutable version. Then submit_for_review hands it to a person.

list_inbox / get_context            (what's waiting, house style, client brief)
        │
create_artifact  ──or── list_artifacts (reuse an existing artifact)
        │
 ┌──────┴───────────────────────────┐
 │ small HTML/MD                    │ PDF or large file
 │ submit_content                   │ create_upload → PUT bytes → finalize_upload
 └──────┬───────────────────────────┘
        │
submit_for_review  →  get_publish_status
        │
a publisher approves and publishes in SnowDots

Before drafting

Call list_inbox to see what’s waiting, and get_context — with the client when known — for the agency guidelines, the client’s brief, recent work and open feedback. That context is team-only: follow it, never quote it to clients.

Small HTML or Markdown: submit_content

1. Create the artifact (or find an existing one with list_artifacts):

   // create_artifact
   { "title": "September performance report", "format": "html", "client": "brightline-dental", "type": "report", "reporting_period": "September 2026" }

2. Commit the content as a new version:

   // submit_content
   { "artifact_id": 42, "filename": "september.html", "content": "<!doctype html><html>…</html>" }

3. Submit it for review:

   // submit_for_review
   { "artifact_id": 42 }

PDFs and large files: the upload flow

1. Create or find the artifact. Its format is fixed: every version must match it.

   // create_artifact
   { "title": "Q3 board pack", "format": "pdf" }

2. Reserve an upload with the exact file metadata:

   // create_upload
   {
     "artifact_id": 43,
     "original_filename": "q3-board-pack.pdf",
     "mime_type": "application/pdf",
     "byte_size": 1834221,
     "checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
   }

   The response gives the upload id, the signed URL to PUT the bytes to, the content type and when the URL expires. Upload URLs are valid for 15 minutes.

3. PUT the bytes to the upload_url. No other authentication is needed — the signature is the credential.

   curl

   curl -X PUT --data-binary @q3-board-pack.pdf \
     -H "Content-Type: application/pdf" \
     "<upload_url>"

   JavaScript

   await fetch(uploadUrl, {
     method: 'PUT',
     headers: { 'Content-Type': 'application/pdf' },
     body: fileBytes,
   });

   A successful upload returns 204 No Content.

4. Finalize to commit the version:

   // finalize_upload
   { "artifact_id": 43, "upload_id": "<upload_id>" }

   SnowDots checks the size, the declared checksum and that the file really is a valid document of the artifact’s format, then returns the new version number and its SHA-256.

5. Submit for review with submit_for_review.

Upload rules

Rule	Detail
Formats	html (.html, .htm), pdf (.pdf), markdown (.md, .markdown)
MIME types	HTML: text/html, application/xhtml+xml · PDF: application/pdf · Markdown: text/markdown, text/x-markdown, text/plain
Consistency	The extension, MIME type and artifact format must all agree.
Size	At most 25 MB. byte_size must match the bytes exactly.
Checksum	Optional SHA-256 hex digest (64 characters), verified on finalize.
Expiry	Upload URLs expire after 15 minutes; reserve a new one if needed.

PUT responses

Status	Meaning	What to do
204	Stored.	Call finalize_upload.
409	Already finalized.	Call get_publish_status.
410	Upload expired.	Call create_upload again.
413	Body larger than declared.	Re-reserve with the right byte_size.
422	Size doesn’t match the declared size.	Re-reserve with the right byte_size.
403	Signature invalid.	Use the exact upload_url returned.

Caution

Only call finalize_upload after the PUT succeeded. If the file is missing it fails with “The uploaded file is missing.”

After submitting

The AI tool cannot publish or share. Finish by telling the user their draft is ready to review. Use get_publish_status to see whether it’s still in review, was published, or was returned with a reviewer note.

To answer feedback, read it with list_comments, push a new version, then resolve_comment with addressed_in_version. See Comments & feedback.