Use the upcoach API and webhooks

Use the upcoach API and webhooks

The upcoach API connects your workspace to your own scripts and to tools such as Make or n8n. The API and webhooks are available on every plan.

With the API you can:

• Read your programs, the people in your workspace and in each program, events, activity completions and offer enrollments
• Invite people to a program by email, as participants or coaches, and remove someone from a program
• Get events as they happen with webhooks: someone joins or leaves a program, accepts an invitation, completes an activity, answers an event invitation, or buys or joins an offer

The API can’t create or change programs, content, events, offers or settings. Do those in upcoach.

Who can use it

Only an organization Owner, Admin or Implementation Admin can create API tokens or add webhooks. A token acts as the person who created it, with their permissions, in the workspace it was created in. It stops working at once if that person is removed, deactivated or loses their admin role.

Base URL

Every request goes to:

https://v3.upcoach.com/s/api/v1

You never name your workspace in a request: the token decides it. The API answers in JSON. Ids are UUIDs. Two carry a prefix: workspace ids (org-<uuid>) and webhook event ids (evt_<uuid>). Times are in UTC (ISO 8601), for example 2026-11-11T05:55:44Z.

Authentication

Send your token in the Authorization header of every request:

curl https://v3.upcoach.com/s/api/v1/me \
  -H "Authorization: Bearer <your token>"

The answer names the token’s person, workspace and scopes: see GET /me.

Create a token in Admin Area > Integrations > API: see Create and revoke API tokens.

What a token can do

Each token holds one or more of these scopes:

Scope	Lets the token
api:read	Read programs, members, events, completions and enrollments
api:write	Invite people to programs and remove them, as you
webhooks:manage	Manage webhook subscriptions that send member data to other apps

Lists and pages

Lists come newest first (events come earliest first) as { "data": [...], "next_cursor": "..." }. Pass limit (1 to 100, default 50) and, for the next page, cursor set to the next_cursor you got. next_cursor is null on the last page.

A single item comes as { "data": {...} }.

Errors

Errors share one shape. Match on code, not on the message, which is written for people.

{ "error": { "code": "not_found", "message": "Not found." } }

Status	code	When
401	unauthenticated	The token is missing, invalid, expired or revoked, or was sent to another workspace’s address
403	forbidden	The token lacks the scope, or its person lacks the permission the endpoint needs, is no longer an active Owner, Admin or Implementation Admin, or the workspace is locked until its owner chooses a plan. message says which
404	not_found	Nothing with that id in this workspace. An id from another workspace is not found either
409	conflict	An invite would go over the plan’s client limit or admin seats
422	validation_failed	The request isn’t valid. fields says why, per field
429	rate_limited	Too many requests. Wait for Retry-After seconds
500	server_error	Something went wrong on upcoach’s side. Quote the request_id to support

A 422 example:

{
  "error": {
    "code": "validation_failed",
    "message": "The request is not valid.",
    "fields": { "status": ["The selected status is invalid."] }
  }
}

Rate limits

Limit	How many
Requests per token	120 a minute
Requests per workspace, all its tokens together	600 a minute
Refused tokens (401) from one IP address	30 a minute
Invite emails per workspace	100 an hour and 300 a day, and one per address every 10 minutes
Webhook changes per workspace (adding one, rotating its secret, turning it back on), on the Webhooks page and over the API together	10 a minute and 100 a day
Webhooks made over the API	200 per workspace

Responses to a valid token in an active workspace carry X-RateLimit-Limit and X-RateLimit-Remaining for whichever limit, the token’s or the workspace’s, has fewer requests left. Over a limit, you get a 429 with Retry-After, the seconds to wait:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 52

Changes to the API

Responses can gain new fields at any time, so ignore fields you don’t know.

What to do next

• Create and revoke API tokens: get a token to try the API
• upcoach API endpoint reference: every endpoint, with examples
• Send events to your tools with webhooks: get events as they happen