Skip to main content

API Reference

This document is a reference for the Crux API. It contains information about the different APIs, the resources they return, and the response objects. Refer to the intro for more information about the API or the authentication page for information about how to authenticate your API requests.

API Endpoints​

GET /api/v1/gyms/:gym_slug/climb_lists​

Returns all public climb lists for a specific gym.

Parameters:​

gym_slug​

The URL slug of the gym whose lists you want to retrieve. This parameter is required.

Authorization:​

Public.

Response:​

ClimbList

GET /api/v1/users/:user_id/climb_lists​

Returns all climb lists created by a user.

Parameters:​

user_id​

Must be "me" or your own user ID, since you can only view your own lists. This parameter is required.

Authorization:​

You can only view your own lists.

Response:​

ClimbList

GET /api/v1/climb_lists/:id​

Returns details for a specific climb list. Must be public or owned by the user.

Parameters:​

id​

The ID of the climb list to retrieve. This parameter is required.

Authorization:​

Public if the list is public. Otherwise, restricted to the user who owns the list.

Response:​

ClimbList (full)

POST /api/v1/climb_lists/:list_id/add_climb​

Adds a climb to a climb list. Returns HTTP 200 if successful.

Parameters:​

list_id​

The ID of the list to add the climb to. This parameter is required.

climb_id​

The ID of the climb to add. This parameter is required.

Authorization:​

User must own the list or be a gym admin of a gym-owned list.

Response:​

Empty

POST /api/v1/climb_lists/:list_id/remove_climb​

Removes a climb from a list. Returns HTTP 200 if successful.

Parameters:​

list_id​

The ID of the list. This parameter is required.

climb_id​

The ID of the climb to remove. This parameter is required.

Authorization:​

User must own the list or be a gym admin of a gym-owned list.

Response:​

Empty

GET /api/v1/climbs/:id​

Returns details for a specific climb.

Parameters:​

id​

The ID of the climb to retrieve. This parameter is required.

Authorization:​

Public.

Response:​

Climb (full)

GET /api/v1/gyms/:gym_slug/climbs/custom​

Returns a list of custom climbs for the specified gym.

Parameters:​

gym_slug​

The URL slug of the gym whose custom climbs you want to retrieve. This parameter is required.

page​

The page number to retrieve (defaults to 1). This parameter is optional.

Authorization:​

Public.

Response:​

Climb

GET /api/v1/gyms/:gym_slug/climbs/official​

Returns a list of official climbs for the specified gym.

Parameters:​

gym_slug​

The URL slug of the gym whose official climbs you want to retrieve. This parameter is required.

page​

The page number to retrieve (defaults to 1). This parameter is optional.

Authorization:​

Public.

Response:​

Climb

GET /api/v1/gym_walls/:id​

Returns details for a specific gym wall.

Parameters:​

id​

The ID of the gym wall to retrieve. This parameter is required.

Authorization:​

Public.

Response:​

GymWall

GET /api/v1/gym_walls/:id/active_climb​

Returns the active climb for the specified gym wall.

Parameters:​

id​

The ID of the gym wall to retrieve. This parameter is required.

Authorization:​

Public.

Response:​

Climb (full)

GET /api/v1/gyms/:gym_slug/gym_walls​

Returns a list of all gym walls for the specified gym.

Parameters:​

gym_slug​

The URL slug of the gym whose walls you want to retrieve. This parameter is required.

Authorization:​

Public.

Response:​

GymWall

GET /api/v1/gyms/:gym_slug​

Returns details for a specific gym.

Parameters:​

gym_slug​

URL slug for the gym. This parameter is required.

Authorization:​

Public.

Response:​

Gym

GET /api/v1/gyms/:gym_slug/webhook_registrations​

List all webhook registrations for a gym.

Parameters:​

gym_slug​

URL slug for the gym. This parameter is required.

Authorization:​

Restricted to gym admins.

Response:​

WebhookRegistration (full)

GET /api/v1/gyms/:gym_slug/active_climb​

Returns the active climb for any wall on the specified gym.

Parameters:​

gym_slug​

URL slug for the gym. This parameter is required.

Authorization:​

Public.

Response:​

Climb (full)

GET /api/v1/users/:user_id​

Returns details for a specific user.

Parameters:​

user_id​

The ID of the user to retrieve. Use "me" to retrieve your own user details. This parameter is required.

Authorization:​

Public.

Response:​

One of: [User, User (authenticated)]

GET /api/v1/users/:user_id/climb_sessions​

Returns a list of climb sessions for the current user.

Parameters:​

user_id​

Must be "me" or your own user ID, since you can only view your own climb sessions. This parameter is required.

