Skip to main content
Yertle’s API is built on a Git-like content addressing model. Once you understand the core primitives, the entire API surface follows naturally.

​
The mental model

If you’re familiar with Git: Every node has its own commit history and branches. Every change is an immutable commit. Every state in history can be retrieved exactly.

​
Organizations

An organization is a tenant container. Every node, member, and invite link belongs to an org. Users join orgs through invite links and are assigned a role:
  • viewer — read-only access
  • editor — read + write access
  • owner — full administrative access (manage members, settings, billing)
Every org must have at least one owner. The user who creates an org is automatically assigned owner.

​
Nodes

A node is the central object in Yertle. It represents anything you want to model: a service, a database, a team, a deployment, an entire system. Nodes can contain other nodes (parent/child relationships) and connect to other nodes (graph edges). Each node has:
  • Identity — a stable UUID and a public ID (used in URLs)
  • Content — title, description, tags, directories
  • Children — nodes contained inside this node
  • Connections — directed edges between child nodes
  • Visual properties — positions and sizes for canvas rendering
  • Branches — independent lines of history
  • Commits — immutable snapshots of state

​
Branches and commits

Every node has a main branch by default, plus any number of feature branches. Branches are pointers to commits — exactly like Git. When you push state to a node, you create a new commit. Commits are immutable and form a chain. You can:
  • View the full history of any node
  • Switch between branches
  • Open pull requests to merge branches
  • Roll back to any previous commit

​
Full-state push semantics

Yertle uses full-state push rather than mutation operations. When you update a node, you send the complete desired state — and the server diffs it against the current state to figure out what changed. This is unusual but powerful:
  • No race conditions — your push is the truth
  • Atomic updates — multiple changes commit together
  • Simple client logic — clients don’t need to track individual mutations
The server creates a new commit, updates the branch pointer, and returns the new commit ID.

​
Tags, directories, connections

These are the entities that live inside a node:
  • Tags — Key-value metadata (e.g., env=prod, team=backend). Useful for filtering and search.
  • Directories — Folder paths used to organize nodes within an org’s tree view (e.g., /services/api).
  • Connections — Directed edges between two child nodes inside a parent. Each connection has a label, type, and visual styling.
  • Visual properties — Position, size, rotation, transparency for rendering child nodes on the canvas.

​
Pull requests

When you make changes on a feature branch and want to merge them into main, you open a pull request. PRs work like GitHub:
  • Have a title, description, source branch, target branch
  • Can be open, merged, or closed
  • Support fast-forward, merge-commit, and squash merge methods
  • Optionally require review before merging

​
Reading the API reference

Once you understand these primitives, the API reference becomes self-explanatory. Endpoints are grouped by resource:
  • /organizations — orgs and memberships
  • /orgs/{org_id}/nodes — nodes within an org
  • /orgs/{org_id}/nodes/{node_id}/tree/{branch}/... — branch-scoped operations on a node
  • /orgs/{org_id}/nodes/{node_id}/pull-requests — PRs for a node
  • /invitations — joining an org
See the API Reference for the full list.