Sports
View as MarkdownA Sport represents an activity in your workspace, such as basketball or volleyball. Start by listing sports to find the IDs used by operations that work within a specific sport.
Use the Sport object to identify an activity and display its names. The list endpoint also includes public registration details when available.
Attributes
idinteger- Unique identifier for the sport within its workspace.
namestring- Name used in the workspace.
public_namestring or null- Display name used on public pages.
slugstring or null- URL segment used to identify the sport on public pages.
is_hiddeninteger or null- Visibility flag.
nullmeans the sport is not hidden. A non-null value marks it as hidden, typically1. archived_atinteger or null- Unix timestamp in seconds when the sport was archived.
nullmeans the sport is not archived.
Creating a sport requires a signed-in user with Sports write access. Create the sport in your workspace, then use the API to look up its ID.
Create a sport in your workspace
- Open Sports and select Add sports.
- Enter the internal name, public name, and a unique slug, then save.
- Use List sports to find the new sport by name or slug.
/api/v1/sports/{id}Updates an existing sport in the workspace associated with your API key. Both PATCH and PUT accept the same JSON body.
Permissions
Send your API key in X-API-Key. Required permissions are Sports → Write.
Path parameters
idintegerRequired- The sport ID returned by List sports.
Body parameters
namestring- The name used in the workspace. Use 1 to 100 characters when supplied.
public_namestring- The name shown on public pages. Use 1 to 100 characters when supplied.
slugstring- The URL segment used on public pages. Use a unique slug of up to 50 characters with lowercase letters, digits, hyphens, or underscores.
is_hiddenboolean or null- Set to
trueto hide the sport. Set tofalseornullto clear the hidden flag when the sport is not archived. archived_atboolean or null- Send
trueto archive and hide the sport using the current server time. Sendfalseornullto clear the archive timestamp.
Omitting is_hidden or archived_at clears the corresponding field. The example keeps a visible sport visible. To keep a hidden sport hidden, send is_hidden: true and archived_at: null. Keeping a sport archived sets a new archive timestamp.
Returns
Returns 200 OK with a message_key confirming the update. Use Retrieve a sport to read the updated object.
Errors
401- The API key is missing or invalid.
403- The API key lacks Sports write access.
404- The sport was not found.
422- One or more fields failed validation.
/api/v1/sports/{id}Retrieves one sport by ID from the workspace associated with your API key.
Permissions
Send your API key in X-API-Key. Required permissions are Sports → Read.
Path parameters
idintegerRequired- The sport ID returned by List sports.
Returns
Returns the Sport object in data, with status set to success.
Errors
401- The API key is missing or invalid.
403- The API key lacks Sports read access.
404- The sport was not found.
/api/v1/sportsLists the sports in the workspace associated with your API key. You can call this endpoint before selecting a sport.
Permissions
Send your API key in X-API-Key. Required permissions are Sports → Read.
Query parameters
statusstring- Defaults to
visible, which excludes hidden and archived sports. Usehiddenfor hidden sports that are not archived,archivedfor archived sports, orallfor all three groups. qstring- Searches the name, public name, and slug.
lengthinteger- Positive page size. Omit it to return all matches.
startinteger- Zero-based offset. Defaults to
0. Use it withlength. sortstring- Sort by
id,tsc(creation time), ortsu(last update time). Prefix a field with-for descending order. orderstring- Sort direction for fields without a
-prefix. Acceptsasc(the default) ordesc. drawstring- Optional request marker echoed in the response.
Returns
data contains the sports on the requested page. List entries also include sport_public_link and form_id. When no pre-registration form is configured, form_id is null.
records_total counts sports after the status filter, before search and pagination. records_filtered counts sports after both the status filter and search, before pagination. draw echoes the request marker or returns null when omitted.
Errors
401- The API key is missing or invalid.
403- The API key lacks Sports read access.
/api/v1/sports/{id}Deletes a sport from the workspace associated with your API key. The API marks it as deleted and omits it from List and Retrieve.
Permissions
Send your API key in X-API-Key. Required permissions are Sports → Write.
Path parameters
idintegerRequired- The sport ID returned by List sports.
Use Update a sport if you want to archive it and keep it available in the archived list.
Returns
Returns 200 OK with a message_key confirming deletion. A repeat request for the same ID returns 404.
Errors
401- The API key is missing or invalid.
403- The API key lacks Sports write access.
404- The sport was not found.
400- The backend could not complete the deletion.
/api/v1/sports/slug-availableChecks whether a public URL slug is available in the workspace associated with your API key.
Permissions
Send your API key in X-API-Key. Required permissions are Sports → Write.
Query parameters
slugstringRequired- The proposed slug. The API lowercases it, replaces spaces with hyphens, and removes characters outside letters, digits, hyphens, and underscores.
exclude_idinteger- The ID of the sport being edited. The availability check ignores that sport.
Returns
Returns available: true if no matching sport uses the slug, or available: false if it is taken. If normalization leaves an empty slug, the response includes available: false and reason: invalid_format.
The check does not reserve the slug. The update still validates it.
Errors
401- The API key is missing or invalid.
403- The API key lacks Sports write access.
400- The slug was missing, empty, or not a string.