Omniscio

Share via CLI (publish, list, revoke, delete from a script or AI)

The share endpoints on the local CLI control server at http://127.0.0.1:19519 let any tool that can make an HTTP request publish files or pasted content as shareable links, list existing shares, inspect, edit, protect, send, republish, revoke or delete a share.

On this page

What it is

These endpoints mirror the renderer-side IPC handlers exactly — same publish pipeline, same path allow-list, same content-hash dedup, same Firebase upload, same share_links table — so a CLI publish is indistinguishable from an in-app publish at the data layer. The only telemetry difference is sourceType: 'cli' on the share_artifact_publish event so the Stats view can split CLI traffic from in-app traffic.

For the user-facing flow (paste modal, file peek toolbar, supported types, limits, security model), see share-artifacts.md. This page is the CLI-caller reference: route shapes, body schemas, status codes, and curl recipes. It documents publish, list, revoke, delete and refresh-video-pages in full; the same route family also serves session, digest and fork shares, mentions, comments, share status, in-place edits (PATCH /share/:token), password protection, republish, send, and a reaper action.

Where to find it

There is no screen for this — it is the reference for the local control server an outside script or AI calls. The token such a caller needs is created and regenerated in Settings → CLI Control.

How it behaves

Authentication

Every share endpoint requires the Omniscio bearer token in the Authorization header. The token is auto-generated at first launch and stored at ~/.amc/cli-token (%USERPROFILE%\.amc\cli-token on Windows) with OS-level file-permission hardening (mode 0600 on Unix, ACL-restricted on Windows). Settings → CLI Control shows the token and offers Regenerate.

Never echo the token to chat, logs, or terminal output. Call the endpoints through the amc-api.mjs helper, which reads the token file in its own process (so the value never appears in argv, environment dumps or a command substitution) and sends the Authorization header for you. It works the same in bash and PowerShell; write the route without its leading slash:

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" <METHOD> <route> [json-body | @file | @-]

If a token leaks (curl -v in chat, accidental log line, screenshot), regenerate it immediately at Settings → CLI Control.

Endpoints

POST /share/publish — publish a file or pasted content

Auth: bearer token in Authorization header (query-string ?token= is rejected, like every other mutation route). Body cap 1 MB at the dispatcher level.

Rate limit — publishing has its OWN per-session budget (12/minute), NOT the shared mutation pool. It used to sit on the global 10-mutations-per-minute bucket shared by every session and every mutating route, so another session's unrelated writes could refuse your publish after only two or three artifacts. It now has a dedicated per-session budget — your own publishes are the only thing that can exhaust it. POST /report-template/render shares that same budget (it performs the same publish). Revoke and delete still use the shared mutation pool.

A refused publish returns 429 with an honest Retry-After (seconds until a slot actually frees, not a flat 60) plus a retryAfterSeconds body field — read one of those instead of guessing a sleep interval. Some clients hide response headers: PowerShell 5.1's Invoke-RestMethod raises a terminating error on a 429 and discards them, so read the body field (or catch the exception and inspect $_.Exception.Response).

The budget is keyed on your session's PROVEN identity, so rotating the X-AMC-Source-Session-Id header does not grant a fresh one.

Encoding — prefer path over content. For a local file, send its path: Omniscio reads the bytes server-side as UTF-8, so a wrong-encoding read on the caller's side (e.g. PowerShell Get-Content -Raw, which defaults to Windows-1252 — not UTF-8) cannot garble multibyte characters (em-dashes, bullets, curly quotes, emoji). If you must send content, read and transmit it as UTF-8 (PowerShell: [IO.File]::ReadAllText($p,[Text.Encoding]::UTF8) plus a UTF-8 byte body). On suspected double-encoding the response adds a non-fatal warning (see below) — it never rewrites your content. Always verify the LIVE url, not the local file.

Body schema (JSON, exactly one of path / content required):

