Rhythms REST API v2

REST API v2 is the Rhythms API for third-party integrations, reporting, automation and bulk changes. It offers predictable JSON endpoints under https://api.rhythms.ai/rest/v2/ for Objectives, Key Results, Initiatives, Check-ins, Labels, Teams and Users. This article mirrors the published reference at apidocs.rhythms.ai/rest/v2, where you can also send test requests. To get a token, see Get access to the Rhythms REST API.

Basics

Base URL: https://api.rhythms.ai. All REST API v2 endpoints are prefixed with /rest/v2/.

Response format: JSON. Successful responses wrap the payload in a data object. Error responses use standard HTTP status codes with a short message.

Authentication: every request needs a Bearer token in the Authorization header. The API runs each request with the permissions of the user the token belongs to.

Authorization: Bearer ‹token›

Rate limiting

Rhythms does not publish fixed per-token rate limits today. Keep request volume reasonable — page with limit=100, use count=true instead of walking every page to get a total, and cache what you can. The API reserves 429 Too Many Requests; handle it with a back-off and retry. If you expect sustained high volume, tell [e-mail] about the integration.

Pagination and counts

List endpoints support pagination through query parameters.

Parameter	Type	Default	Description
page	number	1	Page number.
limit	number	20	Records per page, maximum 100.
per_page	number	20	Alias for limit.
limit_max	number	—	Maximum records per page; used as the page size when limit is not set.
count	string	—	Set to true to include the total in data.pagy.count. Use this for totals instead of paginating through every page.

Paginated responses include metadata in data.pagy; next is the next page number, or null when there are no more pages.

Making requests

A first request

curl -H "Authorization: Bearer tokp_1abc23c45d..." \
     -H "Accept: application/json" \
     "https://api.rhythms.ai/rest/v2/objectives?limit=1"

List endpoints return data.records (an array) plus data.pagy:

{
  "data": {
    "type": "Okrs::Objective",
    "records": [
      {
        "uuid": "...",
        "type": "Okrs::Objective",
        "short_id": "OBJ-001",
        "title": "Grow enterprise revenue",
        "current_status": "on_track",
        "start_date": "2026-07-01",
        "end_date": "2026-09-30",
        "owner_uuids": ["..."]
      }
    ],
    "pagy": { "next": 2 }
  }
}

Single-record endpoints return data.record instead of data.records. Record fields are abbreviated above; the live docs carry the full schema.

Filtering

List endpoints accept a q parameter using bracket notation: the attribute name followed by a predicate.

Predicate	Meaning
_eq	exact match
_cont	contains (substring)
_in	value is in a list, e.g. q[current_status_in][]=behind&q[current_status_in][]=at_risk
_gteq / _lteq	greater than or equal / less than or equal — useful on dates
_present / _null	attribute is set / attribute is null

# objectives that have not started
GET /rest/v2/objectives?q[current_status_eq]=not_started

# check-ins since 1 July 2026
GET /rest/v2/checkins?q[checkin_date_gteq]=2026-07-01

# users whose display name contains "Alice"
GET /rest/v2/users?q[display_name_cont]=Alice

# labels that are groups, sorted by name
GET /rest/v2/labels?q[is_group_eq]=true&q[s]=name+asc

Add q[s]=‹attribute›+asc|desc to sort. The attribute before the predicate must be filterable for that endpoint; each section below lists the filterable attributes.

Paging

GET /rest/v2/objectives?page=1&limit=1

data.pagy.next holds the next page number, or null on the last page. Add count=true to include a total in data.pagy.count.

When authentication fails

A missing or invalid token returns 401:

{ "error": "Invalid Authorization header" }

A valid token whose user is not allowed to perform the action returns 403.

Going further

The live docs at apidocs.rhythms.ai/rest/v2 carry the full schema for every endpoint, let you send a real authenticated request from the browser, and let you load the API definition into an AI coding assistant such as Cursor.

API sections

REST API v2 has 7 sections and 34 operations.

Section	Operations
Checkins	5
Initiatives	5
Key Results	5
Labels	5
Objectives	5
Teams	5
Users	4

Checkins

Check-ins record progress updates, status, notes, values and labels for a goal.

Method	Path	Summary
GET	/rest/v2/checkins	List check-ins.
POST	/rest/v2/checkins	Create a check-in.
GET	/rest/v2/checkins/{id}	Get a check-in.
PUT	/rest/v2/checkins/{id}	Update a check-in.
DELETE	/rest/v2/checkins/{id}	Delete a check-in.

List check-ins

GET /rest/v2/checkins returns check-ins newest first and supports filtering and pagination.

Filterable attributes: uuid, goal_uuid, creator_uuid, checkin_date, created_at, status, value, source_type.

Create a check-in

