Upload local media

Get files from the user's machine into Artima without passing their bytes through the conversation, then use the stored files in drafts.

Ground rules

• This needs a shell. The upload is an HTTPS request that curl sends from the user's computer, so it needs a tool that runs shell commands. That means Claude Code, or Cowork running on the user's computer. If this session has no shell, or the shell cannot reach the Artima host because of sandbox network rules, say so plainly and offer one of these instead:
  • a public https:// link to the file, which upload_media can fetch (url);
  • uploading the files in the Artima app, then picking them from list_media;
  • giving the user the curl command to run themselves (step 4).
• No base64 for real files. upload_media with base64 sends the bytes through the conversation. Use it only for tiny files of about 20 kB or less, never for photos or video.
• Never claim an upload that did not happen. A file is in Artima only when the upload response lists it with status: "ready" and a url.
• Role. Uploading needs the Editor role or higher. get_upload_token refuses lower roles with a readable message; relay it and stop.
• Publishing is separate. This skill creates drafts. Scheduling or publishing needs the user's explicit yes to the exact post and time.

Limits

At most 20 files and 500 MB per request. Artima detects the type from the file's content, not its name. HEIC/HEIF, AVIF, TIFF, PDF and other formats are rejected even when renamed.

Workflow

1. Check the files locally

List the files with their sizes (for example ls -l) and check their real types (for example file). Then sort them out before uploading:

• HEIC or another unsupported image: tell the user and offer to convert it to JPEG in a temporary folder, for example with sips -s format jpeg in.heic --out /tmp/artima-upload/in.jpg on macOS. Never overwrite the originals.
• Too large: offer to downscale images, for example with sips -Z 4096. Video over 300 MB needs to be compressed or uploaded in the app.
• Anything else unsupported: leave it out and say why.

Agree the carousel order with the user. It is the order you will pass in mediaUrls.

2. Get an upload token

Call get_upload_token. It returns:

• token: upload-only, valid for 15 minutes, bound to the active workspace;
• uploadUrl: where to send the files;
• limits, and an example command.

Treat the token as a secret. Use it in the command, but do not repeat it in your messages or summaries.

3. Upload in one request

Send all files in one curl call, with one -F per file. Quote paths that contain spaces:

curl -sS -X POST "<uploadUrl>" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/Users/me/Desktop/launch/hero.jpg" \
  -F "file=@/Users/me/Desktop/launch/detail 2.png"

Always use the uploadUrl that the tool returned; don't type a host yourself. Split more than 20 files, or more than 500 MB, into several requests.

4. Read the result per file

The response is JSON with a files list. Partial success is normal:

• status: "ready": keep its url (and mediaId).
• status: "rejected": error.code is unsupported_media_type or file_too_large (with limitBytes). Tell the user which file and why.
• status: "error": a permission problem or a failed upload. Report the message.

HTTP 401 means the token expired: call get_upload_token again. HTTP 403 means a role or workspace problem.

Retry only the files that did not come back ready. Every successful upload creates a new library item, so sending a ready file again makes a duplicate.

If you cannot run the command yourself, give the user the exact command with the real uploadUrl, a <token> placeholder, and their file paths. Ask them to paste back the JSON response.

5. Files that are already online

For a public https:// link, call upload_media with url (up to 300 MB). It returns a durable url in the user's library. list_media (with nameFilter, pageSize up to 100, and hasMore for paging) finds files that are already in the library.

6. Attach to a draft

• New post: call create_draft_post with socialAccountId from list_accounts (never just a platform), text, postKind, and mediaUrls, which keep their order. Files ending in .mp4 or .mov are attached as video. Use postKind: "Reels" when the user wants an Instagram Reel.
• Existing post: update_draft replaces the whole media list, so pass every URL the post should keep, not only the new ones. On a plain draft it returns a newPostId; use that ID from then on.
• If the result has mediaRehostWarnings, tell the user which media did not attach.

7. Report

Then give the draft's post ID and first line. Ask before scheduling or publishing it.