Authorization:​

You can only view your own climb sessions.

Response:​

ClimbSession

GET /api/v1/users/:user_id/webhook_registrations​

Returns all webhook registrations for the current user.

Parameters:​

user_id​

Must be "me" or your own user ID, since you can only view your own webhook registrations. This parameter is required.

Authorization:​

You can only view your own webhook registrations.

Response:​

WebhookRegistration (full)

Response Objects​

These are the definitions of the objects returned by the API. Some objects have variants, for example, User has an "authenticated" variant with additional information that we return when you're fetching your own user. The API documentation above indicates when a variant is returned.

Climb​

id integer​

An ID that uniquely identifies the resource across Crux.

angle nullable string​

The angle this climb was set at. Only for climbs on adjustable walls.

color nullable string​

The color of the climb. Only for official climbs in commercial gyms.

created_at string​

When the climb was created.

description nullable string​

Optional climber-provided description of the climb.

foot_rules nullable string​

Foot rules for the climb. One of [feet_follow_hands, any_feet, campus, feet_follow_hands_open_kicker, only_marked_feet]

grade nullable string​

The grade of the climb. This will be one of the gym's available grades.

image_height nullable integer​

Height of the cropped image in pixels. Hold masks are relative to this height.

image_url nullable string​

The final (edited) image URL for the climb.

image_width nullable integer​

Width of the cropped image in pixels. Hold masks are relative to this width.

name string​

The name of the climb.

number_of_comments integer​

The number of comments on this climb.

number_of_sends integer​

The number of times this climb has been sent.

unedited_image_url nullable string​

The original uploaded image URL, before hold highlights.

unset_at nullable string​

When the climb was marked as unset (removed from the wall).

updated_at string​

When the climb was last updated.

Climb (full)​

id integer​

An ID that uniquely identifies the resource across Crux.

angle nullable string​

The angle this climb was set at. Only for climbs on adjustable walls.

color nullable string​

The color of the climb. Only for official climbs in commercial gyms.

created_at string​

When the climb was created.

description nullable string​

Optional climber-provided description of the climb.

foot_rules nullable string​

Foot rules for the climb. One of [feet_follow_hands, any_feet, campus, feet_follow_hands_open_kicker, only_marked_feet]

grade nullable string​

The grade of the climb. This will be one of the gym's available grades.

gym_name string​

The name of the gym where the climb is located.

gym_slug string​

The URL slug of the gym where the climb is located.

holds ClimbHold (on_climb)​

List of holds in the climb.

image_height nullable integer​

Height of the cropped image in pixels. Hold masks are relative to this height.

image_url nullable string​

The final (edited) image URL for the climb.

image_width nullable integer​

Width of the cropped image in pixels. Hold masks are relative to this width.

name string​

The name of the climb.

number_of_comments integer​

The number of comments on this climb.

number_of_sends integer​

The number of times this climb has been sent.

setter_id nullable integer​

User ID of the setter (custom climbs only).

setter_name nullable string​

Name of the setter who posted the climb (custom climbs only).

unedited_image_url nullable string​

The original uploaded image URL, before hold highlights.

unset_at nullable string​

When the climb was marked as unset (removed from the wall).

updated_at string​

When the climb was last updated.

sends array Send​

List of sends for this climb.

ClimbHold​

id integer​

An ID that uniquely identifies the resource across Crux.

mask array​

The mask of the hold. The mask is a list of points that form a polygon. The points are relative to the width and height of the image provided by the API.

ClimbHold (on_climb)​

hold_type string​

The type of hold. One of [hand, hand_l, hand_r, foot, foot_l, foot_r, start, finish, zone]

id integer​

An ID that uniquely identifies the resource across Crux.

mask array​

The mask of the hold. The mask is a list of points that form a polygon. The points are relative to the width and height of the image provided by the API.

ClimbList​

id integer​

An ID that uniquely identifies the resource across Crux.

climb_count integer​

The number of climbs in the list.

created_at string​

Timestamp when the list was created.

icon string​

Icon for this list. A single emoji.

name string​

The name of the climb list.

owned_by_gym boolean​

Whether this list is owned by the gym. Gym-owned lists can be edited by all gym staff.

pinned_at nullable string​

Timestamp when the list was pinned (if applicable).

gym nullable Gym​

The gym that owns this list, if the list is gym-owned.

owner nullable User​

The user who owns the list, if the list is not gym-owned.

ClimbList (full)​

id integer​

An ID that uniquely identifies the resource across Crux.

climb_count integer​

The number of climbs in the list.

created_at string​

Timestamp when the list was created.

icon string​

