> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rings.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

> The entities, scores, and vocabulary used across Rings

Rings watches the email and calendar activity your team already generates and
builds a **relationship graph** from it: who knows whom, how well, and how
recently. Almost everything in the API is either a node in that graph, an
interaction that feeds it, or a score derived from it.

This page defines the terms you will meet in the API and in the Rings app.

## Your workspace

<ResponseField name="Ring" type="your organisation's workspace">
  A ring is one organisation's private world in Rings — its people, companies,
  deals, and relationship graph. All API keys belong to exactly one ring, and
  nothing crosses between rings. When you see "tenant" in the API, it means the
  same thing; "ring" is the product word, "tenant" the technical one.
</ResponseField>

<ResponseField name="Ring member" type="someone on your team">
  A colleague inside your ring — a Rings user at your firm. Their email and
  calendar activity is what builds the graph. Ring members are excluded from
  relationship lists, which are about the outside world.
</ResponseField>

<ResponseField name="Ringmaster" type="workspace administrator">
  A ring member with administrative rights over the workspace. Ringmasters can
  act on records they do not own — for example, deleting any note in the ring
  or editing any entity list. Ordinary members can only change their own.
</ResponseField>

<ResponseField name="Internal vs external">
  **Internal** people are ring members. **External** people are everyone else —
  founders, LPs, candidates, counterparties. Relationship scores always measure
  an internal person's connection to an external one.
</ResponseField>

<ResponseField name="User context">
  Some data belongs to a specific person rather than the whole ring — your
  meetings, your tasks, your own relationships. Endpoints returning that data
  need to know which member is asking. Either use a user-scoped API key, or
  send `x-rings-user-id` with a ring-scoped one. Without it you get `403`.
  See the [API reference](/api-reference/introduction).
</ResponseField>

## The entities

```mermaid theme={null}
graph LR
  P[Person] -- works at --> C[Company]
  A[Activity] -- involves --> P
  O[Opportunity] -- associated with --> P
  O -- associated with --> C
  N[Note] -- associated with --> P
  T[Task] -- associated with --> O
  L[Entity list] -- contains --> P
```

<ResponseField name="Person" type="a human">
  Anyone your ring knows about — a contact, a founder, a candidate, or a ring
  member. Identified by `person_uuid`. Carries emails, job title, current
  company, and relationship scores.
</ResponseField>

<ResponseField name="Company" type="an organisation">
  Identified by `company_uuid`. Carries domain, location, industry tags,
  headcount, funding attributes, and relationship scores. People are linked to
  companies through affiliations.
</ResponseField>

<ResponseField name="Affiliation" type="a person-company link">
  The connection between a person and a company — where someone works, or used
  to. A person's `current_company` comes from their highest-priority
  affiliation, so it can change without anyone editing the record.
</ResponseField>

<ResponseField name="Activity" type="an email or a meeting">
  A single interaction: one email, or one calendar event. Activities are the
  raw material of the graph — every relationship score ultimately traces back
  to them. They arrive automatically from connected mailboxes and calendars;
  you do not create them through the API.
</ResponseField>

<ResponseField name="Meeting" type="a calendar activity">
  A calendar-event activity where a ring member is a participant. The meetings
  endpoints are a view over calendar activity scoped to a specific member,
  which is why they need user context.
</ResponseField>

<ResponseField name="Opportunity" type="a deal or workstream">
  Whatever your firm is trying to move forward — a deal, a fundraise, a
  mandate, a search. Has a **type** and a **stage**, an owner, a value, and a
  probability. Opportunities can nest: a parent opportunity can have
  sub-opportunities beneath it.
</ResponseField>

<ResponseField name="Opportunity type and stage" type="your pipeline's shape">
  Each ring defines its own types (for example "Investment" or "Fundraise"),
  and each type has its own ordered stages. Stages belong to a type, so fetch
  the type first, then its stages. Both are UUIDs, not free text — resolve them
  before creating an opportunity.
</ResponseField>

<ResponseField name="Note" type="written context">
  Rich-text notes — meeting write-ups, call summaries, diligence observations.
  A note has a subject, an HTML body, and associations to the entities it is
  about. Notes are searchable by meaning, not just keyword.
</ResponseField>

<ResponseField name="Task" type="a follow-up">
  An actionable item with an optional assignee, due date, and reminders. Tasks
  are either `RING` (visible to everyone in the ring) or `PERSONAL` (visible
  only to their creator — other members get a `404`).
</ResponseField>

<ResponseField name="Entity list" type="a named collection">
  A saved group of people or companies — a target list, a portfolio, a
  conference roster. A list holds one kind only: a person list cannot contain
  companies. Lists return member UUIDs, which you then hydrate.
</ResponseField>

<ResponseField name="Association" type="a link between records">
  How a note, task, or opportunity attaches to the people and companies it
  concerns. One note can be associated with several entities at once. This is
  the join that makes "everything we know about Acme" answerable.
</ResponseField>

## Relationship intelligence

These are the scores that make Rings more than a contact database.