field type required notes
path string (1–2048 chars) XOR with content Absolute path to a file inside an active session's workdir (only the CALLING session's own workdir when it sends X-AMC-Source-Session-Id), ~/Claude, the calling session's own scratch folder ($AMC_SESSION_TMP — the session your token proves owns it — an agent's own session token proves its session, and the full-trust key claims it with X-AMC-Source-Session-Id; a credential that proves no session, such as a paired API key, never claims one from that header), a folder the user granted the app, or Omniscio's published-pastes dir. Symlinks are resolved before allow-listing. A refusal lists the exact roots it accepted in allowedRoots An H.264 MP4 (.mp4 / .m4v) publishes as a video — see Videos and live films
content string (1–2 MB) XOR with path Inline UTF-8 content to publish — staged under <userData>/published-pastes/<uuid>.<ext> before going through the pipeline. Refused with 403 for an agent-session / in-app-session token — those callers publish by path only
contentType 'html' / 'markdown' / 'text' / 'react' optional Omitted → text, EXCEPT a full HTML page (one opening with <!DOCTYPE html or <html), which is refused with a 400 rather than published as its own source code — send html to publish it as a page, or an explicit text to publish the source on purpose. Drives the staging-file extension and the share-page renderer. 'markdown' (or a path ending in .md) renders through Omniscio's shared markdown renderer — full GFM incl. tables, task lists, footnotes and highlighted code, HTML comments dropped, raw HTML sanitized — so never pre-convert markdown to HTML yourself. 'react' stages a .tsx and runs through the React/JSX runtime (same as the paste modal's React choice) — so you can publish a live React component from inline content, not only from a .tsx file by path
label string (≤ 200 chars) optional Display label in the Settings → Sharing list. Defaults to the source filename when omitted
expiresIn int seconds (60 to 60 × 60 × 24 × 365), or "never" optional Defaults to 30 days (2592000) when omitted — never to no expiry. Pass 3600 for 1h, 86400 for 1d, 604800 for 7d, 2592000 for 30d, 7776000 for 90d, 15552000 for 6 months, or "never" for a link with no expiry. The reply's data.expiresAt states the date (null = no expiry).
title string (≤ 200 chars) optional Browser-tab title + link-preview (OG/unfurl) title. Also the visible page <h1> on a framed share (markdown / text / code / image) — but a full-bleed html / react share (the default) has no chrome, so there title sets only the tab + unfurl card, never a visible on-page heading. label stays the smaller subtitle. Defaults to the source filename
fullBleed boolean optional Chromeless, viewport-filling render — no 960px frame, no heading, no footer. Honored for html / react / image only; ignored (framed) for every other kind. Defaults ON for html / react (a self-contained page owns the whole surface), OFF for everything else — pass fullBleed:false to force the framed reading view on an html/react share
background string (≤ 64 chars) optional Full-bleed backdrop colour — hex (#rgb/#rrggbb/#rrggbbaa) or rgb()/rgba() only; anything else is dropped for an automatic backdrop (a blurred copy of the image for images, a theme-aware neutral for html/react). Read only when fullBleed is honored for the kind
markdownStyle 'omniscio' / 'book' optional Markdown pages only. Which reading skin the page wears: omniscio (the default — the aurora backdrop, the Geist brand font and the orb + gradient wordmark, plus an “On this page” outline on any document with two or more sections) or book (the classic paper-column report style). Any other value is refused with a 400 naming the valid styles. Ignored for every other kind. Part of the dedup key, so switching skins mints a fresh link. GET /report-template/styles lists each skin with a when-to-use note under data.markdownStyles
raw boolean optional Hand back the FILE rather than a page about it: the link returns the artifact’s own bytes, typed from its extension and named after it, so a recipient (or curl) gets the file. Omitted → decided by the file — a data file (.json .csv .tsv .txt .xml .log) hands itself back and everything else keeps its page; pass raw:false to force a page, or raw:true to force the file. Only meaningful with path. An extension the shared table cannot serve is refused as unsupported-type
commentsEnabled boolean optional Override the global comments default for this share. true enables the comments sidebar, false disables it regardless of the user's shareCommentsDefaultOn setting. When omitted the share inherits that setting. With shareCommentsDefaultOn off (Share comments switched off), true still publishes no comment box
teamChatChannelId string (≤ 100 chars) optional Link this share to a Team Chat channel so the Cloud Function cross-posts new comments as thread replies. The channel must already exist. Persisted on the DB row + mirrored to Firestore; only applied to new publishes (ignored on dedup hits)
shareId string (1–256 chars) optional In-place update — the share's PUBLIC ID (the value a publish returns as data.shareId; it is the last path segment of the link, so it is not a secret and not a credential). Send it to refresh THAT share (same public URL, new content) instead of minting a fresh link. The target must be a live (non-revoked, non-expired, published) artifact share; a thread / digest / unknown id is a 400 No such active share to update. It replaces like with like: a page share takes a page, a video share takes a new video (see Videos and live films) — either mismatch is a 400. Its existing expiry is preserved (expiresIn is ignored on an update). It also has to still be live when the update finishes: a share deleted, revoked or expired while the update was uploading is refused with a 409 share-deleted-mid-publish, the page just uploaded is removed, and the link stays gone — an update never brings a dead share back, and it never revives one that had already expired. The response returns the SAME url with updatedInPlace: true; on an old-relay fallback a page update mints a new link + retires the old (updatedInPlace: false), while a video update is refused instead. What authorizes the replace is the CALLER, never the id: only the full-trust CLI token may send this field — a scoped agent or cloud-session token is refused with a 403 (see The share token is an address, not a key)
updateToken string (1–256 chars) optional Deprecated alias of shareId — same value, same rules, kept so existing callers keep working. Send ONE of the two; sending both with different values is a 400

Success response (200):

{
  "ok": true,
  "data": {
    "shareId": "a1b2c3d4e5f6a7b8",
    "token": "a1b2c3d4e5f6a7b8",
    "url": "https://shares.omniscio.com/s/a1b2c3d4e5f6a7b8",
    "publicUrl": "https://shares.omniscio.com/s/a1b2c3d4e5f6a7b8",
    "artifactType": "image",
    "reused": false,
    "contentHash": "9f2b…",
    "sizeBytes": 22698,
    "expiresAt": "2026-06-13T12:34:56.000Z"
  }
}

reused: true means the SHA-256 content hash matched an existing active share; no second upload happened and the existing shareId / url were returned. artifactType is the share row's own artifact kind — one of 'html', 'markdown', 'svg', 'image', 'pdf', 'text', 'code', 'react', 'pasted-text', 'mc-board' — the same value GET /share/list reports as artifactKind for that token. A video publish answers 'html' (a video share's row IS its html viewer page) plus isVideo: true, so filter the list by the kind you were answered with and a video comes back with the rest. updatedInPlace appears only when you passed shareId (or the deprecated updateToken): true = the SAME link now serves your new content; for a page, false = the relay could not reuse the token, so a fresh link was minted and the old one retired (read url for the new link); for a video it is always true, because a relay that cannot reuse the token is refused rather than answered with a second link.

