# Rings AI > Relationship Intelligence ## Docs - [Company activities](https://docs.rings.ai/api-reference/activity/company-activities.md): Returns a paginated list of emails and calendar meetings where any participant is associated with the company, ordered by date descending. - [Company activity stats](https://docs.rings.ai/api-reference/activity/company-activity-stats.md): Returns activity counts (emails, meetings, total) across different time periods. - [Bulk company activity stats](https://docs.rings.ai/api-reference/activity/company-activity-stats-batch.md): Body: `uuids` (company UUIDs, max 100), plus the same optional `periods` `group_by`, and `sort_by` controls as the single-entity endpoint. `results` holds one entry per input UUID, in order. UUIDs with no data — or that the identified user is not authorized to read — come back with empty `periods` r… - [Get activity body](https://docs.rings.ai/api-reference/activity/get-body.md): Access is enforced via grant ownership + explicit EmailAccessPermission. Returns: - 404 when the activity / message can't be resolved for the caller - 403 when the caller has no active grant for the activity's owner - [Get activity thread](https://docs.rings.ai/api-reference/activity/get-thread.md): Scoped to the caller's tenant (via `tenant_uuid`) to prevent cross-tenant thread spills. Only EMAIL activities are returned — calendar events share `thread_id=None` semantics and would muddy the result set. - [Person activities](https://docs.rings.ai/api-reference/activity/person-activities.md): Returns a paginated list of emails and calendar meetings where the person was a participant, ordered by date descending. Each item includes participants, from/to addresses (for emails), start/end times (for meetings), and attachment counts. - [Person activity stats](https://docs.rings.ai/api-reference/activity/person-activity-stats.md): Returns activity counts (emails, meetings, total) across different time periods. - [Bulk person activity stats](https://docs.rings.ai/api-reference/activity/person-activity-stats-batch.md): Body: `uuids` (person UUIDs, max 100), plus the same optional `periods` `group_by`, and `sort_by` controls as the single-entity endpoint. `results` holds one entry per input UUID, in order. UUIDs with no data — or that the identified user is not authorized to read — come back with empty `periods` ra… - [AI summary for a company](https://docs.rings.ai/api-reference/ai-summary/company.md): Generates a live summary using the same pipeline as the web app. Returns 404 when the entity is not found. - [AI summary for a person](https://docs.rings.ai/api-reference/ai-summary/person.md): Generates a live summary using the same pipeline as the web app. Returns 404 when the entity is not found. - [Create a company](https://docs.rings.ai/api-reference/company/create-company.md): Dedupe: if the payload's `linkedin_url` or `website` matches an existing tenant-visible company (incl. Crunchbase / Rings Research globals), that record's UUID is reused so the tenant row converges onto the canonical entity instead of forking a duplicate. If no match is found, the downstream write g… - [Get a company](https://docs.rings.ai/api-reference/company/get-company.md) - [List companies](https://docs.rings.ai/api-reference/company/list-companies.md) - [Lookup a company](https://docs.rings.ai/api-reference/company/lookup.md) - [Batch lookup companies](https://docs.rings.ai/api-reference/company/lookup-batch.md): Each entry in `queries` is resolved independently using the same matching semantics as `GET /v1/companies/lookup`. Results are returned in the same order as the input. - [Update a company](https://docs.rings.ai/api-reference/company/update-company.md): Only fields provided in the request body are written; other attributes on the existing record are preserved. Returns 404 if the company is not visible in the tenant Explorer view. - [Overview](https://docs.rings.ai/api-reference/introduction.md): The Rings AI REST API - [Create an entity list](https://docs.rings.ai/api-reference/lists/create-list.md): `entity_uuids`, if provided, are added as members at creation time (same `entity_kind` as the list's `kind`). List names are unique per tenant per `kind` — returns 409 if `name` is already in use for that `kind`. - [List entity lists](https://docs.rings.ai/api-reference/lists/list-lists.md): Filter parameters (all optional): - name: Exact (case-sensitive) name match - search: Case-insensitive substring search on name - kind: PERSON or COMPANY - [Update an entity list](https://docs.rings.ai/api-reference/lists/update-list.md): Mirrors GraphQL `updateEntityList`: only the list's owner or a tenant ringmaster may update it (404 otherwise); membership is not affected. Only fields provided in the request body are written. - [Get a meeting](https://docs.rings.ai/api-reference/meetings/get-meeting.md): if the user is an internal participant. - [List meetings](https://docs.rings.ai/api-reference/meetings/list-meetings.md): Only meetings where the user appears as an internal calendar participant (same scope as in-app meeting tools) are returned. - [Add note association](https://docs.rings.ai/api-reference/note/add-association.md): Idempotent on duplicates: if the association already exists the existing row is returned (still status 201 for client simplicity — matches the opportunity association sub-endpoint). - [Batch create notes](https://docs.rings.ai/api-reference/note/batch-create.md): associations and optional per-note idempotency. - [Create a note](https://docs.rings.ai/api-reference/note/create-note.md): Full HTML `content` goes to S3 under the new note UUID, a plain-text excerpt is persisted on the DB row. - [Delete note association](https://docs.rings.ai/api-reference/note/delete-association.md): Returns 204 on success and 404 when the association doesn't exist or doesn't belong to the referenced note. - [Delete a note](https://docs.rings.ai/api-reference/note/delete-note.md): Only the note's owner or a ringmaster may delete it. Returns 204 on success, 404 when the note isn't visible to the caller's tenant, and 403 when the caller is neither the owner nor a ringmaster. - [Get a note](https://docs.rings.ai/api-reference/note/get-note.md): Reads the row via `Note.by_uuid` (tenant/ring scoped) and fetches the HTML body from S3. Missing S3 objects degrade to the stored DB excerpt rather than erroring. - [List notes](https://docs.rings.ai/api-reference/note/list-notes.md): Supports: - `entity_uuid` + `entity_type`: notes associated with that entity (either via the generic `associations` table or, for PERSON/COMPANY, the legacy `rings_*_uuid` columns). - `search`: full-text match over `search_vector`. - Standard pagination, `sort_by`, `order`. - [Search notes](https://docs.rings.ai/api-reference/note/search.md): Performs hybrid vector + full-text search and returns results grouped by source note with matching text snippets. `search_mode=comprehensive` additionally reranks results with a cross-encoder against person/company context (not just raw note text) for broad, ambiguous asks — e.g. "give me everyone I… - [Update a note](https://docs.rings.ai/api-reference/note/update-note.md): Only provided fields are written. If `content` is provided the S3 object is re-uploaded and the excerpt on the DB row is refreshed; omitting `content` leaves the stored HTML untouched. 404s when the note isn't visible for the caller's tenant. - [Add opportunity association](https://docs.rings.ai/api-reference/opportunity/add-association.md): entity_type must be one of (uppercase): PERSON, COMPANY, NOTE, FILE, TASK, OPPORTUNITY. Unlike notes/tasks, OPPORTUNITY-to-OPPORTUNITY associations are allowed. Rejects with 404 when the opportunity or target entity doesn't exist for this tenant. Idempotent on duplicate associations — returns the ex… - [Create an opportunity](https://docs.rings.ai/api-reference/opportunity/create-opportunity.md): Required fields: name, type_uuid, stage_uuid. If the user hasn't specified an opportunity type or stage, ask them before calling this endpoint. - [Delete opportunity association](https://docs.rings.ai/api-reference/opportunity/delete-association.md): Returns 204 on success, 404 if the association doesn't exist or doesn't belong to the referenced opportunity. - [Get an opportunity](https://docs.rings.ai/api-reference/opportunity/get-opportunity.md): Returns the complete opportunity including stage, type, owner, intro person, associated persons and companies, custom fields, days in current stage, notes/files count, and activity dates. Returns 404 if the opportunity is not visible in the tenant's ring. - [List opportunities for a company](https://docs.rings.ai/api-reference/opportunity/list-by-company.md): Scoped to opportunities that have the given company as an association. Only the `name`, `opportunity_type_uuid`, and `opportunity_stage_uuid` filters from GET /v1/opportunities are applied here; other filter parameters are accepted but ignored. Sorting and pagination match GET /v1/opportunities. - [List opportunities for a person](https://docs.rings.ai/api-reference/opportunity/list-by-person.md): Scoped to opportunities that have the given person as an association. Only the `name`, `opportunity_type_uuid`, and `opportunity_stage_uuid` filters from GET /v1/opportunities are applied here; other filter parameters are accepted but ignored. Sorting and pagination match GET /v1/opportunities. - [List opportunities](https://docs.rings.ai/api-reference/opportunity/list-opportunities.md): Returns a paginated list of opportunities visible to the tenant ring. - [List opportunity stages](https://docs.rings.ai/api-reference/opportunity/list-stages.md): Use this to discover a valid `stage_uuid` before creating an opportunity. Pass `stage_type=PARENT` (default) for top-level opportunities or `stage_type=CHILD` for sub-opportunities. A stage is only valid when paired with the `type_uuid` it belongs to. - [List opportunity types](https://docs.rings.ai/api-reference/opportunity/list-types.md): Use this to discover a valid `type_uuid` before creating an opportunity. Each item's `pinning_config` declares whether a person/company association is required for that type. To get the matching `stage_uuid`, call GET /v1/opportunity-types/{type_uuid}/stages. - [Update an opportunity](https://docs.rings.ai/api-reference/opportunity/update-opportunity.md): Only fields present in the request body are written; other attributes on the existing record are preserved. Association edits go through the dedicated associations sub-resource (see below). Returns 404 if the opportunity is not visible under the tenant's ring. - [Bulk PathPower scores](https://docs.rings.ai/api-reference/pathpower/bulk-scores.md): Parameters: - entity: person | company (required) - uuids: comma-separated list of entity UUIDs (max 100) - [PathPower for a company](https://docs.rings.ai/api-reference/pathpower/company.md): Returns a single aggregate score (0.0–1.0) measuring how strongly the tenant's team is connected to this company. This is a numeric strength indicator only — it does NOT return connection paths or introductions. - [PathPower for a person](https://docs.rings.ai/api-reference/pathpower/person.md): Returns a single aggregate score (0.0–1.0) measuring how strongly the tenant's team is connected to this person. This is a numeric strength indicator only — it does NOT return connection paths or introductions. - [Batch create persons](https://docs.rings.ai/api-reference/person/batch-create.md): For each entry: if `email` or `linkedin_url` matches an existing tenant-visible person, that person is returned (status MATCHED) without a write; otherwise a new tenant-source record is created (status CREATED). This mirrors the matching of `GET /v1/persons/lookup`, but is broader than the dedupe on… - [Create a person](https://docs.rings.ai/api-reference/person/create-person.md): All fields are optional. If the provided `email` matches an existing person in the tenant, the existing record is updated in place and its UUID is returned (deduplication by email). Returns the UUID and rings_updated_at timestamp on success. - [Get a person](https://docs.rings.ai/api-reference/person/get-person.md): Returns the full person record including: - strongest_relationships: top 2 internal team members with the strongest connection to this person (use for "who internally knows X" without needing recommended-paths) - pathpower: overall relationship strength score (0.0–1.0) - priority_management.rq:… - [List persons](https://docs.rings.ai/api-reference/person/list-persons.md): Returns a paginated list of people visible to the tenant. All filter parameters are optional — omitting all of them returns all persons. - [Lookup a person](https://docs.rings.ai/api-reference/person/lookup.md): Searches across tenant-visible persons (including global records). At least one of email, linkedin_url, domain, or name must be provided. Returns up to `limit` matches (default 5, max 20), ranked so tenant-specific records appear before global ones. - [Batch lookup persons](https://docs.rings.ai/api-reference/person/lookup-batch.md): Each entry in `queries` is matched independently using the same semantics as `GET /v1/persons/lookup` (email, linkedin_url, domain, or fuzzy name match). Results are returned in the same order as the input queries. Entries with no matching criteria return empty matches rather than an error. - [Merge persons](https://docs.rings.ai/api-reference/person/merge-person.md): Always tenant-scoped to the caller's own tenant -- there is no REST option for GLOBAL scope or admin overrides. Set `preview=true` for a read-only dry run: nothing persists, and the response's `preview` field describes the canonical/superseded/merged entities as they would look post-merge. Returns 4… - [Update a person](https://docs.rings.ai/api-reference/person/update-person.md): Fields omitted from the request body are left unchanged on the existing record. Returns 404 if the person UUID is not visible in the tenant's Explorer view. Returns the UUID and updated rings_updated_at timestamp on success. - [Recommended paths to a company](https://docs.rings.ai/api-reference/recommended-paths/company.md): "who internally knows people at this company" / "best path into" queries. - [Bulk recommended paths (companies)](https://docs.rings.ai/api-reference/recommended-paths/company-batch.md): Body: `uuids` (company UUIDs, max 100) plus optional `limit` (top contacts per target, default 25, max 100), `sort_by`, `order`, and `include_items`. `results` holds one entry per input UUID, in order; each carries that target's `total`, its top contacts, and the company's `top_external_contacts` (t… - [Recommended paths to a person](https://docs.rings.ai/api-reference/recommended-paths/person.md): "who knows this person" / "introduce me to" / "path to" queries. - [Bulk recommended paths (persons)](https://docs.rings.ai/api-reference/recommended-paths/person-batch.md): Body: `uuids` (person UUIDs, max 100) plus optional `limit` (top contacts per target, default 25, max 100), `sort_by`, and `order`. `results` holds one entry per input UUID, in order; each carries that target's `total` and its top contacts. Targets that are not found come back with empty `items` rat… - [My relationships](https://docs.rings.ai/api-reference/relationships/mine.md): Backed by the per-user MR precompute (one parquet per user). This is the individual counterpart to GET /v1/relationships: it returns only the people the bound user knows, sorted by that user's own relationship_quality, and skips the team aggregation / overlay enrichment that the ring-wide endpoint d… - [List ring relationships](https://docs.rings.ai/api-reference/relationships/ring.md): Backed by the MRR precompute (refreshed every ~2h), so it can sort by relationship_quality (RQ) and PathPower — unlike the live persons list, which only sorts by name or last activity date. Each item is one external person with their embedded primary company, RQ, PathPower, priority signals, AI scor… - [Add task association](https://docs.rings.ai/api-reference/task/add-association.md): Links a person, company, note, file, or opportunity to the task. TASK-to-TASK links are not allowed. Returns 201 with the association record; if an identical association already exists the existing record is returned (idempotent). Returns 404 if the task is not visible to the caller. - [Create a task](https://docs.rings.ai/api-reference/task/create-task.md): Creates a task and optionally assigns it to users and associates it with entities (persons, companies, opportunities, etc.) in a single atomic operation. Returns the new task id on success. - [Delete task association](https://docs.rings.ai/api-reference/task/delete-association.md): Returns 404 when the association doesn't exist or doesn't belong to the given task. - [Delete a task](https://docs.rings.ai/api-reference/task/delete-task.md): PERSONAL tasks can only be deleted by their creator; RING tasks can be deleted by any tenant member. - [Get a task](https://docs.rings.ai/api-reference/task/get-task.md): Returns the full task including assignments. PERSONAL tasks are only returned for their creator; RING tasks are visible to any tenant member. Returns 404 when the task doesn't exist or isn't visible to the caller. - [List tasks](https://docs.rings.ai/api-reference/task/list-tasks.md): Returns a paginated list of tasks visible to the caller. PERSONAL tasks created by other users are excluded. ARCHIVED tasks are excluded unless include_archived=true is passed. - [Update a task](https://docs.rings.ai/api-reference/task/update-task.md): Omitted fields are left unchanged on the existing record. To mark a task as done, set status="COMPLETED". To remove a due date, pass clear_due_date=true instead of setting due_date to null. To remove a reminder, pass clear_reminder=true. - [List users](https://docs.rings.ai/api-reference/users/list-users.md): Returns active users that can be used with the x-rings-user-id header to enable per-user context on supported endpoints. - [Get current user](https://docs.rings.ai/api-reference/users/me.md): Designed for MCP and AI agent clients that need to resolve "me", "my", or "I" into concrete UUIDs before calling other endpoints (e.g. fetching activity history or relationship data for the current user). - [MCP Guide](https://docs.rings.ai/guides/mcp.md): Connect AI tools to Rings via the Model Context Protocol - [Introduction](https://docs.rings.ai/index.md): Relationship intelligence for revenue teams - [Quickstart](https://docs.rings.ai/quickstart.md): Make your first Rings API call in under 5 minutes ## OpenAPI Specs - [openapi](https://production-api.joinrings.com/openapi.json)