MyJackfruit

Help
Browse topics · Reading and writing records

Reading and writing records

← Reading and writing records

How do I read relations between records?

Short answer

Send GET to the record's address with /relations added, then read each relation's role, type and members.

Before you start

Your app holds a token for a person who may read the record, and the record's address.

Words used here (3)
record's address
A record's address is the web address that names one record for good: it never changes and is never given to another record.
relation
A relation is a named link between two records, such as part-of or connected-to, that says how they are related.
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
Steps
  1. Ask for the record's relations.

    Send GET to the record's own address, its @id, with /relations added, such as https://<name>.gilb.com/vault/e/<record id>/relations; the answer is 200 with member and relations.

    More about this

    A relation is a named link between two records, such as part-of or connected-to, that says how they are related. The @id is the address listings and search give, on the vault's own host; it carries the same id as the /lws/r/ address. The call takes a DPoP token with a new proof, a short signed note your app makes for one request, or a plain Bearer token, one bound to no key. A record you may not read answers 404, the same as one that is not there.

  2. Read each relation's role, type and members.

    Each entry in relations has relation, the relation's address, and role, the part your record plays in it, such as role:source; a relation you may read also has type and members.

    More about this

    type is the kind of link, such as t:PartOf. members lists every member with its role, so you can see who is at the other end without reading the relation. For a relation you may not read, type and members are left out, not empty: an empty list would say the relation has no other members. Two or more relations of the same kind between the same two records are each listed apart, each with its own address.

  3. Read one relation at its own address.

    Send GET to the relation's address, such as https://<name>.gilb.com/vault/r/<relation id>, with a DPoP token and a new proof; the answer is the relation with its type and members.

    More about this

    A relation is a record of its own. Its earlier states are at its address with /history added. To list the relations a relation itself is a member of, add /relations to its address.

Deeper

Also asked:

How do I link two records by API? Send PUT to a new relation's address with agent, type, vault and one role:<name> fact per member, such as role:source; it answers 201. To end a link, POST to its address with /end added.

To link two records, send PUT to the new relation's address, such as https://<name>.gilb.com/vault/r/<new relation id> (/base/r/ on a system vault), with agent; type, the kind of link, t:Relation if left out; vault, the vaultId it goes in, or your own vault if left out; and facts with one role:<name> fact per member, such as role:source: {@id: <record address>}. The answer is 201, or 200 when nothing changed. Each relation records its own address, so two links of the same kind between the same records stay two; a value you send for that address is replaced. A member written under the wrong host or spelling is changed to the one stored record it names; one that names no record, several, or a record held elsewhere is kept as sent.

To end a link, send POST to the relation's address with /end added, with no body and no Content-Type. It answers 200: the relation keeps its type, its members are closed, and it leaves the relations lists, but its history keeps it. Ending it again changes nothing. Deleting a record ends the links that join it, as far as you may end them; the answer then gives the number it could not end in the header base-delete-residual, and names up to 10 of them in base-delete-residual-relations.

The Developer Guide has no chapter on relations yet. Its chapter Dev.Guide.EndAndRevive, https://appbuilder.gilb.com/base/e/06gkzpws11z7ba2q7s9qns17h0, says what happens to links when a record is ended and brought back; it can be read with no sign-in, as data for programs and AIs rather than as a web page. The answer on linking two records shows how GilbApp does it on screen.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11; code read at 498d29a0): src/routes/read.ts:796-815 (GET /base/e/:id/relations and /base/r/:id/relations), :357-475 (readReverse: Bearer floor, AUTH FIRST; identical 404 for an unreadable member; answer {member, relations:[{relation, role, type?, members?}]}; members and type omitted, never [], for an unreadable relation; each relation listed apart, :431-474), :785-793 (GET /base/e/:id and /base/r/:id through readAndFrame: a DPoP token, :211), :809-841 (history and relations of a relation); src/uri/vault-segment.ts:321-461 and src/server/app.ts:326-394 (a user vault's /vault spelling is rewritten to these /base routes; /base/e/ and /base/r/ on a user vault's host are refused 404, :435-437, namespaces e, a, t, r, view, p :449); src/routes/relation.ts:1-53 (role:<slug> facts, {@id} values; body type?, facts, agent, vault?), :94-276 (PUT /base/r/:id: the named vault or the writer's own, :147-161; relation address from that vault, a:relationSelf stamped by the platform, a client value replaced, :259; 201/200 :274; Bearer floor), :294-346 (POST /base/r/:id/end; body ignored; 200 {relation, entity, changed, txn_id?}); src/write/relation-end.ts:1-55 (keeps @type, asserts a:relationLifecycleState ended, closes every role:, relation_members re-derived empty; history keeps it), :225-255 (ending again: an idempotent replay; 404 when no state); src/write/member-uri.ts:28-31 (canonicalize when certain, else verbatim); src/lws/routes.ts:1108-1136 (DELETE /lws/r/:id: base-delete-residual = the count, base-delete-residual-relations = up to 10 addresses, :1123-1132). Production, no token, https://appbuilder.gilb.com/base/e/06gkzpwqkxz1h5002g87j1p3x0/relations, 2026-11-11: 200 {member:…,relations:[]}. Not in the Developer Guide (no relations chapter): Dev.Guide.EndAndRevive (A 06gkzpws11z7ba2q7s9qns17h0, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied); Dev.Guide.Addresses (A 06gkzpwjzhtwb4m72ae1jy3t2c, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) EndAndRevive.Links (closed links stay closed after a revive; links held as facts verified 2026-10-15, separate relation records not); Addresses.Record (the @id and /lws/r/ carry the same id). GilbApp ebd9415e (live at https://gilb.com/app/version.json, read 2026-11-11): src/lib/base/planSolution.ts:12 (role:source, role:target in use). The code examples are written here, placeholders only. Rows: Developer.ReadRecordRelations, SeveralRelationsBetweenSameRecords, RelationMemberCanonicalised, GilbPlatform.RelationLinkAndEnd.

For developers

curl

relations.sh

# The relations a record is in, on the vault's own host.
curl -s "https://<name>.gilb.com/vault/e/<record id>/relations" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for this GET and this address>"
# 200: {"member":"https://<name>.gilb.com/vault/e/<record id>",
#       "relations":[{"relation":"https://<name>.gilb.com/vault/r/<relation id>","role":"role:source",
#                     "type":"t:PartOf","members":[{"member":"...","role":"role:source"},{"member":"...","role":"role:target"}]}]}

TypeScript

other-ends.ts

// The records at the other end of each relation a record is in, with the kind of link.
type Relations = {
  member: string;
  relations: { relation: string; role: string; type?: string; members?: { member: string; role: string }[] }[];
};

export function otherEnds(answer: Relations): { relation: string; type?: string; member: string; role: string }[] {
  const out: { relation: string; type?: string; member: string; role: string }[] = [];
  for (const r of answer.relations) {
    if (r.members === undefined) continue; // a relation you may not read: no members are shown
    for (const m of r.members) {
      if (m.member !== answer.member) out.push({ relation: r.relation, type: r.type, member: m.member, role: m.role });
    }
  }
  return out;
}

Checked against GilbApp d529620.