Icon for this list. A single emoji.

name string​

The name of the climb list.

owned_by_gym boolean​

Whether this list is owned by the gym. Gym-owned lists can be edited by all gym staff.

pinned_at nullable string​

Timestamp when the list was pinned (if applicable).

climbs array Climb​

All climbs in this list.

gym nullable Gym​

The gym that owns this list, if the list is gym-owned.

owner nullable User​

The user who owns the list, if the list is not gym-owned.

ClimbSession​

id integer​

An ID that uniquely identifies the resource across Crux.

created_at string​

Timestamp when the session was created.

date string​

The date of the climb session (YYYY-MM-DD). This can be different from the created_at timestamp if you are creating a session for a past date.

sends array Send (full)​

List of sends during the session.

Empty​

Gym​

id integer​

An ID that uniquely identifies the resource across Crux.

The banner URL of the gym.

description nullable string​

The description of the gym. This appears below the gym's name on the gym page and only applies to commercial gyms.

icon_url nullable string​

The icon URL of the gym.

location nullable string​

The location of the gym.

name string​

The name of the gym.

number_of_climbers integer​

The number of distinct users who have used Crux at this gym.

number_of_sends integer​

The cumulative number of sends at this gym across all climbs, including unset climbs.

url_slug string​

The URL slug of the gym.

GymWall​

id integer​

An ID that uniquely identifies the resource across Crux.

angle_adjustable boolean​

Whether the wall has an adjustable angle.

created_at string​

Timestamp when the wall was created.

holds nullable ClimbHold​

List of predicted holds on the wall.

image_height nullable integer​

The height of the wall image in pixels.

image_url nullable string​

The URL of the wall's image.

image_width nullable integer​

The width of the wall image in pixels.

maximum_angle nullable integer​

Maximum wall angle in degrees.

minimum_angle nullable integer​

Minimum wall angle in degrees.

name string​

The name of the wall.

updated_at string​

Timestamp when the wall was last updated.

Send​

id integer​

An ID that uniquely identifies the resource across Crux.

created_at string​

Timestamp when the send was recorded.

repeat boolean​

Whether this was a repeat send of the climb.

send_date string​

The date of the session in which this send occurred.

user User​

The user who sent the climb.

Send (full)​

id integer​

An ID that uniquely identifies the resource across Crux.

created_at string​

Timestamp when the send was recorded.

repeat boolean​

Whether this was a repeat send of the climb.

send_date string​

The date of the session in which this send occurred.

climb Climb​

The climb that was sent.

user User​

The user who sent the climb.

User (authenticated)​

id integer​

An ID that uniquely identifies the resource across Crux.

created_at string​

Timestamp when the user account was created.

name string​

The display name of the user, or 'Unknown' if the user has not set a name.

profile_image_url nullable string​

URL for the user's profile image.

administrated_gyms array Gym​

List of gyms where the user is an admin.

viewed_gyms array Gym​

List of gyms the user has viewed.

User​

id integer​

An ID that uniquely identifies the resource across Crux.

created_at string​

Timestamp when the user account was created.

name string​

The display name of the user, or 'Unknown' if the user has not set a name.

profile_image_url nullable string​

URL for the user's profile image.

WebhookDelivery​

id integer​

An ID that uniquely identifies the resource across Crux.

created_at string​

Timestamp when the webhook delivery was scheduled.

delivered_at nullable string​

Timestamp when the webhook delivery was delivered.

error nullable string​

Error message if the delivery failed.

payload object​

Parsed JSON payload that was delivered.

status string​

Status of the webhook delivery. One of [success, failure, pending, retrying]

webhook_registration WebhookRegistration​

The webhook registration associated with this delivery.

WebhookRegistration​

id integer​

An ID that uniquely identifies the resource across Crux.

event_type string​

The type of event that triggers the webhook.

gym_url_slug nullable string​

The slug of the gym that owns this webhook (only present if owner is a Gym).

owner_id integer​

ID of the resource that owns this webhook registratiom.

owner_type string​

Type of the owner resource. One of [Gym, User]

url string​

The endpoint URL where webhooks will be delivered.

WebhookRegistration (full)​

id integer​

An ID that uniquely identifies the resource across Crux.

event_type string​

The type of event that triggers the webhook.

gym_url_slug nullable string​

The slug of the gym that owns this webhook (only present if owner is a Gym).

owner_id integer​

ID of the resource that owns this webhook registratiom.

owner_type string​

Type of the owner resource. One of [Gym, User]

url string​

The endpoint URL where webhooks will be delivered.

recent_deliveries array WebhookDelivery​

The 10 most recent webhook deliveries for this registration.