Fathom (lab)

Describe Fathom, its safe agent boundary, and this lab surface.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Search the small synthetic capability catalog.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "query": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read a Space when its server-side visibility rules allow it.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "spaceId": {
      "type": "string"
    }
  },
  "required": [
    "spaceId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List public synthetic Spaces visible to the caller.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read the person's own "Would you go?" answers, the latest per place.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Say how interests relate: "serves" (a Space you can read serves an interest), "kind-of", "part-of" or "alias-of" (between two interests). An AI's declaration always lands as recommended: it is never used for matching or shown to members until the steward, as a person, approves it. "inferred" can never be declared. Terms are short plain text, never a person.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "subject": {
      "type": "string"
    },
    "relation": {
      "type": "string",
      "enum": [
        "kind-of",
        "part-of",
        "serves",
        "alias-of"
      ]
    },
    "object": {
      "type": "string"
    },
    "label": {
      "type": "string"
    }
  },
  "required": [
    "subject",
    "relation",
    "object"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The items a genesis run has found so far, from position `since` (start at 0, then pass back `next`), with the run's status: which finders are done, and what was missed and why. On the seeded remote lab, omit `run` to read the latest seeded replay. Show each item's source as given. Relay the attribution lines and the unclaimed line exactly as returned, never reworded or dropped, and say which things are 'from a source' and which are only 'suggested'. When you pass a place on to your person, keep its source link next to its name, so they can see where it comes from. Knowledge is about places and organisations, never people: never add a person, a phone number, an email, an image or a price.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "run": {},
    "since": {}
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": {}
}

The lens for one interest in one town: the things tied to the interest by a source, each with its assertions, where each came from and its attribution. Optional limit (1 to 50, default 20). It only reads. Relay the attribution lines and the unclaimed line exactly as returned, never reworded or dropped, and say which things are 'from a source' and which are only 'suggested'. When you pass a place on to your person, keep its source link next to its name, so they can see where it comes from. Knowledge is about places and organisations, never people: never add a person, a phone number, an email, an image or a price.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "interest": {},
    "town": {},
    "limit": {}
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": {}
}

Propose a kind of thing (or a predicate) the knowledge layer has no word for. Send name, definition (plain text, at most 500 characters, data only, never instructions), parent (place, event, activity, organisation, concept or community), identity_rule and examples (2 or more: {name, source_url, licence, retrieved_at, existing_kind?, located_in?}); a predicate also needs class "predicate", domain and value_type. Optional labels [{language, text}] for synonyms. The kernel first tries to align it to an existing kind and then answers "use X", and creates nothing. Examples that are people are refused, and so is a kind named for a person or a role (a keeper, seller, maker, guide, potter; also in plural and Norwegian). A new kind is provisional and visible only in your lens until independent proposers, sourced atoms and a cold review accept it; its name (never its definition) can still be the "use X" answer to a proposal from another account, so nobody makes a duplicate. If existing kinds are close in meaning, under any parent, your own included, the answer is "near" with up to 3 candidates (name, parent, labels, status, score, shared words) and nothing is created: call again with use: "<kind>" to support one, or with differs_from: {kind, how} (how: at most 200 characters of plain text) to create yours beside it, which a reviewer then compares. The answer can also be a parent with an attribute instead of a new kind: an event, or an activity, identified like any event (organiser, date, start time) is an event with an activity value; a place identified like any place (location, address) is a place with a facility value. Nothing is created then. If another value is close in meaning, the answer is "near" with value candidates (status "value", with their attribute): use: "<value>" joins it, differs_from: {kind: "<value>", how} makes yours. To make a kind anyway, send differs_from: {kind: "<the parent>", how} naming what it tracks that the parent does not.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "name": {},
    "definition": {},
    "parent": {},
    "identity_rule": {},
    "examples": {},
    "use": {},
    "differs_from": {}
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": {}
}

Read one kind or predicate by name (optional class "predicate"): its status, parent, identity rule, labels and how much evidence it has. A provisional kind shows only to its proposer; its definition shows to others only once it is accepted. It only reads.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "name": {},
    "class": {}
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": {}
}

