API reference / Workspace

GET

Get the workspace

https://app.ridgetop.io/api/v1/workspace

The workspace the key belongs to, and the key itself with its scopes. Use it to check a key works and what it may do.

Required permission: Any workspace API key

Authentication

Send a workspace API key as Authorization: Bearer <WORKSPACE_API_KEY>. Admins create keys under Settings → API keys and choose their scopes. A key belongs to the workspace rather than a person, so keep it on your servers and never in a browser or mobile app. See Getting started.

Responses

Choose a status to see its sample on the right.

Getting started

The REST API under https://app.ridgetop.io/api/v1 is for your own backend. It authenticates with a workspace API key: an admin creates one under Settings → API keys, chooses what it may do, and copies it once. A key belongs to the workspace rather than a person, keeps working when its creator leaves, and has no permissions beyond its scopes. Keep it on your servers.

cURL
curl 'https://app.ridgetop.io/api/v1/users?limit=25' \
  -H 'Authorization: Bearer <WORKSPACE_API_KEY>'
ScopeAllows
guides:readRead guides. List guides and read their published content and state.
guides:writePause guides. Pause a live guide, for example from your release tooling.
surveys:responsesRead survey responses. Individual answers and comments, which can contain personal data.
events:writeSend events. Product events from your backend, such as invoice paid.
people:writeSet people's properties. Properties for guide targeting, such as plan or role.
marketing:readRead marketing. Subscription status and suppressions by email address, Lists and their members, campaign results, social posts, and the marketing calendar.
marketing:writeChange marketing consent and Lists. Set subscription status, add and remove suppressions, and add and remove List members.
users:readRead teammates and teams. Teammates' names, work emails and whether they're active, and the workspace's teams, to match record owners to your own users.
fields:readRead custom fields. Custom field definitions for contacts, companies, deals and conversations: keys, types and options.
contacts:readRead contacts. Contacts with their owner, companies, custom fields and notes, which hold personal data such as names, emails and phone numbers.
companies:readRead companies. Companies with their owner, custom fields, your app's organization IDs, contacts and notes.
contacts:writeCreate and change contacts. Create, update and upsert contacts, including their owner and custom fields, link them to companies, and add notes.
contacts:eraseErase contacts. Permanently erase a contact and everything about them (conversations, analytics, replays, files and notes), as a privacy erasure request does. It can't be undone.
companies:writeCreate and change companies. Create, update and upsert companies, including their owner and custom fields, and add notes.
deals:readRead deals. Deals with their pipeline, stage, value, owner, companies, contacts and roles, custom fields, stage history and notes, and the workspace's pipelines.
deals:writeCreate and change deals. Create, update and delete deals, move them between stages, link companies and contacts with their roles, and add notes.
conversations:readRead conversations. Conversations with their messages, notes and attachments, which hold what customers wrote, and the workspace's AI persona, inboxes, tags, statuses and ticket types.
conversations:writeChange conversations. Change a conversation's status, assignee, priority, ticket type, custom fields and tags, add internal notes, and manage tags.
conversations:replyReply to customers. Send replies customers see, as the workspace's AI persona or as a teammate whose role may reply.
webhooks:writeManage webhooks. Subscribe your endpoints to record events, such as contact.updated or deal.stage_changed, and rotate their secrets. Events are only for records the key can read.
knowledge:readRead knowledge. Help centers, collections and articles, drafts and internal articles included.
knowledge:writeWrite articles. Create and change draft articles and submit them for review, and manage collections, as an author does.
knowledge:publishPublish articles. Publish and unpublish articles and change live ones, as a publisher does.
scheduling:readRead scheduling. Event types (booking pages) with their hosts, and bookings with the attendee's answers.
scheduling:writeManage scheduling. Create and change event types and their hosts, and cancel bookings, which emails the attendee.
development:readRead development. Projects with their statuses, sprints, issues with their custom fields and linked conversations, and comments.
development:writeChange development issues. Create and change issues, move them through their project's lifecycle, and comment as a teammate.
learning:readRead learning. Academies, categories, programs and courses with their full outlines, quiz answers included.
learning:writeWrite courses. Create and change academies, categories, programs and draft courses, and sync course outlines by your own IDs.
learning:publishPublish courses. Publish, unpublish and archive courses and programs, and change live ones, as a publisher does.
learning:enrollEnroll learners. Enroll teammates and contacts in courses and programs, set due dates, and read their progress and scores.
sequences:readRead sales sequences. Shared sales sequences and their steps, who is in them and how far they've got, and shared sales email templates.
sequences:writeEnroll in sales sequences. Enroll contacts in shared sales sequences as a teammate you name, from an address they may send from, and pause, resume, skip or remove their enrollments.
workflows:readRead workflows. Workflows with their paths, steps and settings, and the problems the builder would show, including AI instructions and message text.
workflows:writeBuild workflows. Create workflows and save new draft versions, as an administrator does in the builder. A draft never runs until it is published.
workflows:publishPublish workflows. Publish a workflow's draft and turn it on, so it runs on new records. Publishing AI steps that send to customers without review also needs Reply to customers.