POST /rest/v2/checkins creates a check-in for a goal with an optional value, status and note. Fields are sent at the top level of the JSON body (no wrapper object).

Field	Type	Required	Notes
goal_uuid	string	yes	UUID of the goal being checked in. (checkinable_uuid is accepted as a deprecated alias.)
timezone_offset	number	yes	Your offset from UTC in minutes, as JavaScript's getTimezoneOffset() reports it (negative east of UTC). Must be between -840 and 720.
value	number	no	Check-in value. The goal must have a metric.
status	string	no	Defaults to not_started; one of not_started, in_progress, on_track, behind, at_risk, closed, postponed.
note	string	no	Check-in note.
checkin_date	string	no	YYYY-MM-DD. Defaults to today in your timezone; cannot be in the future.
score	number	no	Score; only stored when status is closed.
progress_mode	string	no	Sets the goal's progress mode: manual, rollup or integration.
labels	array[string]	no	Label names to apply to the check-in.

Checking in on a draft goal publishes it, provided the token's user is allowed to publish it.

Get, update and delete a check-in

• GET /rest/v2/checkins/{id} retrieves a check-in by UUID.
• PUT /rest/v2/checkins/{id} updates value, status, note, score and labels. At least one must be provided. A score is kept only while the status is closed.
• DELETE /rest/v2/checkins/{id} deletes a check-in. If it was the goal's latest check-in, the goal's cached status and progress are recalculated.

Goals: Objectives, Key Results and Initiatives

Objectives, Key Results and Initiatives share the same core goal fields and CRUD pattern. Each type has its own endpoint namespace.

Endpoint namespaces

Goal type	List/create path	Specific record path
Objectives	/rest/v2/objectives	/rest/v2/objectives/{id}
Key Results	/rest/v2/key_results	/rest/v2/key_results/{id}
Initiatives	/rest/v2/initiatives	/rest/v2/initiatives/{id}

{id} accepts either the goal's UUID or its short ID such as OBJ-001 or KR-014. List endpoints return published goals only, ordered by title.

Shared create fields

Used by POST /rest/v2/objectives, POST /rest/v2/key_results and POST /rest/v2/initiatives. Fields are sent at the top level of the JSON body.

Field	Type	Required	Notes
title	string	yes	Goal title.
description	string	no	Goal description.
time_period_uuid	string	yes	Time period UUID. Its dates define the allowed goal date range.
start_date	string	no	YYYY-MM-DD; must fall within the time period and be on or before end_date. Defaults to the period start.
end_date	string	no	YYYY-MM-DD; must fall within the time period and be on or after start_date. Defaults to the period end.
goal_type	string	no	Defaults to aspirational; one of aspirational, committed.
visibility	string	no	Defaults to public; one of public, limited.
team_uuids	array[string]	no	Team UUIDs; default [].
owner_uuids	array[string]	no	Owner UUIDs; default [].
labels	array[string]	no	Label names; default []. Unknown names are created when the token's user may create labels.
delegate_uuids	array[string]	no	Delegate UUIDs; default [].
metric	object	no	Metric configuration.
metric.name	string	no	Defaults to Progress.
metric.start_value	number	no	Defaults to 0.
metric.target_value	number	no	Defaults to 100.
metric.unit	string	no	One of percentage, number, dollar, euro, pound, swiss_franc. Defaults to number for Key Results and to percentage for Objectives and Initiatives — set it explicitly if you need a particular unit.
metric.metric_type	string	no	Defaults to reach; one of reach, stay_above, stay_below, stay_between.
parents	array[object]	no	Parent goal objects, not strings: {"uuid": "‹parent UUID›", "type": "‹parent type›", "is_contributing": true}. is_contributing is optional — omit it to use your workspace's OKR model default for this goal type. Default [].
visible_entities	array[object]	no	Who can see the goal when visibility is limited. Array of objects: {"entity_type": "User" | "Team", "entity_uuid": "<UUID>", "mode": "<visibility mode>"}. Default [].

Shared update fields

Used by PUT /rest/v2/objectives/{id}, PUT /rest/v2/key_results/{id} and PUT /rest/v2/initiatives/{id}. Update fields include title, description, goal_type, visibility, current_status, start_date, end_date, time_period_uuid, team_uuids, owner_uuids, labels, delegate_uuids, progress_mode, metric, parents and visible_entities. Only the fields you send are changed. Changing time_period_uuid resets omitted start and end dates to the new period's boundaries. When you resend parents, include every parent that should remain; a parent left out is unlinked, and a parent resent without is_contributing keeps its current contribution.

Shared delete options

Used by DELETE /rest/v2/objectives/{id}, DELETE /rest/v2/key_results/{id} and DELETE /rest/v2/initiatives/{id}. Deleting through the API removes the goal permanently — unlike deleting in the Rhythms app, it does not go to Trash and cannot be restored. Check the goal's children and links first.

