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/custom_climbs

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.

Authorization:

Public.

Response:

Climb

GET /api/v1/gyms/:gym_slug/official_climbs

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.

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/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/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.

banner_url nullable string

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.

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.