data.shareId is the share's public id, and data.token carries the same value as its deprecated alias — read either; new code should read shareId.

The share token is an address, not a key

data.shareId (the same value data.token has always carried) is the share's public id: the same characters are the last path segment of url and publicUrl, so anyone who has the link has the id. That is by design — it names the share, it does not unlock it. You pass it back as shareId to say WHICH share to replace; what authorizes the replace is the CALLER, checked twice:

  • On this computer — an in-place publish (on /share/publish and /report-template/render alike) is refused 403 unless the bearer is the full-trust CLI token. No bearer, or the share id itself sent as one, is a 401; a scoped agent or cloud-session token is a 403.
  • At the share host — the in-place upload is signed only for a signed-in Omniscio account that OWNS the share (not your share otherwise), and the public share page answers a write with 405.

Measured on a throwaway share on 2026-11-08: every one of those refusals held and the page kept serving its original bytes. So a forwarded link can be read, never overwritten — knowing a share's id buys a caller nothing.

contentHash + sizeBytes describe the blob this call actually STORED, and match what GET /share/list reports for the token. They are the way to verify an in-place update landed: ok: true tells you the call succeeded, not that the bytes you sent are the ones now being served — so on an in-place publish, compare sizeBytes against your source and treat a mismatch as a failed refresh. Both are absent on a reused: true dedup hit, where nothing new was written.

When the user's Open shares in app setting (sharesOpenInApp) is ON, data.url is swapped to a deep-link URL (omniscio://share/<token>) that opens the share in Omniscio's built-in viewer instead of the browser. data.publicUrl always contains the HTTP URL regardless of the setting. Callers that always want the browser URL should read publicUrl; callers that want the user's preferred link should read url.

When the user has also enabled Show new shares automatically (sharesAutoOpenOnCreate, opt-in default OFF, sub-toggle of sharesOpenInApp), a successful publish additionally raises a one-click "Go there" toast on the user's screen via the agent-foreground nav-suggestion path (suggestAgentNavigation()). The toast is never a forced view-switch — if the user is in another app it becomes a durable inbox card instead. The toast carries only the share token so an arbitrary URL can never be coerced into the viewer. Toasts coalesce per source-session (a looping agent bumps one toast, latest label wins). This side-effect is transparent to callers: the publish response shape is unchanged.