<ResponseField name="Signal" type="evidence of a relationship">
  The underlying record that one ring member has a relationship with one
  external person, inferred from their shared activity. Signals are what
  every score below is computed from. A person with no signals has no scores —
  which is why some fields come back `null` rather than zero.
</ResponseField>

<ResponseField name="Relationship Quality (RQ)" type="1–3, per member">
  How strong one specific ring member's relationship with one specific person
  is. `1` is weak, `3` is strong. RQ is per-member, so the same external person
  can be a `3` for one colleague and `null` for another.

  The canonical field is `priority_management.rq`. Ignore `rq_manual` and
  `rq_math` — they are inputs, not the answer.
</ResponseField>

<ResponseField name="PathPower" type="0.0–1.0, whole ring">
  How strong your **organisation's** overall relationship with a person or
  company is — the ring-wide view, where RQ is the per-member one. A person's
  PathPower is derived from the RQ signals every member has with them. A
  company's PathPower averages the top five person scores among people
  affiliated with it.

  | `strength_label` | Score     |
  | ---------------- | --------- |
  | `weak`           | 0.0 – 0.2 |
  | `moderate`       | 0.2 – 0.4 |
  | `strong`         | 0.4 – 0.6 |
  | `very_strong`    | 0.6 – 1.0 |

  `score` is the raw `0.0`–`1.0` value and `score_display` is the same number
  as `0`–`100`. PathPower answers "how well do we know them", not "who should
  make the intro" — for that, use recommended paths.
</ResponseField>

<ResponseField name="Recommended paths" type="who should make the intro">
  Given a target person or company, the ranked list of ring members best placed
  to open the door, each with the hops connecting them to the target. This is
  the endpoint behind "who can introduce me to Acme". PathPower gives you a
  number; recommended paths give you a name and a route.
</ResponseField>

<ResponseField name="Strongest relationships" type="the quick version">
  The top two ring members with the strongest connection to a person or
  company, precomputed and returned inline on detail and list responses. Use it
  when you want the headline without a second call; use recommended paths when
  you need the full ranking and the hops. Refreshed every few hours, so it can
  trail a very recent introduction.
</ResponseField>

<ResponseField name="Last contact and last activity">
  `last_contact_at` and `last_activity_date` are the same value under two
  names: the most recent interaction anyone in the ring had with that entity.
  `last_engaged_at`, which appears inside strongest relationships, is narrower
  — the last interaction between that *particular* member and the entity.
</ResponseField>

## Data model details

<ResponseField name="Global vs ring records">
  Some people and companies come from shared reference data available to every
  ring; others your team created or enriched privately. When both exist, your
  ring's version wins, and lookups rank your records above global ones. This is
  why a company can appear with details nobody at your firm entered.
</ResponseField>

<ResponseField name="Visibility and 404s">
  Every request is scoped to your ring. When a record exists in Rings but your
  ring cannot see it, the API returns `404` — the same response as a record
  that does not exist. This is deliberate: it prevents one ring learning what
  another holds. Read `404` as "not available to you", not "no such record".
</ResponseField>

<ResponseField name="Custom fields">
  Ring-defined fields on companies and opportunities, keyed by field UUID
  rather than name. Writing them replaces the whole object — there is no
  per-key merge, so send every key you want to keep.
</ResponseField>

<ResponseField name="UUIDs">
  Every entity is identified by a UUID, and almost every endpoint takes one.
  When you start from an email address, a domain, or a name, resolve it first
  with a lookup endpoint. To resolve several at once, use the batch lookup
  endpoints rather than looping.
</ResponseField>

## Quick reference

| Term                    | In one line                                                |
| ----------------------- | ---------------------------------------------------------- |
| Ring                    | Your organisation's workspace. Also called a tenant.       |
| Ring member             | A colleague inside your ring.                              |
| Ringmaster              | A ring member with administrative rights.                  |
| Internal / external     | Ring members / everyone else.                              |
| Person                  | A human, identified by `person_uuid`.                      |
| Company                 | An organisation, identified by `company_uuid`.             |
| Affiliation             | The link between a person and a company.                   |
| Activity                | One email or one calendar event.                           |
| Meeting                 | A calendar activity a ring member attended.                |
| Opportunity             | A deal or workstream, with a type and a stage.             |
| Note                    | A rich-text write-up attached to entities.                 |
| Task                    | A follow-up, either ring-visible or personal.              |
| Entity list             | A saved group of people or companies.                      |
| Association             | The link joining a note, task, or opportunity to entities. |
| Signal                  | Evidence that a member knows an external person.           |
| RQ                      | One member's relationship strength with one person, 1–3.   |
| PathPower               | The whole ring's relationship strength, 0.0–1.0.           |
| Recommended paths       | Ranked members who can make the introduction.              |
| Strongest relationships | The precomputed top two connectors.                        |
| User context            | Telling the API which member is asking.                    |

## Where to go next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first call.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Every endpoint in detail.
  </Card>

  <Card title="MCP Guide" icon="plug" href="/guides/mcp">
    Give an AI agent access to the graph.
  </Card>
</CardGroup>