Everything in Display.dev is one of a small set of nouns. The rest of the docs assume you know these.
Artifact
An artifact is a single piece of authored content — an HTML file, a Markdown document, an exported notebook — that has been published to Display.dev. Each artifact has:
- A shortId — the stable handle (
abc123) that appears in every URL and CLI command for the artifact. - A slug — the human-friendly name segment derived from the artifact name.
- A version (see below).
Version
Every republish bumps the artifact's version by one — v1 on first publish, v2 after the next dsp publish --id <shortId> --base-version <currentVersion> ..., and so on. The artifact's URL always serves the latest version by default; readers don't have to know what version they're looking at.
A specific version can be linked directly with the /_v/<n> path suffix — for example, https://acme.dsp.so/abc123-quarterly-report/_v/2. The CLI's dsp export <shortId>@2 does the same thing for source bytes.
Version retention depends on plan. Free orgs keep only the latest version on every artifact; paid plans keep older versions up to a per-tier cap. See Plans & features.
Organization
An organization is the unit of billing, identity, and access. Members of an organization can see each other's artifacts (subject to visibility) and bill against the same plan.
Visibility
Every artifact has a visibility setting:
- Public — anyone with the link can view, no auth required.
- Company — anyone signed in to your organization can view.
- Private — the publisher and explicitly allowlisted addresses (
sharedWith).
Visibility & sharing covers the full semantics including external-guest invitations and tier requirements.
Organization subdomain
Each organization gets a stable view subdomain — <org>.dsp.so — so artifacts always render at the same hostname for a given organization. This lets your company set up bookmarks, browser policies, and SSO trust against one origin.
Actor
Every write to your organization — a publish, a comment, a key rotation — records the actor that performed it. Four classifications:
- Human — a person signed in to the dashboard or CLI.
- Agent — an AI assistant publishing on a human's behalf (Claude Code, Cursor, Codex, the display.dev MCP server, the display.dev skill).
- Service — a non-interactive automation publishing with an organization-scoped API key (CI pipelines, deploy bots).
- System — Display.dev itself (retention sweeps, automated cleanups, billing-driven changes).
Agent rows show the agent's display name and the human it's acting for — "claude-code on behalf of Alice Smith", or "agent on behalf of Alice Smith" when no name is stamped. Human rows show only the user, unless they stamped a label with --actor-name, in which case the row reads "Alice Smith via my-tool". Service rows show the name stamped via --actor-name (e.g. "ci-deploy") or "service key" when none is set. System rows show "display.dev system".
The classification appears in three places:
- The audit log (Pro and Enterprise; Solo records only artifact-view events; Free has no audit log).
- The version history side panel on each artifact.
- Every comment row in the comments widget.
The CLI infers the actor type automatically — human when launched from a terminal, agent otherwise. Override it with --actor-type human|agent and stamp a display name with --actor-name <name>, or set DISPLAYDEV_ACTOR_TYPE and DISPLAYDEV_ACTOR_NAME once per session. Use an organization-scoped API key to publish as service; that classification can't be set from the CLI. See the CLI reference.