A non-fatal warning string may appear alongside data when you publish via content and the text looks double-encoded (mojibake) — e.g. an em-dash arriving as the three chars â€" because the file was read in the wrong code page before upload. The share still publishes; the warning is advisory. The fix is to re-publish by sending the file path (read as UTF-8) instead of content. The server never auto-repairs the content (that would corrupt text that legitimately contains those characters). Genuinely-invalid UTF-8 is still rejected with a 400 earlier in the pipeline. Only content is scanned — a path publish never carries this warning.

The same warning also carries what a render of your published page found. After the artifact is live, Omniscio loads it once offscreen at phone size and reports what it saw. It is advisory only — a finding never refuses, delays, or changes a publish, and a check that cannot run stays silent rather than claiming the page is fine. Three things get reported:

Finding What it means What to do
N of M blocks did not reach the rendered page A branded report's own prose is missing from the page a reader loads — usually a block written in a shape no style dispatches on. Two published reports lost 100% of their body this way and still returned success. Write blocks as {"p": "…"}; fix the shapes and publish again. A session token publishes a fresh share — an in-place shareId refresh needs the full-trust CLI token.
this artifact's own script threw while rendering Your page's JavaScript raised an uncaught error, so the reader sees only whatever had been drawn before it stopped. Fix the script and publish again. A session token publishes a fresh share — an in-place shareId refresh needs the full-trust CLI token.
the page is Npx wider than a 390px phone Content sits off the right edge, inside a frame a reader cannot scroll sideways. Let the layout wrap instead of fixing a width.

There is deliberately no "this page looks empty" warning. Judging emptiness by counting visible text was measured against every published artifact and was wrong every time it fired — a video, an animation and a design mockup all legitimately carry a few words — while missing the report that had actually lost its body.

Error responses:

Every refusal body carries code — a stable machine value to switch on — alongside error, the sentence to show a person, and a hint when there is one saying what to change. The table names each row's code; where a refusal's error is itself the whole sentence, both are given.

status code / error string cause
400 outside-allowlist Path doesn't resolve into an active workdir, ~/Claude, this session's scratch folder, a granted folder, or published-pastes — the body's allowedRoots is the exact list that was accepted
400 unsupported-type File extension not in the supported list (Office, archives, binaries); or a video that is not an H.264 MP4 (the body then carries a hint to convert it through POST /convert)
400 magic-byte-mismatch Extension says one thing, the file's first bytes say another
400 empty-file Zero-byte source
400 update-target-not-found — No such active share to update shareId doesn't resolve to a live artifact share (revoked / expired / digest / thread / unknown)
400 update-target-is-video / update-target-is-a-page shareId aimed at a share of the other kind — a video share only takes a video, a page only a page
400 screen-recording-not-replaceable A video shareId aimed at a screen recording — its page carries comments, a transcript and a thumbnail a rebuild would strip
409 video-share-not-published / video-share-expired A video shareId aimed at a share that is still publishing (retry once it is live) or has already expired (give it a new lifetime through PATCH /share/:token) — the request is well-formed and fails only on the target's state, so each says what to do instead
409 share-deleted-mid-publish shareId's share stopped being live while the update was still uploading — deleted, revoked, or expired. Nothing is served and the just-uploaded page is removed; the share does NOT come back. Publish it again to create a new share
400 custom-slug-unsupported — A custom link name is not available for a video share. customSlug sent with a video path
400 (zod parse error) Body validation failed — schema fields out of range, both path and content set, etc.
401 unauthorized Missing or invalid bearer token
403 Replacing an existing share in place requires the full-trust CLI token… shareId sent with a scoped agent or cloud-session token — publish a new share instead
404 not-found The video file named by path could not be read — it moved, or it is gone
409 sign-in-required / share-auth-refresh-failed / share-relay-auth-rejected The APP is not signed in to the cloud account publishing needs (or its relay token lapsed / the relay rejected it). Your token was FINE, so this is deliberately not a 401 and never carries the "use the global token" hint: sign in to Omniscio, then retry
413 size-cap Source exceeds the type's raw-bytes cap (22 MB image, 18 MB PDF) or rendered HTML exceeds 25 MB
429 Rate limit exceeded (12 artifact publishes/minute for one session) YOUR session published 12 artifacts in the past minute. Carries Retry-After + a retryAfterSeconds body field — wait that long rather than guessing. Another session's traffic can no longer cause this.
502 firebase-upload-failed Generic upload error — check Settings → Sharing → Firebase config and Omniscio's main.log
507 firebase-quota Over your account's share storage allowance — delete old shares in the Shares view, or upgrade to a paid plan
504 publish-timeout — Publishing is taking too long — please try again The publish ran out of its wall-clock budget — for a page, a budget sized to its payload at a 32 KiB/s floor (about 45 seconds at the smallest, a little over two minutes at the 25 MB cap); for a video, a budget sized to the file, up to 15 minutes. Nothing was published. A page's object uploads each carry their own bounded attempt that fits inside that deadline, so one slow upload can no longer eat the whole budget and a retry still runs; a page within the 25 MB cap completes in seconds. A 504 therefore means the storage host answered slowly repeatedly, not that the page was big. A video's budget scales with its size on purpose — a 26 MB file is allowed ~3.5 minutes because that is what it needs on an ordinary uplink — so on a video a 504 means the link stayed slower than 128 KiB/s for the whole attempt

