Public API

Embed cnfs files anywhere.

Galleries, AI assistants, oEmbed unfurlers, Discord bots — anything that needs to render your cnfs files publicly. Three credential flavors so you pick the trade-off that fits: the URL itself for shares, an opaque magic link for single files, or a path-scoped Bearer key for services.

REST playground Transforms playground GraphQL playground LLM prompt Markdown reference

Pick your credential

  • Share URLLive (phase 2)

    URL-only access. Optional password, expiry, max-uses, referrer allowlist. Best for galleries pasted into a webpage.

  • File tokenPhase 5

    Opaque magic link to one file. TTL-based. Best for one-shot embeds (newsletter image, Discord upload).

  • Public API keyPhase 6

    Bearer cnfs_pub_*. Path-scoped. Rate limits + CORS allowlist + per-day quota. Best for backend services.

What ships in v1

  • REST — listing, file fetch (range-aware), metadata. Live now.
  • Transforms — width/height (px or %), no upscaling, format negotiation, GPS-only EXIF strip default. Phase 3.
  • GraphQL — same auth, same listing helper, with DataLoader-batched thumbnails. Phase 4.
  • Inline playgrounds — Scalar for REST, GraphiQL for GraphQL, slider-driven preview for transforms.
  • LLM prompt generator — paste-into-Claude block scoped to a specific share or key. Phase 7.

Endpoint reference

GET/api/public/v1/share/<id>

Share metadata — label, path-prefix, capabilities, expiry.

GET/api/public/v1/share/<id>/files

Cursor-paginated listing with sort/filter/recursive controls.

GET/api/public/v1/share/<id>/file/<path>

Range-aware file fetch. Transform params land in phase 3.

GET/api/public/v1/share/<id>/file/<path>/meta

Metadata-only fetch — cheap pre-flight.

Security defaults

  • Path traversal — every request is normalized + scoped to the share's pathPrefix. .. escapes are rejected.
  • Constant-time password check — scrypt + timingSafeEqual.
  • Hotlink protection — optional referrer_allowlist per share.
  • Soft revoke — rotating a share's signing secret invalidates outstanding URLs in one stroke.
  • No path-existence leak — out-of-scope paths return 404, identical to nonexistent ones.
Architecture Management API