Ransack

Getting started

What Ransack is, creating an organization, and publishing a first site.

Ransack turns typed, linked information into public websites and APIs. You define entity types and fields, add entities and relationships, choose routes, and the platform serves a fast public site at ransack.io/s/<your-handle> — pages, search, feeds, and a JSON API, all from the same data.

Ransack is built for agents: everything is driven through the REST API, the CLI, and the MCP server. There is no admin console — the API surface is the product. OAuth-capable MCP clients connect through https://mcp.ransack.io/mcp; Ransack asks the signed-in human to approve an organization and read, write, and publishing access without copying an API key into the agent.

Create an organization

POST /v1/organizations
{ "name": "My Organization", "initialApiKeyName": "builder" }

No account and no credential are needed, and nobody is emailed. This is deliberate: an agent can build a real site and show it to you before you decide whether you want it. An unclaimed organization is deleted when its window closes, so treat it as a demonstration until a human claims it.

When you do want to keep the work, set the owner's email with POST /v1/organizations/{id}/claim-email — that is the moment the claim link is sent. You may also pass pendingClaimEmail to POST /v1/organizations when the owner is already known, which sends the link immediately. Only a human identity can own and recover an organization. The response includes an automation-only bootstrap service API key (shown once — store it outside model context); agents can build immediately, and this key can correct the claim email before ownership, but it is not a recovery credential. The recipient's magic-link page identifies the organization, deadlines, and active automation credentials before offering Claim organization or This isn't mine. Rejection prevents that organization from targeting the same email again. After ownership, ordinary passwordless sign-in is recovery, OAuth is preferred for interactive MCP clients, and a signed-in human can create a 90-day membership-bound key for a CLI or automation that cannot complete OAuth.

Publish a first site

  1. Create a site — POST /v1/sites with your organization id. Every site starts with a production branch and deployment, live at an auto-generated /s/<handle> path.
  2. Push a schema — define an entity type with a few fields (see Schema and entities).
  3. Add entities — individually or via bulk upsert.
  4. Add routes — a home route, a list route, an entity route (see Routes and pages).
  5. Visit your path. Pages, search, sitemap, and feeds are already serving at ransack.io/s/<handle>. Changes appear live — pages re-render as the branch advances.

The CLI wraps every step: ransack sites create, ransack schema push, ransack entities bulk, ransack routes push. Each subcommand documents itself with --help.