Recipes:

Publish a file by path:

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST share/publish \
  '{"path":"C:\\Software Projects\\my-project\\screenshot.png","label":"Bug repro"}'

Publish inline Markdown with 24-hour expiration:

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST share/publish '{
    "content":"# Title\n\nSome **markdown**.",
    "contentType":"markdown",
    "label":"Notes",
    "expiresIn":86400
  }'

Publish inline HTML that never expires ("never" must be sent on purpose — leaving expiresIn out gives 30 days):

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST share/publish \
  '{"content":"<h1>Hello</h1>","contentType":"html","label":"Greeting","expiresIn":"never"}'

Publish a full-screen HTML dashboard with a custom title (no Omniscio frame). Note that html / react are full-screen by default now, so the "fullBleed":true below is explicit-but-redundant — kept here to show the field; pass "fullBleed":false instead when you want the framed reading view:

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST share/publish '{
    "content":"<div style=\"display:flex;height:100vh;align-items:center;justify-content:center\">Hi</div>",
    "contentType":"html",
    "title":"Live Dashboard",
    "fullBleed":true,
    "background":"#0b0e14"
  }'

Publish with comments enabled and linked to a Team Chat channel:

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST share/publish '{
    "path":"/path/to/report.md",
    "label":"Weekly report",
    "commentsEnabled":true,
    "teamChatChannelId":"channel-abc123"
  }'

Update an existing share's content in place (same URL) — regenerate the file, then point the share's own token at the fresh bytes:

# ...regenerate C:\...\report.html with new content at the SAME path...
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST share/publish \
  '{"path":"C:\\...\\report.html","contentType":"html","shareId":"a1b2c3d4e5f6a7b8"}'
# → { "ok": true, "data": { "url": "https://.../s/a1b2c3d4e5f6a7b8", "updatedInPlace": true, ... } }