Field	Type	Default	Notes
including_immediate_objectives	boolean	false	Also delete immediate child objectives.
including_immediate_initiatives	boolean	false	Also delete immediate child initiatives.
including_immediate_key_results	boolean	false	Also delete immediate child key results.
delete_hierarchy	boolean	false	Delete the entire hierarchy beneath the goal.

Goal list filters

The Objective, Key Result and Initiative list endpoints support filtering on uuid, type, current_status, last_checkin_date, time_period_uuid, creator_uuid and discarded_at, plus associated filters for time periods, owners, labels, ancestors, teams, child links and delegates.

Labels

Labels can be regular labels or label groups, and can be attached to OKRs and check-ins.

Method	Path	Summary
GET	/rest/v2/labels	List labels and label groups.
POST	/rest/v2/labels	Create a label.
GET	/rest/v2/labels/{id}	Get a label.
PUT	/rest/v2/labels/{id}	Update a label.
DELETE	/rest/v2/labels/{id}	Delete a label.

GET /rest/v2/labels supports filtering on uuid, name, parent_uuid and is_group.

To create or update a label, send a label wrapper object. Create accepts name (required, unique in the workspace), description, parent_uuid (the parent must be a group), is_group and color (a hex code such as #eb5757). Update accepts name, description, parent_uuid and color; send a blank parent_uuid to move a label back to the root, and a blank color to clear it. Whether a label is a group cannot be changed after creation. Creating labels requires a Rhythms Admin token.

Deleting a label also deletes its child labels.

Teams

Teams can have a parent team, owners, members, and an active or archived status.

Method	Path	Summary
GET	/rest/v2/teams	List teams.
POST	/rest/v2/teams	Create a team.
GET	/rest/v2/teams/{id}	Get a team.
PUT	/rest/v2/teams/{id}	Update a team.
DELETE	/rest/v2/teams/{id}	Delete a team.

GET /rest/v2/teams supports filtering on uuid, display_name, parent_uuid, status, is_org and depth, plus associated team membership filters.

To create or update a team, send a team wrapper object.

• Create accepts display_name (required), description, parent_uuid, owner_uuids and member_uuids. A user listed in both arrays becomes a Team Owner.
• Update accepts the same fields plus status, one of active or archived. Status can only be set on update, not on create. Sending owner_uuids replaces the full set of Team Owners; sending member_uuids adds the listed members.

A team can be deleted only if it has no active sub-teams and no OKR relationships.

Users

Users can be listed, created, retrieved and updated. REST API v2 has no user delete operation; deactivate a user by setting status to closed.

Method	Path	Summary
GET	/rest/v2/users	List users.
POST	/rest/v2/users	Create a user.
GET	/rest/v2/users/{id}	Get a user.
PUT	/rest/v2/users/{id}	Update a user.

GET /rest/v2/users supports filtering on uuid, display_name, status, manager_uuid and license_type, plus associated filters for direct teams, team memberships, profile fields and manager fields.

To create or update a user, send a user wrapper object.

• Create requires email (unique in the workspace) and display_name. Optional: license_type (standard, hris_only or guest; default standard), status (active or closed; default active), manager_uuid, and profile_attributes with first_name, last_name, job_title, timezone, locale and about.
• Update accepts display_name, avatar_url (applied only when the user has no avatar yet), status, manager_uuid, license_type and profile_attributes.

A manager_uuid must refer to an existing user, otherwise the request returns 422.

Common response codes

Code	Meaning
200	Success.
201	Created.
400	Bad Request — invalid parameters or malformed request.
401	Unauthorized — invalid or missing token, or the token's user is no longer active.
403	Forbidden — the token's user is not allowed to perform this action in Rhythms.
404	Not Found — resource does not exist.
422	Unprocessable Entity — validation error; the body explains which rule failed.
429	Too Many Requests — back off and retry.
500	Internal Server Error — unexpected server error.

Schemas

REST API v2 references 10 response schemas: label, okrs_checkin, okrs_initiative, okrs_key_result, okrs_objective, rest_v2_goal_collection_response, rest_v2_goal_response, rest_v2_user_collection_response, rest_v2_user_response and team.

Goal schemas for objectives, key results and initiatives share a common shape with fields for UUID, type, short ID, title, description, dates, goal type, time period, current metric (target, unit and metric type), owners, visible parent links with contribution percentages, creator, status, progress, visibility, data sources and discarded metadata.

Collection response schemas wrap records in data.records and can include data.pagy, data.checks and data.filters. Single-record response schemas wrap the record in data.record and can include data.checks and data.access_source.

Related articles

• Get access to the Rhythms REST API
• Use Rhythms from Claude, ChatGPT or Cursor
• Rhythms OKR Roles and Permissions
• How to Set Up Auto-Updates