Everything an integration does goes through this REST API with a workspace API key. The Messenger SDK, agent, workflow and status endpoints further down are for those surfaces and each name their own credential.

Responses and objects

A success is the payload itself, with no wrapper: one record as { "user": { … } }, a list as { "users": [ … ], "nextCursor": … }. Every full record names its type in object (user, team, field, guide…), so one handler can tell records apart wherever they come from.

Field names are camelCase. IDs are UUIDs. Times are ISO 8601 in UTC, ending in Z; dates are YYYY-MM-DD. A field with no value is null, never left out. Lists of values (enumerations) can gain new values, so treat one you don't know as “other” rather than failing.

A teammate on any record (an owner, assignee or author) is always the same four fields, so you can match them to your own users by email:

JSON
{
  "owner": {
    "id": "7d3f2a10-5c4e-4b8a-9f21-0c6e1b2a3d45",
    "name": "Alex Rivera",
    "email": "alex@acme.example",
    "active": true
  }
}

Custom fields are keyed by the field's key, which keeps the case the workspace gave it (plan_tier). List them with GET /v1/fields.

Errors

Every REST API failure has the same shape. Branch on error.code, not on the status or the message: the message is written for people and can change. Quote requestId when you contact us; every response also carries it in the X-Request-Id header. The top-level message beside error is a deprecated copy of error.message; don't read it.

Error JSON
{
  "error": {
    "code": "invalid_input",
    "message": "limit can be at most 100.",
    "requestId": "3f2b8c1e-7d4a-4b6e-9c0f-1a2b3c4d5e6f",
    "details": {
      "parameter": "limit"
    }
  }
}

A body with invalid fields lists every problem at once in details.fields, so you can fix them all in one go. Each has a path (owner.email, customFields.seats, contacts.2.email in a batch), a code to branch on (required, invalid_type, invalid_format, too_long, unknown_field, invalid_option, not_found, user_not_found, user_inactive, duplicate, field_archived, required_by_stage, required_fields_missing, not_allowed) and a message. A duplicate is a conflict whose details.existingId names the record that already exists.

Error JSON · invalid fields
{
  "error": {
    "code": "invalid_input",
    "message": "2 fields are invalid.",
    "requestId": "3f2b8c1e-7d4a-4b6e-9c0f-1a2b3c4d5e6f",
    "details": {
      "fields": [
        {
          "path": "owner",
          "code": "user_inactive",
          "message": "That teammate has been deactivated. Choose an active teammate."
        },
        {
          "path": "customFields.seats",
          "code": "invalid_type",
          "message": "seats must be a number, such as \"40\" or 12.5."
        }
      ]
    }
  }
}
CodeStatusMeans
unauthorized401No valid credential: the key is missing, revoked or expired.
forbidden403The credential is valid but lacks the scope or permission. Signing in again won't help.
plan_required402The workspace plan doesn't include this area, or (details.reason billing_locked) its billing needs attention.
invalid_input400The request is malformed or fails validation. details.parameter names a bad query parameter.
not_found404No such record, or none this caller may see.
gone410It existed and deliberately won't come back, such as a used link or a retired endpoint.
conflict409The request is valid, but the record's current state forbids it.
payload_too_large413The body is over the endpoint's size limit.
rate_limited429Too many requests. Wait the Retry-After seconds, then retry.
unavailable503A dependency is down. Retry with backoff.
internal500Something failed on our side. Quote the requestId when you contact us.