Videos and live films

  • A video publishes by path — pass an H.264 MP4 (.mp4 / .m4v). It skips the page builder and goes to the one video publisher (the same one screen recordings use), after the same folder allow-list check as any file. The reply has the usual shape with artifactType: "html" — a video share's row is its html viewer page, so it lists as artifactKind: "html" too — plus isVideo: true, which is how you tell a video share apart. data.publicUrl opens a share page that plays it in the one video player. shortLink: true adds a short link, expiresIn works as for a page, and a retry carrying the same X-Client-Request-Id returns the first share — with the same sizeBytes and, when the first publish claimed one, the same shortUrl, so a caller that lost the first reply recovers the whole thing rather than a trimmed link — the retry record is kept per calling session (the X-AMC-Source-Session-Id the token proves or the header names), so one session reusing another's request-id string can never be handed that session's link. A retry that arrives while the first upload is still running waits for that upload and answers with its link — it neither starts a second upload nor mints a second share. The page it opens on is the Cinema share page: under the title it names who shared it (the signed-in account's name and photo, or initials) and the date it was first shared, with the Share button beside them — no "Video" label and no length (the player bar shows that). The name and photo are hidden when the publisher turns off Show my name on shared videos (sharesShowAuthorName, on by default), which leaves just the date. Download is in its Share menu and in the player's bottom bar. Each publish makes a new share: a video is never de-duplicated by content, so publishing the same file twice makes two links.
  • Refused before anything uploads (400 unsupported-type with a hint): another video format (.mov, .webm, .mkv, .avi, …), a file named .mp4 whose first bytes are not an MP4, or an MP4 whose video ffprobe reports as something other than H.264 (the one format every browser plays). Convert it with POST /convert ({ "inputPath": "<file>", "to": "mp4" }) and publish the MP4 that returns. Without ffprobe installed the MP4 publishes anyway, with a warning.
  • Chapters — add chapters: [{ "start": <seconds>, "title": "<label>" }, …] and the share page shows them as clickable chips under the title (a click jumps the video there; the playing chapter is marked). The list is sorted for you; it is refused with a 400 naming the field — before anything uploads — for a negative or non-number start, an empty or over-100-character title, an unknown key, two chapters in the same second, or more than 100 chapters. An empty list means no chapters. A page publish that sends chapters gets them ignored, with a warning.
  • Page-only fields (fullBleed, background, commentsEnabled, teamChatChannelId) are ignored for a video, with a warning; customSlug is refused.
  • A video share takes a new video IN PLACE — pass the new MP4 as path with shareId set to the share's token and the SAME link serves the new film: the token, https://.../s/<token> and its omnisc.io short link never change, so every link already sent keeps working. The page is rebuilt too (title, chapters and byline as you send them — re-send chapters or they are dropped, since they are not stored), the share keeps its own expiry, its shape and its short link, and updatedInPlace: true comes back. Refused with a 400 before anything uploads: a page into a video share (or a video into a page share), a screen recording (its page carries comments, a transcript and a thumbnail a rebuild would strip), and a free account with no room left for the new file. A share that is still publishing or has already expired is a 409 instead — both are well-formed requests failing on the target's state, not malformed ones; an expired share keeps its expiry on an update, so it would go on answering "Share Expired" — give it a new one through PATCH /share/:token. An update never removes the link: if the upload or the online record fails, the share stays up exactly as it was and the same call finishes the job when you re-run it. The one exception is a share that is no longer live when the update finishes — deleted, revoked or expired while the film was uploading. That is refused with a 409 share-deleted-mid-publish instead of reporting success, and nothing is removed: the link stays exactly as the delete left it. An update that outruns the route's budget is answered for what it actually did: once the new film has landed its page uploads finish on a short budget of their own, so the call answers ok: true when the page lands, or a failure saying the film is live and its page did not finish — never a 504 that reads as "nothing was published" while the link already serves the new film.
  • POST /share/:token/republish is not the video road — it rebuilds a share from its source file as a page, so a video share is refused there and pointed at shareId.
  • An older video share can get today's page on the same link — a share page is saved when the video is published, so a link sent before a page redesign keeps the old look. POST /share/refresh-video-pages replaces only the page; the link, its expiry, its title and the video stay as they were.
  • A large video takes a while — the route sizes the budget to the file: the time its upload needs at a 128 KiB/s floor, plus a minute of headroom, up to 15 minutes. It answers 504 if the budget runs out, with nothing published — except an in-place update, which answers for the work it had already committed (see above).
  • A page's uploads are budgeted against the request's own payload-sized deadline, not against a fixed upload timeout. Each page object — the thumbnail, the runtime document and the shell — is given a bounded attempt (its own bytes at a 32 KiB/s floor, between 30 and 120 seconds) that finishes well inside the route's budget, and the runtime document and the shell upload at the same time rather than one after the other. That pairing is why a page's publish time no longer scales with how many objects it stores, and why one slow upload can no longer turn a small page into a 504. The public link is gated on the share's mirror record, which is written only after both objects have landed, so neither is ever served before the other exists.
  • A film drawn live in code (canvas frames, an optional soundtrack) plays through the same player: fetch the player's script from GET /video-player/script (raw JavaScript, any session token), put it in a <script> tag in your HTML page, mount the film, and publish the page by path. Never build your own video controls.

Publish an MP4 with a short link:

curl -X POST \
  -H "Authorization: Bearer $AMC_CLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"C:\\Users\\me\\Claude\\launch-film.mp4","label":"Launch film","shortLink":true}' \
  http://127.0.0.1:19519/share/publish

A film drawn in code — the page carries the player script, then mounts the film:

<div id="film"><canvas id="frame" width="1280" height="720"></canvas></div>
<script>/* the text GET /video-player/script returned */</script>
<script>
  const canvas = document.getElementById('frame')
  const ctx = canvas.getContext('2d')
  const media = OmniscioVideoPlayer.createTimelineMedia({
    duration: 20, // seconds
    render: (t) => { /* draw the frame for time t (seconds) onto ctx */ }
    // audio: an <audio> element or URL — when given, it keeps time and pitch holds at any speed
  })
  OmniscioVideoPlayer.mount(document.getElementById('film'), { media, surface: canvas })
</script>

GET /share/list — list shares, one bounded page at a time

