Records

Tangled data lives in AT Protocol records. Each record is stored either in a user’s PDS (things a person owns: profile, stars, follows) or in the repository DID’s account on its knot (things about a repository: issues, pull requests, comments). Schemas are in lexicons/org/tangled/.

$ curl "https://knot.example.com/xrpc/com.atproto.repo.listRecords?repo=did:plc:repoxyz&collection=org.tangled.track.ticket&limit=1"

Records in a repository account are written through the knot (com.atproto.repo.createRecord and friends, or by the knot itself). The knot checks the caller’s permission and stamps the record with x-tngl-editor, the DID of the account that made the change.

Location key:

• User PDS: the author’s own account.
• Repo account: the repository DID’s account, hosted by its knot.

Repositories

NSID	Stored in	Record key	Purpose
org.tangled.repo.manifest	Repo account	self	Repository metadata (description, website, topics, spindle DID, fork or import source) and the declaration {owner, name} half of the ownership claim. Written by the knot.
org.tangled.repo.declaration	User PDS (owner)	Repository slug	The owner’s half of the claim: {repo: repoDid}. A repository is listed under owner/slug only while manifest and declaration agree.
org.tangled.graph.collaborator	Repo account	Invitee DID	Collaboration offer. Indexed by bobbin. The repo owner will create it by sending a request to com.atproto.repo.createRecord with this NSID, conversely removing it with deleteRecord; the knot grants collaborator access from the record’s presence.
org.tangled.label.definition	Repo account	any	A label in the repository’s catalogue: {name, color}.

Issues and pull requests

NSID	Stored in	Record key	Purpose
org.tangled.track.ticket	Repo account	TID (minted by the knot)	An issue, or a pull request when targetBranch is set. Holds title, body, state (open, closed, completed) and labels. Only the author or a maintainer can change state.
org.tangled.review.patch	Repo account	The record’s own CID	One immutable revision of a pull request: {ticket, base, head} commit IDs, plus an optional source naming the repo DID and branch it came from. Each resubmission adds a patch.

Discussion and reactions

NSID	Stored in	Record key	Purpose
org.tangled.feed.comment	Repo account	TID (minted by the knot)	A comment on a ticket, patch or string, with optional replyTo. Images and video attach through the markdown blobs.
org.tangled.feed.reaction	Repo account	TID (minted by the knot)	An emoji reaction on a record. Create and delete only.
org.tangled.graph.attestation	User PDS	TID	The author’s claim that a knot-written record is really theirs: {subject, change} where change is the COB change ID, from the write’s x-tngl-change.

Social graph

NSID	Stored in	Record key	Purpose
org.tangled.actor.profile	User PDS	self	Profile: avatar, bio, links, location, pronouns, pinned repositories, isOrganization.
org.tangled.feed.star	User PDS	TID	Star on a repository DID or a record.
org.tangled.feed.subscription	User PDS	TID	Subscription to a repository or a thread; ignore mutes it. Drives notifications.
org.tangled.graph.follow	User PDS	Subject DID	Follow another account.
org.tangled.graph.vouch	User PDS	Subject DID	vouch or denounce another account, with a reason and up to 10 evidence links.

Keys and strings

NSID	Stored in	Record key	Purpose
org.tangled.key.sshKey	User PDS	TID	SSH public key with usages auth and/or sign. Written by web key settings and GitHub import. The knot authenticates pushes with keys whose usages include auth (or omit usages); bobbin indexes it.
org.tangled.snippet.string	User PDS	any (TID preferred)	A string (gist): description plus one text file blob up to 1 MB.

Git

NSID	Stored in	Record key	Purpose
org.tangled.git.refs	Repo account	self	Snapshot of every ref and the default branch, rewritten by the knot after each push. Knotmirror syncs from it. Spindle reads the default branch from it.

Shared objects

Embedded in other records, never stored alone: org.tangled.git.oid, org.tangled.embed.commit, org.tangled.markup.markdown (text up to 256 KiB plus blobs), org.tangled.markup.embed.image, org.tangled.markup.embed.video, org.tangled.label.defs, org.tangled.repo.defs.

The API pages list the methods that read and write these records.