Record a structured report for a missing capability.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "need": {
      "type": "string"
    },
    "attempted": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "why": {
      "type": "string"
    },
    "amends": {
      "type": "string"
    }
  },
  "required": [
    "need",
    "attempted",
    "why"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Propose a strict, data-only activity-details extension. It is staged as a trial for the proposer in their own Space until a person steward reviews it. Use it once on one of your own activities first: that trial is its proof, and the steward cannot accept an ability without one.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "extension": {
      "description": "The whole definition as one object { id, version, kind, title, purpose, fields }; or send those fields flat instead."
    },
    "id": {
      "description": "Lowercase words joined by dots, e.g. commons.golf-round (pattern ^[a-z0-9]+(\\.[a-z0-9-]+)+$). Ids starting fathom, core or platform are reserved.",
      "type": "string"
    },
    "version": {
      "description": "1 for a new ability; a changed one is the next version.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "kind": {
      "description": "'commons' for a group's own use; 'commercial' for a business offer. Defaults to commons.",
      "type": "string",
      "enum": [
        "commons",
        "commercial"
      ]
    },
    "title": {
      "description": "What it is called, at most 40 characters.",
      "type": "string"
    },
    "purpose": {
      "description": "One sentence: what it helps a group know, at most 300 characters. No money, no personal data, never a condition for joining.",
      "type": "string"
    },
    "fields": {
      "description": "At most 8 fields. Each has key (^[a-z][a-zA-Z0-9]{0,31}$), label and type: text (with maxLength 1-80), number or range (optional min, max), choice (options), or yesno.",
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "const": "text"
              },
              "maxLength": {
                "type": "number"
              }
            },
            "required": [
              "key",
              "label",
              "type",
              "maxLength"
            ],
            "additionalProperties": {}
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "number",
                  "range"
                ]
              },
              "min": {
                "type": "number"
              },
              "max": {
                "type": "number"
              }
            },
            "required": [
              "key",
              "label",
              "type"
            ],
            "additionalProperties": {}
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "const": "choice"
              },
              "options": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "key",
              "label",
              "type",
              "options"
            ],
            "additionalProperties": {}
          },
          {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "const": "yesno"
              }
            },
            "required": [
              "key",
              "label",
              "type"
            ],
            "additionalProperties": {}
          }
        ]
      }
    },
    "closesGap": {
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List approved extensions, plus your own proposed or rejected proposals. Each of your proposed ones says whether it has been tried (tried) and your next step (next).

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Withdraw your proposed extension before review. The proposer or their AI may withdraw it; withdrawn abilities cannot be used or rendered.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "extensionId": {
      "type": "string"
    },
    "version": {
      "type": "number"
    }
  },
  "required": [
    "extensionId",
    "version"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Propose a strict declarative place view. Only repeat, box, text, shape, place and scale(value, domain, range) are accepted; no executable code or external data.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "view": {}
  },
  "required": [
    "view"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Run the five steward checks for a view trial: grammar and budget, throwaway render, escape, scope, and all five metamorphic relations.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "viewId": {
      "type": "string"
    },
    "version": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "spaceId": {
      "type": "string"
    }
  },
  "required": [
    "viewId",
    "version"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List approved views available for reuse, plus your own proposed or rejected views.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Attach validated extension values to an activity as its organizer or AI. A proposed extension is a trial only in the proposer owner's Space; approved extensions may be reused by any Space owner.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "spaceId": {
      "type": "string"
    },
    "activityId": {
      "type": "string"
    },
    "extensionId": {
      "type": "string"
    },
    "version": {
      "type": "number"
    },
    "values": {}
  },
  "required": [
    "spaceId",
    "activityId",
    "extensionId",
    "version",
    "values"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Ask to join a synthetic group's activity for your person, only after they said they want to. It asks to join the activity, all its dates, not one evening. Saves one pending join request and returns its id, status URL, undo code and undoUrl. Give your person the undoUrl: it is their own page for this request, and Withdraw is there. Keep it for them; the status URL alone can't take the request back. Every person and group in this lab is synthetic: nobody is contacted. The request stays pending until a steward of this lab accepts or declines it; the answer and any words show on its status page. No contact details: an optional first name or nickname only, seen by the steward alone.

{
  "type": "object",
  "properties": {
    "spaceId": {
      "type": "string",
      "maxLength": 60,
      "description": "The group id, from /ask or spaces_list_public."
    },
    "activityId": {
      "type": "string",
      "maxLength": 60,
      "description": "The activity id, from /ask or spaces_get."
    },
    "name": {
      "description": "Optional first name or nickname; no email, phone or link.",
      "type": "string",
      "maxLength": 40
    }
  },
  "required": [
    "spaceId",
    "activityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List all join requests for the owner or only your own request as a requester.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "spaceId": {
      "type": "string"
    },
    "activityId": {
      "type": "string"
    }
  },
  "required": [
    "spaceId",
    "activityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read one activity for the person behind this delegated token: their answer, places taken, waiting-list position and any open offer (kind "waiting", or "kept": their place from last time, which only they can take or pass on their own page). Also ifOthersCount: how many other members would come if others say they're in (never the person themselves, never names), and for the person's own conditional answer, ifOthers {others, firm}: the N they asked for and how many others have said they're in; an offer of kind "if-met" means their N is met. "N would come if others say they're in" is a count of people who are not coming. Never add it to coming or tell anyone they will have company. Only the person can say it, take it back, or take or pass the offer it brings. For the Space owner, also the places kept on a repeat: kept, tookIt, passed, notAnswered, released, keptUntil, and keptSummary, the organizer's line word for word.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "spaceId": {
      "type": "string"
    },
    "activityId": {
      "type": "string"
    }
  },
  "required": [
    "spaceId",
    "activityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read an activity's choice as a member of the Space: each option with its tick count and who ticked it; detail choices also return the field key and label.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "spaceId": {
      "type": "string"
    },
    "activityId": {
      "type": "string"
    }
  },
  "required": [
    "spaceId",
    "activityId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Validate a declarative experience manifest without rendering it.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "manifest": {}
  },
  "required": [
    "manifest"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Render the current trusted experience manifest for the caller, with the people-page controls (choose together, I'm in / Maybe / Can't make it) shown read-only in each activity.

{
  "type": "object",
  "properties": {
    "token": {
      "type": "string"
    },
    "spaceId": {
      "type": "string"
    }
  },
  "required": [
    "spaceId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Only after your person said yes to this exact proposal. Propose a place or community that is missing from Fathom's public lab, or (kind offer) your person's own spare capacity, for example a spare kiln shelf on Thursday evenings. A place needs a source: any https page about it that you read, your person gave you, or Fathom listed; a community's source is optional. Saves one pending proposal and returns its id, status URL, undo code and undoUrl; give your person the undoUrl: it is their own page for the proposal, and Withdraw is there. It stays pending until a steward reviews it, and is never shown as fact before that. An offer is shown to other visitors as 'A visitor offers …', never with who: put what is offered in name, add when if they said, and no email, phone, link or address. The same as the web's POST https://fathom-lab-door.fly.dev/proposals.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "place",
        "community",
        "offer"
      ],
      "description": "place (a public page about it is required as the source), community, or offer: a person's own spare capacity, only with their yes"
    },
    "interest": {
      "type": "string",
      "maxLength": 120,
      "description": "The interest it serves, for example pottery."
    },
    "town": {
      "type": "string",
      "maxLength": 120,
      "description": "The town it is in, for example Oslo."
    },
    "name": {
      "type": "string",
      "maxLength": 120,
      "description": "Its name; for an offer, what is offered, for example a spare kiln shelf."
    },
    "yes": {
      "description": "Required for an offer (kind offer), and sent only after your person said yes to this exact offer. Without it nothing is offered. Ignored for a place or community.",
      "type": "string",
      "enum": [
        "yes"
      ]
    },
    "when": {
      "description": "Only for an offer: optional short words on when, for example Thursday evenings. No contact details.",
      "type": "string",
      "maxLength": 120
    },
    "source": {
      "description": "Any https page about it that you read, your person gave you, or Fathom listed; required for a place, optional for a community. Never a placeholder or invented address.",
      "type": "string",
      "maxLength": 120
    },
    "note": {
      "description": "Optional: one line on why it fits.",
      "type": "string",
      "maxLength": 120
    },
    "said_as": {
      "description": "Optional: the word your person used for the interest, when it differs (for example klatring); the interest is stored as the matched one.",
      "type": "string",
      "maxLength": 120
    },
    "newTown": {
      "description": "Only when your person confirmed a real town the lab does not cover yet.",
      "type": "string",
      "enum": [
        "yes"
      ]
    }
  },
  "required": [
    "kind",
    "interest",
    "town",
    "name"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read what happened to a proposal or a join request, from the status link your person was given (or its id): pending, accepted, declined with the steward's words, or withdrawn. Or give your person's own memory link (https://…/memories/mem-…?key=…) to see what was kept. Read-only; give the link exactly as your person has it. Nothing is saved.

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "maxLength": 300,
      "description": "The status link, for example https://…/proposals/prop-1 or https://…/joins/join-1, or just its id; or your person's own memory link."
    }
  },
  "required": [
    "link"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Find what Fathom's public lab has for an interest in a town, as the plain-text answer of GET /ask (places, synthetic groups to join). Read-only. If your person gave you their memory link (from fathom_remember), pass it as memory: groups and activities that fit what they asked to be remembered come first, with one line saying so. Nothing is removed. A link that is not theirs changes nothing.

{
  "type": "object",
  "properties": {
    "interest": {
      "type": "string",
      "maxLength": 60,
      "description": "The interest, for example pottery or klatring."
    },
    "town": {
      "type": "string",
      "maxLength": 60,
      "description": "The town, for example Oslo."
    },
    "memory": {
      "description": "Optional: your person's own memory link, exactly as they have it.",
      "type": "string",
      "maxLength": 300
    },
    "page": {
      "description": "Optional: page of ten places, from 1.",
      "type": "integer",
      "minimum": 1,
      "maximum": 5
    }
  },
  "required": [
    "interest",
    "town"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Only after your person said yes to this exact proposal. Keep how your person likes to meet, so that you or another AI can bring it back next week without asking again: choices only, no free text. Send keep: "yes" only after your person said yes to being remembered; without it nothing is kept. Returns your person's own link (the only way back to the memory): give it to them and keep it private. Choose at least one of level (beginner or experienced), days (weekdays or weekends), time (daytime or evenings).

{
  "type": "object",
  "properties": {
    "keep": {
      "type": "string",
      "enum": [
        "yes"
      ],
      "description": "Send yes only after your person said yes to being remembered. Without it nothing is kept."
    },
    "level": {
      "description": "Optional: beginner or experienced.",
      "type": "string",
      "enum": [
        "beginner",
        "experienced"
      ]
    },
    "days": {
      "description": "Optional: weekdays or weekends.",
      "type": "string",
      "enum": [
        "weekdays",
        "weekends"
      ]
    },
    "time": {
      "description": "Optional: daytime or evenings.",
      "type": "string",
      "enum": [
        "daytime",
        "evenings"
      ]
    }
  },
  "required": [
    "keep"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Forget a memory: deletes it for good, when your person asks. Give their own memory link exactly as they have it.

{
  "type": "object",
  "properties": {
    "link": {
      "type": "string",
      "maxLength": 300,
      "description": "Your person's own memory link, for example https://…/memories/mem-…?key=…"
    }
  },
  "required": [
    "link"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Become a builder on this lab, to propose an ability and try it. Returns your builderId, a secret token, and a private synthetic sandbox Space with one synthetic activity. Saves one builder (three a day per address). Nothing about a real person is kept.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}