Auth: bearer token in Authorization header. Not rate-limited (read-only) but still bearer-gated because share rows expose public content URLs.

Query string:

param values notes
includeRevoked true / unset When true, revoked rows are included in the result
limit 1–500 Page size. Absent or malformed falls back to 100, never "no cap".
offset 0+ Rows to skip — 0 (the first page) when absent.

Success response (200):

{
  "ok": true,
  "data": {
    "shares": [
      {
        "id": 42,
        "token": "a1b2c3d4e5f6a7b8",
        "url": "https://shares.omniscio.com/s/a1b2c3d4e5f6a7b8",
        "label": "Bug repro",
        "scope": "conversation",
        "artifactKind": "image",
        "status": "published",
        "revoked": false,
        "createdAt": "2026-05-14T12:34:56.000Z",
        "expiresAt": null,
        "hasPassword": false,
        "...": "..."
      }
    ],
    "limit": 100,
    "offset": 0,
    "hasMore": false
  }
}

The page is ordered newest first. hasMore is the completeness signal: when it is true the table continues past this page, so walk on with ?offset= (offset + limit) until it is false. A full page is not the end of the list.

Field set matches share_links schema — see queries-share.ts for the exact column list — except passwordHash / passwordSalt, which never leave the process; the row carries hasPassword (a boolean) instead. The same stripped shape is returned by the renderer-side SHARE_LIST IPC handler.

Recipe:

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" GET "share/list?includeRevoked=true&limit=100&offset=0"

POST /share/:token/revoke — soft-disable a share

Auth: bearer token, 10 mutations/minute rate limit.

Marks the row revoked = 1 (keeps the DB row + the blob in Firebase storage but invalidates the URL — viewers see a 410-style "this share has been revoked" page). Use this for shares you might want to audit later: the row and the stored blob are kept, but the link is dead for good — there is no un-revoke, and POST /share/:token/republish refuses a revoked share with a 409. To put the same content back online, publish it again as a new share; that mints a fresh URL.

This is not a DB-only operation: the route first stamps the row expired, then awaits the cloud mirror write (syncShareMirrorChecked({ …share, revoked: true })) and only flips revoked = 1 locally once that write is confirmed. A 200 therefore does not by itself mean "the public URL is dead" — read the body.

Success response (200):

{ "ok": true }

Deferred response (200, not revoked) — the mirror write could not be confirmed, so the hosted page may still be serving the content. The local record is left expired (not revoked) so the 15-minute sweep retries the unpublish + revoke; retry the call:

{
  "ok": false,
  "deferred": true,
  "error": "The hosted share could not be confirmed revoked — it may still be served. The local record is marked expired so the periodic sweep retries the unpublish; retry the revoke."
}

A caller MUST check ok (and deferred) before treating the link as closed.

Error responses: 401 (no token), 404 (Share not found — the path reference matches no live row), 429 (rate limit), 503 (the app is signed out: "Sign in to Omniscio before revoking this share. Nothing was changed." — the row, its expiry and the hosted copy are left exactly as they were, so sign in and retry). The :token segment takes any of the three references a share answers to — canonical token, short code (omnisc.io/<code>), or custom link name — exactly as DELETE does below.

Recipe:

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST share/a1b2c3d4e5f6a7b8/revoke

DELETE /share/:token — hard-delete a share row

Auth: bearer token, 10 mutations/minute rate limit.

Deletes the DB row and tears down the hosted copy (stored bytes, cloud record, comments). The URL then answers 404 "Share Not Found". Irreversible.

Which reference the :token segment takes. A share answers to any of the three names the app prints for it: its canonical token, its short code (the omnisc.io/<code> link), or its custom link name. The segment is matched in that order, so the token always wins, and a short code or custom name resolves to the same share the token does. This is the reference the SaaS panel and the published links hand out — a DELETE /share/a1b2c3d4e5f6a7b8 closes the share behind https://omnisc.io/a1b2c3d4e5f6a7b8.

Success response (200):

{ "ok": true }

Error responses: 401 (no token), 400 (VALIDATION_FAILED — the segment matches no share on this machine AND cannot be a share token, so it is refused before any call to the hosting relay; pass one of the three references above), 403 (FORBIDDEN — the link belongs to another owner, so no retry will ever delete it: it was published by a different account, or it was handed to Omniscio as a tutorial video), 404 (Share not found), 429 (rate limit), 503 (the hosted copy could not be confirmed removed — retry the delete; or, when the app is signed out, "Sign in to Omniscio before deleting this share. Nothing was deleted." — the share and its expiry are left exactly as they were, so sign in and retry).

