API reference / Workspace
Get the workspace
https://app.ridgetop.io/api/v1/workspaceThe 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.
| Scope | Allows |
|---|---|
| guides:read | Read guides. List guides and read their published content and state. |
| guides:write | Pause guides. Pause a live guide, for example from your release tooling. |
| surveys:responses | Read survey responses. Individual answers and comments, which can contain personal data. |
| events:write | Send events. Product events from your backend, such as invoice paid. |
| people:write | Set people's properties. Properties for guide targeting, such as plan or role. |
| marketing:read | Read marketing. Subscription status and suppressions by email address, Lists and their members, campaign results, social posts, and the marketing calendar. |
| marketing:write | Change marketing consent and Lists. Set subscription status, add and remove suppressions, and add and remove List members. |
| users:read | Read 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:read | Read custom fields. Custom field definitions for contacts, companies, deals and conversations: keys, types and options. |
| contacts:read | Read contacts. Contacts with their owner, companies, custom fields and notes, which hold personal data such as names, emails and phone numbers. |
| companies:read | Read companies. Companies with their owner, custom fields, your app's organization IDs, contacts and notes. |
| contacts:write | Create and change contacts. Create, update and upsert contacts, including their owner and custom fields, link them to companies, and add notes. |
| contacts:erase | Erase 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:write | Create and change companies. Create, update and upsert companies, including their owner and custom fields, and add notes. |
| deals:read | Read deals. Deals with their pipeline, stage, value, owner, companies, contacts and roles, custom fields, stage history and notes, and the workspace's pipelines. |
| deals:write | Create and change deals. Create, update and delete deals, move them between stages, link companies and contacts with their roles, and add notes. |
| conversations:read | Read 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:write | Change conversations. Change a conversation's status, assignee, priority, ticket type, custom fields and tags, add internal notes, and manage tags. |
| conversations:reply | Reply to customers. Send replies customers see, as the workspace's AI persona or as a teammate whose role may reply. |
| webhooks:write | Manage 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:read | Read knowledge. Help centers, collections and articles, drafts and internal articles included. |
| knowledge:write | Write articles. Create and change draft articles and submit them for review, and manage collections, as an author does. |
| knowledge:publish | Publish articles. Publish and unpublish articles and change live ones, as a publisher does. |
| scheduling:read | Read scheduling. Event types (booking pages) with their hosts, and bookings with the attendee's answers. |
| scheduling:write | Manage scheduling. Create and change event types and their hosts, and cancel bookings, which emails the attendee. |
| development:read | Read development. Projects with their statuses, sprints, issues with their custom fields and linked conversations, and comments. |
| development:write | Change development issues. Create and change issues, move them through their project's lifecycle, and comment as a teammate. |
| learning:read | Read learning. Academies, categories, programs and courses with their full outlines, quiz answers included. |
| learning:write | Write courses. Create and change academies, categories, programs and draft courses, and sync course outlines by your own IDs. |
| learning:publish | Publish courses. Publish, unpublish and archive courses and programs, and change live ones, as a publisher does. |
| learning:enroll | Enroll learners. Enroll teammates and contacts in courses and programs, set due dates, and read their progress and scores. |
| sequences:read | Read sales sequences. Shared sales sequences and their steps, who is in them and how far they've got, and shared sales email templates. |
| sequences:write | Enroll 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:read | Read workflows. Workflows with their paths, steps and settings, and the problems the builder would show, including AI instructions and message text. |
| workflows:write | Build workflows. Create workflows and save new draft versions, as an administrator does in the builder. A draft never runs until it is published. |
| workflows:publish | Publish 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:
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.
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.
| Code | Status | Means |
|---|---|---|
| unauthorized | 401 | No valid credential: the key is missing, revoked or expired. |
| forbidden | 403 | The credential is valid but lacks the scope or permission. Signing in again won't help. |
| plan_required | 402 | The workspace plan doesn't include this area, or (details.reason billing_locked) its billing needs attention. |
| invalid_input | 400 | The request is malformed or fails validation. details.parameter names a bad query parameter. |
| not_found | 404 | No such record, or none this caller may see. |
| gone | 410 | It existed and deliberately won't come back, such as a used link or a retired endpoint. |
| conflict | 409 | The request is valid, but the record's current state forbids it. |
| payload_too_large | 413 | The body is over the endpoint's size limit. |
| rate_limited | 429 | Too many requests. Wait the Retry-After seconds, then retry. |
| unavailable | 503 | A dependency is down. Retry with backoff. |
| internal | 500 | Something 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.
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.
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.
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.
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/mcpsearch(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.