Paging and rate limits

Lists return a page at a time. Send limit (1 to 100, 25 by default, unless an endpoint says otherwise) and, for the next page, cursor set to the previous page's nextCursor. nextCursor is null on the last page. Cursors are opaque: pass them back as they were returned. A parameter a list doesn't know, or a value it can't use, is refused with invalid_input rather than ignored.

Each key may make 600 requests a minute. Every response says where the key stands: RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until the minute resets). Past the limit the answer is 429 rate_limited with Retry-After in seconds.

Node.js · every page, with retries
let cursor = null;
do {
  const url = new URL("/api/v1/users", "https://app.ridgetop.example");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.RIDGETOP_API_KEY}` } });
  if (response.status === 429) {
    await new Promise((resolve) => setTimeout(resolve, Number(response.headers.get("Retry-After") ?? 1) * 1000));
    continue;
  }
  const page = await response.json();
  if (!response.ok) throw new Error(`${page.error.code}: ${page.error.message} (request ${page.error.requestId})`);
  for (const user of page.users) console.log(user.email);
  cursor = page.nextCursor;
} while (cursor);

Safe retries

A request that timed out may still have worked. To retry a POST without creating a second record, send an Idempotency-Key header: any value up to 255 visible characters that you make once per request, such as a UUID. The first request with a key runs. A retry with the same key and the same body gets the first success back, with the same status and body and Idempotent-Replayed: true, without doing the work again. Keys belong to one API key and are kept for 24 hours.

A failure keeps nothing, so a request that failed can be retried with the same key. Reusing a key with a different body is 409 conflict with details.reason idempotency_key_reused; retrying while the first request is still running is 409 conflict with idempotency_key_in_progress, so wait a moment and retry. Endpoints that take the header list it under Parameters. PATCH, PUT and DELETE are safe to repeat as they are, and upserts match on your own IDs, so you can retry those without one.

cURL
curl -X POST 'https://app.ridgetop.io/api/v1/contacts' \
  -H 'Authorization: Bearer <WORKSPACE_API_KEY>' \
  -H 'Idempotency-Key: 6f1c2a8e-4b7d-4e19-9c3a-2d5e8f0b1a47' \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@analytical-engines.example"}'

Webhooks

Ridgetop sends webhooks two ways. Record events tell your app when a contact, company, deal, conversation or message changes, so you don't have to poll: subscribe an https endpoint with POST /v1/webhooks and the events you want. Workflow webhooks are sent by a workflow's Send webhook step, to a destination people who manage workflows add under Settings → Connected apps → Webhooks, which also lists every subscription.

The record events are contact.created, contact.updated, contact.merged and contact.deleted; the same four for company, deal (plus deal.stage_changed) and conversation; message.created for every reply and note; and enrollment.created, enrollment.completed and enrollment.deleted for course enrollments, with the same three for program_enrollment; and sequence_enrollment.created, sequence_enrollment.finished and sequence_enrollment.stopped for people in shared sales sequences. Subscribe to contact.* and so on for all of a record's events. Each body is the record in the API's own shape, and an update says what changed in previous: the changed fields, as they were.

Record event
{
  "object": "event",
  "id": "evt_5d2e8c1a-3b4f-4e6d-9a0b-1c2d3e4f5a6b",
  "type": "deal.stage_changed",
  "createdAt": "2026-11-02T15:04:05.000Z",
  "workspaceId": "0b5e2c1a-7d3f-4a8e-9b6c-2d1e0f3a4b5c",
  "data": {
    "deal": {
      "object": "deal",
      "id": "9a6d0b13-7e2c-4c85-b4f9-3a1e8d6c2b70",
      "name": "Enterprise rollout",
      "stage": {
        "id": "3e8b1d27-6a5f-4c09-9e14-7b2a0c5d8f61",
        "name": "Proposal"
      },
      "…": "…"
    }
  },
  "previous": {
    "stage": {
      "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
      "name": "Discovery"
    }
  }
}

data is the record when the event is sent, usually seconds after the change, so after quick successive changes two events can carry the same record; previous is what each change replaced. A conversation's tag, deal or issue change has changed naming which (["tags"]) and an empty previous. A .deleted event carries only { object, id, deleted: true }, and a record too large to send has omitted: true: fetch it from the API. Use id to ignore an event you've already handled, and don't rely on order. A key subscribes only to events about records it can read, and nothing is sent about people whose processing is restricted.

A workflow webhook's body is { id, type, createdAt, workspaceId, workflow: { id, name }, data }, where type is the workflow's trigger (for example support.survey_answered) and data holds the event's values by the same names as the workflow's {{variables}}, such as record.title. Workflows can also receive webhooks: a workflow on the Webhook received trigger has its own URL, documented under Workflows in the API reference.

Both kinds come with the headers Ridgetop-Event, Ridgetop-Delivery (one per endpoint and try) and Ridgetop-Signature; a test has the type ping. Answer with any 2xx status within 8 seconds. Anything else is retried after 1, 5 and 30 minutes, then 2, 6, 12 and 24 hours, and after 50 failures in a row the endpoint is turned off until it's turned back on. Redirects aren't followed.

Ridgetop-Signature is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of t, a period and the raw body, keyed with the endpoint's whsec_ secret. For 24 hours after a new secret there are two: t=…,v1=<new>,v1=<old>, so you can switch secrets without missing a delivery. Check the signatures against the raw body before parsing, accept if any is yours, and reject timestamps more than five minutes old.

Node.js
import { createHmac, timingSafeEqual } from "node:crypto";

// For a day after a new secret there are two v1 signatures, one from each
// secret; accept the delivery if any of them is yours.
export function verifyRidgetopWebhook(rawBody, header, secret) {
  const parts = header.split(",").map((part) => part.split("="));
  const timestamp = Number(parts.find(([name]) => name === "t")?.[1]);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  return parts
    .filter(([name]) => name === "v1")
    .some(([, value]) => {
      const given = Buffer.from(value ?? "", "hex");
      return given.length === expected.length && timingSafeEqual(given, expected);
    });
}

ChatGPT MCP connection

Connect ChatGPT to read Ridgetop support conversations, customers, knowledge articles, and internal Development docs. The endpoint uses OAuth sign-in and the signed-in employee’s current workspace permissions. It is available after the Ridgetop MCP OAuth provider has been configured.

Streamable HTTP endpoint

https://app.ridgetop.io/mcp

search(query) returns matching record IDs, titles, and Ridgetop links. It searches article and doc titles, summaries, and body text. fetch(id) returns the text of one permitted record. Knowledge articles require knowledge.view, including drafts and internal articles; Development docs require development.view and exclude archived pages. The public API reference on this page is separate from those Development docs. count_conversations counts conversations by assignment, status, and channel. list_conversations uses the same filters and returns up to 50 matching records per page with an exact total and next offset; use fetch(id) for a full conversation transcript. top_email_contacts ranks customer contacts by inbound emails for a selected period, including last calendar week in the workspace timezone. Search and fetch also cover guides and surveys (with guides.view; fetch includes the last 30 days of results) and ideas (with feedback.view; fetch includes demand and linked work), when the plan includes in-app guides. Reports answer questions such as “What's our NPS this month?” or “Which guides are failing?”: list_guides, get_guide_results, list_surveys, get_survey_results, get_survey_breakdown, get_csat_report, list_ideas and get_idea, each offered when the employee has its permission. They return scores and totals, never individual survey answers. With Marketing access, list_marketing_campaigns, get_marketing_campaign_report, list_social_posts, get_social_post_report and get_marketing_calendar answer questions such as “How did last week's newsletter do?”, “Which LinkedIn post brought the most forms?” or “What's planned for November?”; nothing is ever sent or published through MCP. All tools are read-only and require the records:read OAuth scope; conversation counts, lists, and email rankings also require inbox.view.