Recipe:

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" DELETE share/a1b2c3d4e5f6a7b8

POST /share/refresh-video-pages — put today's page on older video links

Auth: the owner's full-trust token only (~/.amc/cli-token); a session's scoped token gets 401. Counts against the 10 mutations/minute limit.

Rewrites only the page of published video-file shares, on their existing links. The link, its expiry, its title and the video file are never touched, and the page keeps the date the link was first shared — never the day of the refresh. It is a dry run unless the body says "dryRun": false.

Field Type Meaning
dryRun boolean, optional Default true: read each live page and report what would change, upload nothing
tokens string[], optional (1–500) Only these shares; leave it out to cover every live share on this computer

Each share comes back with one outcome:

  • refreshed (or would-refresh on a dry run).
  • skipped with a reason:
    • revoked, expired, not-published or not-found — the link isn't a live share.
    • not-a-video — the share isn't a video file.
    • recording — the share is a screen recording, which refreshes through its own re-share. A recording is recognised by its link, or by its video sitting in the screen-recordings folder, so an older link of a re-shared recording is skipped too.
    • already-current — the live page already shows today's design with the byline the publisher wants now (named, or date-only once Show my name on shared videos is off). A second run changes nothing; turning the name off and running it again takes the name and photo off every live video page.
    • has-chapters — the live page carries chapters. Chapters are not stored anywhere but the page, so a rebuild would lose them; the page is left as it is.
  • failed with a plain reason:
    • could-not-read-live-page — the live page could not be read, so nothing is rebuilt blind.
    • relay-returned-a-different-link — nothing was uploaded.
    • upload-failed.

Each call rewrites at most 20 pages and starts no new share after about 2 minutes. data.remaining says how many are left — repeat the call until it is 0. If sharing is signed out the batch stops instead of failing every share, and because a signed-out call can do none of its work it answers 401 with code: "SHARE_SIGN_IN_REQUIRED" — the partial batch (what it reached, and remaining) rides in data, so a loop that repeats while the answer is 2xx cannot spin on a signed-out install.

Success response (200):

{ "ok": true, "data": { "dryRun": true, "remaining": 0, "results": [
  { "token": "a1b2…", "outcome": "would-refresh" },
  { "token": "c3d4…", "outcome": "skipped", "reason": "already-current" }
] } }

Error responses: 400 (unknown field, or a token that isn't letters, digits and dashes), 401 (not the owner's token — or code: "SHARE_SIGN_IN_REQUIRED" when sharing is signed out and the batch could not start work), 429 (rate limit).

Recipe (look first, then refresh for real, repeating until remaining is 0):

node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST share/refresh-video-pages '{}'
node "$HOME/.claude/skill-content/omniscio-control/amc-api.mjs" POST share/refresh-video-pages '{"dryRun": false}'

Opening, capturing and refreshing a share in the app

Three more routes drive the in-app share viewer instead of the share itself: POST /share/:token/open asks the app to open a share in its viewer (a one-click "Go there" toast by default), and POST /share/:token/screenshot and POST /share/:token/refresh press the viewer's Screenshot and Refresh buttons for a share the desktop app already has open. POST /ui/open does not open shares. How they behave, who may call them and what each refusal means: Shares view § Pressing the viewer buttons from the CLI.

Agents publish on their own

These endpoints are also how the agents Omniscio starts surface what they make. Every session Omniscio spawns is instructed to publish a self-contained visual result — an HTML report, chart, dashboard, slide deck or diagram — as a share link as soon as it has one, without asking first. The agent writes the artifact to a file in its working directory and posts that path with a scoped token minted for its own session (never your full-trust token). A session running on a cloud box cannot send a path, because a path there names a file on your own computer rather than on that machine, so it sends the file's contents instead. Every link it mints lands in the Shares view, where you can preview it, rename it, set an expiry or password, or revoke it. The agent is told to hand you the public link rather than email the file, and never to push the artifact to GitHub or any external host instead.

The rules every publish obeys, and the security model behind them, continue on Share via CLI — part 2.

  • share-artifacts.md — the in-app flow with the same publish pipeline (paste modal + file-peek toolbar)
  • cli-control.md — the CLI control server's design, auth model, and full route catalogue
  • artifact-sharing.md — the sibling feature for sessions / messages / selections (different inputs, same share_links table)

Last verified 2026-11-09