# Factrove

> Guides and references for Factrove, a self-hostable library for HTML artifacts.

> ## Agent Instructions
> Describe what the running code does. Do not invent hosted pricing, launch dates, or security guarantees. Share and viewer links are a configured base URL plus an artifact path. Show localhost and a placeholder origin such as https://library.example.com.

- [Introduction](https://docs.factrove.app/introduction.md): Factrove is a self-hostable library for HTML artifacts, with a web app, HTTP API, and CLI.
- [Quickstart](https://docs.factrove.app/quickstart.md): Install the Factrove CLI, or run the repository locally, create an API key, and upload an HTML file.
- [Concepts](https://docs.factrove.app/concepts.md): Artifacts, HTML delivery, access, organization membership, and how links are built.
- [Self-hosting](https://docs.factrove.app/guides/self-hosting.md): Run Factrove with Docker Compose, or from source, including storage, HTTPS, the CLI, upgrades, and backups.
- [CLI](https://docs.factrove.app/guides/cli.md): Commands, flags, config precedence, and how Factrove differs from aws s3.
- [Release the CLI](https://docs.factrove.app/guides/releasing-the-cli.md): Publish the factrove npm package from a manual GitHub Actions dispatch. Nothing publishes on push.
- [Sharing links](https://docs.factrove.app/guides/sharing-links.md): Create public artifact links, optionally protect them with a password, and understand unlock, lockout, and Retry-After.
- [Troubleshooting](https://docs.factrove.app/guides/troubleshooting.md): Ports, secrets, storage, API origins, cookies, profiles, public links, and content tickets.
- [CLI overview](https://docs.factrove.app/cli-reference/overview.md): Install and configure the Factrove CLI, then read the exact help pages generated from the command spec.
- [factrove --help](https://docs.factrove.app/cli-reference/help.md): The exact top-level help text from the CLI.
- [upload](https://docs.factrove.app/cli-reference/upload.md): Upload an HTML file as a new artifact and print its id.
- [get](https://docs.factrove.app/cli-reference/get.md): Print an artifact's content (HTML, or --format markdown).
- [share](https://docs.factrove.app/cli-reference/share.md): Create a public link. Add --password, --remove-password or --revoke.
- [list](https://docs.factrove.app/cli-reference/list.md): List your artifacts. --view org lists organization-shared ones.
- [rename](https://docs.factrove.app/cli-reference/rename.md): Change the name shown in the library.
- [delete](https://docs.factrove.app/cli-reference/delete.md): Delete an artifact. --yes skips the confirmation.
- [configure](https://docs.factrove.app/cli-reference/configure.md): Save your API key and API URL.
- [API overview](https://docs.factrove.app/api-reference/overview.md): How Factrove authenticates callers, shapes errors, and documents endpoints from the contract schemas.
- [Check that the API is initialized](https://docs.factrove.app/api-reference/health/check-that-the-api-is-initialized.md): Returns `{ status: "ok" }` after the process has started. No credentials.
- [Return the caller and current organization](https://docs.factrove.app/api-reference/auth/return-the-caller-and-current-organization.md): Reads the session cookie or `Authorization: Bearer` API key. A session uses `activeOrganizationId` when the caller is a member of that organization. Otherwise the organization is the caller's only membership, or null when they have none or more than one. An API key has no active organization and use…
- [Create an account with email and password](https://docs.factrove.app/api-reference/auth/create-an-account-with-email-and-password.md): Better Auth email/password sign-up. Email verification is off. Passwords are 8 to 128 characters, the same limits createAuth passes to Better Auth. This route is rate limited to 10 requests per 60 seconds per client address. The response body is Better Auth JSON, not the product `{ error: { code, me…
- [Sign in with email and password](https://docs.factrove.app/api-reference/auth/sign-in-with-email-and-password.md): Better Auth email/password sign-in. Passwords are 8 to 128 characters. Rate limited to 10 requests per 60 seconds per client address. Sets the session cookie. The response body is Better Auth JSON.
- [Create an API key](https://docs.factrove.app/api-reference/auth/create-an-api-key.md): Requires a browser session. Do not send `Authorization`. A request that also sends it is 401 with message `API key management requires a browser session.` Cookie writes need `Origin` or `Referer` to be `WEB_ORIGIN` or `PUBLIC_BASE_URL`. A missing or different origin is 403 `FORBIDDEN` before Better…
- [List API keys for the session](https://docs.factrove.app/api-reference/auth/list-api-keys-for-the-session.md): Requires a browser session. Returns names and starting characters, not the secret. Better Auth JSON `{ apiKeys, total }`.
- [Revoke an API key](https://docs.factrove.app/api-reference/auth/revoke-an-api-key.md): Requires a browser session. Do not send `Authorization`. Cookie writes need `Origin` or `Referer` to be `WEB_ORIGIN` or `PUBLIC_BASE_URL`. A missing or different origin is 403 `FORBIDDEN`. Another user's key id is 404. After delete, that key fails closed on product routes.
- [List artifacts for the caller](https://docs.factrove.app/api-reference/artifacts/list-artifacts-for-the-caller.md): `view=mine` (default) is artifacts the caller created. `view=org` is org_shared artifacts in the caller's current organization, including other creators. With no current organization, `view=org` is an empty list. Sorted by createdAt descending, then id descending. The whole list is returned.
- [Upload an HTML file](https://docs.factrove.app/api-reference/artifacts/upload-an-html-file.md): Accepts one non-empty `.html` or `.htm` file as multipart field `file`, optional `accessType` (`private` default, or `org_shared`), and optional `name`. `name` is one line of 1 to 120 characters. When `name` is omitted, the stored name is the file name without `.html` or `.htm` when that stem is one…
- [Download artifact HTML or converted Markdown](https://docs.factrove.app/api-reference/artifacts/download-artifact-html-or-converted-markdown.md): Default format is HTML, the stored bytes, `Content-Type: text/html`. `format=markdown` converts that HTML on a worker and returns `text/markdown`. Markdown is not stored. `Accept` does not choose the format. Optional `access` is a short-lived HMAC grant for HTML in the viewer iframe and authenticate…
- [Replace an artifact's stored HTML](https://docs.factrove.app/api-reference/artifacts/replace-an-artifacts-stored-html.md): Owner only. Multipart field `file` is the same HTML validation as create: one non-empty `.html` or `.htm` file, at most 10 MiB, UTF-8. Optional `name` is set in the same conditional update as the new object and the revision check. Omit `name` and that update does not change the column, so the curren…
- [Get artifact metadata](https://docs.factrove.app/api-reference/artifacts/get-artifact-metadata.md): Owner and, for org_shared artifacts, organization members can read this. Missing credentials, an invalid key, and anyone who cannot read the artifact get the same 404 as an unknown id. This route does not return 401. A session-authenticated response may append `?access=` on `contentUrl` so the sandb…
- [Delete an artifact](https://docs.factrove.app/api-reference/artifacts/delete-an-artifact.md): Owner only. Deletes the artifact row and the current HTML object. The creator is the only caller who can delete. Organization role is not consulted, so an organization admin who did not create the artifact cannot delete it. A missing id and a caller who is not the creator, including a member who can…
- [Share a private artifact with the confirmed organization](https://docs.factrove.app/api-reference/artifacts/share-a-private-artifact-with-the-confirmed-organization.md): Owner only. JSON body `{ "accessType": "org_shared", "organizationId": "<current organization id>" }` switches a private artifact to `org_shared` and sets `organizationId` to that id. The id must be the caller's current membership. The only explicit row lock is the artifact. The organization foreign…
- [Rename an artifact](https://docs.factrove.app/api-reference/artifacts/rename-an-artifact.md): Owner only. Changes the library name and leaves the HTML object, content revision, access, organization, and share columns unchanged. The creator is the only caller who can rename. Organization role is not consulted, so an organization admin who did not create the artifact cannot rename it. A missin…
- [Read the owner share state](https://docs.factrove.app/api-reference/shares/read-the-owner-share-state.md): Only the creator can read the share. Other members who can read an org_shared artifact get the same 404 as a missing id. When the stored token cannot be decrypted with the current key, the response is `{ shared: false, shareUrl: null }`.
- [Create or update a public share](https://docs.factrove.app/api-reference/shares/create-or-update-a-public-share.md): Creates a public link, or returns the existing one while the current key can still read the token. An optional JSON body `{ password }` sets or replaces the link password. Omitting the password keeps the current one. Passwords are 10 to 128 NFC characters, at least four distinct characters, not all…
- [Revoke the public share](https://docs.factrove.app/api-reference/shares/revoke-the-public-share.md): Clears the share token and the password. The previous URL becomes the same 404 as a missing artifact.
- [Remove the password from a shared link](https://docs.factrove.app/api-reference/shares/remove-the-password-from-a-shared-link.md): When the artifact is shared, the share URL stays the same, `passwordProtected` becomes false, and existing unlock grants become invalid. When the artifact is not shared, the response is `{ shared: false, shareUrl: null, passwordProtected: false }`.
- [Read a public share](https://docs.factrove.app/api-reference/public/read-a-public-share.md): No session. The response omits creator, organization, access type, and the share URL. An inactive, unknown, or revoked token is `404 ARTIFACT_NOT_FOUND` and does not say whether the artifact exists. A password-protected share without a valid `X-Factrove-Share-Grant` is `401 PASSWORD_REQUIRED`. The v…
- [Unlock a password-protected share](https://docs.factrove.app/api-reference/public/unlock-a-password-protected-share.md): No session. JSON `{ password }`. A matching password returns `{ grant: { token, expiresAt } }` valid for 15 minutes. A link with no password returns `{ grant: null }`. A wrong password is `401 PASSWORD_INCORRECT`. An inactive link is `404 ARTIFACT_NOT_FOUND`. A missing or non-JSON body is `400 INVAL…
- [Download public share HTML](https://docs.factrove.app/api-reference/public/download-public-share-html.md): No session. Markdown is not offered. A password-protected link needs a `ticket` query minted on a granted detail response. The ticket lasts 60 seconds and is honored at most 3 times per API process. Content on a protected link without a valid ticket is `401 PASSWORD_REQUIRED`. Reverse proxies should…

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.