Team API Documentation

Authentication

Use HTTP Basic Authentication with your API key as the username. Leave the password empty.

cURL

curl -u "YOUR_API_KEY:" https://racemob.com/api/v1/teams/{team_id}/meetups

Important

The colon after the key is required (it separates username from empty password)
Your API key only works for your specific team
Generate keys in your team's Admin Portal under API Keys

Key Format

Your API key follows this pattern:

rm_team_{team_id}_{random_characters}

Rate Limits

Limit Type	Value
Failed auth attempts	5 per minute per IP
Bulk operations	50 items per request

Contact support for higher limits if needed.

Response Format

Success Response

JSON

{
  "success": true,
  "data": { ... },
  "message": "Optional success message"
}

Error Response

JSON

{
  "success": false,
  "error": "Error type",
  "message": "Human-readable message",
  "hint": "How to fix the issue",
  "validationErrors": [
    { "field": "fieldName", "error": "what went wrong", "hint": "how to fix" }
  ]
}

HTTP Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad Request - invalid JSON or parameters
`401`	Unauthorized - invalid or missing API key
`403`	Forbidden - valid key but wrong team
`404`	Not Found
`422`	Unprocessable Entity - validation errors
`429`	Rate Limited

Team Settings

GET /api/v1/teams/{team_id}

Get team details and settings.

PATCH /api/v1/teams/{team_id}

Update team settings.

Editable Fields

name description location websiteUrl facebookUrl stravaClubUrl instagramHandle publicEmail primarySport joinMethod privacy teamRules screeningQuestion screeningQuestionRequired liabilityWaiverUrl

Example

curl -X PATCH "https://racemob.com/api/v1/teams/{team_id}" \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "team": { "description": "Updated description" } }'

Members

GET /api/v1/teams/{team_id}/members

List all team members with their roles.

PATCH /api/v1/teams/{team_id}/members/:user_id

Update a member's role.

{ "role": "leader" }

Valid roles: captain, leader, member

DELETE /api/v1/teams/{team_id}/members/:user_id

Remove a member from the team.

Cannot remove the team owner.

Join Requests

GET /api/v1/teams/{team_id}/join_requests

List pending join requests.

POST /api/v1/teams/{team_id}/join_requests/:id/approve

Approve a join request.

POST /api/v1/teams/{team_id}/join_requests/:id/reject

Reject a join request with optional reason.

{ "reason": "..." }

Meetups

GET /api/v1/teams/{team_id}/meetups

List all meetups.

Query Parameters

upcoming past activity_type include_drafts include_cancelled page per_page

GET /api/v1/teams/{team_id}/meetups/:id

Get a single meetup with RSVPs.

POST /api/v1/teams/{team_id}/meetups

Create a single meetup. See Meetup Schema.

PATCH /api/v1/teams/{team_id}/meetups/:id

Update a meetup.

DELETE /api/v1/teams/{team_id}/meetups/:id

Delete a meetup.

POST /api/v1/teams/{team_id}/meetups/:id/cancel

Cancel a published meetup.

POST /api/v1/teams/{team_id}/meetups/:id/publish

Publish a draft meetup.

POST /api/v1/teams/{team_id}/meetups/bulk

Create multiple meetups at once. See Bulk Create Schema.

Example

curl -X POST "https://racemob.com/api/v1/teams/{team_id}/meetups/bulk" \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "meetups": [{
      "title": "Tuesday Track Workout",
      "meetupType": "recurring",
      "dayOfWeek": "tuesday",
      "time": "18:00",
      "location": "Community Track",
      "activityType": "speed_workout"
    }]
  }'

Meetup Series

GET /api/v1/teams/{team_id}/meetup_series

List all meetup series.

Query Parameters

include_drafts

GET /api/v1/teams/{team_id}/meetup_series/:id

Get a series with upcoming instances.

POST /api/v1/teams/{team_id}/meetup_series

Create a new series. See Meetup Series Schema.

PATCH /api/v1/teams/{team_id}/meetup_series/:id

Update series settings.

DELETE /api/v1/teams/{team_id}/meetup_series/:id

Delete series and all instances.

POST /api/v1/teams/{team_id}/meetup_series/:id/generate

Generate additional instances.

Parameters

count (1-52)

Discussions

GET /api/v1/teams/{team_id}/discussions

List all discussions.

Query Parameters

category pinned page per_page

GET /api/v1/teams/{team_id}/discussions/:id

Get a discussion with all replies.

POST /api/v1/teams/{team_id}/discussions

Create a new discussion. See Discussion Schema.

PATCH /api/v1/teams/{team_id}/discussions/:id

Update a discussion (author/leaders only).

DELETE /api/v1/teams/{team_id}/discussions/:id

Delete a discussion (author/leaders only).

POST /api/v1/teams/{team_id}/discussions/:id/pin

Pin a discussion (leaders only).

POST /api/v1/teams/{team_id}/discussions/:id/unpin

Unpin a discussion (leaders only).

POST /api/v1/teams/{team_id}/discussions/:id/lock

Lock a discussion (leaders only).

POST /api/v1/teams/{team_id}/discussions/:id/unlock

Unlock a discussion (leaders only).

Discussion Replies

POST /api/v1/teams/{team_id}/discussions/:discussion_id/replies

Create a reply. Replies can be nested up to 3 levels using parent_id.

DELETE /api/v1/teams/{team_id}/discussions/:discussion_id/replies/:id

Delete a reply (author/leaders only).

Announcements

GET /api/v1/teams/{team_id}/announcements

List all announcements.

Query Parameters

page per_page

GET /api/v1/teams/{team_id}/announcements/:id

Get an announcement with comments.

POST /api/v1/teams/{team_id}/announcements

Create an announcement (leaders only). See Announcement Schema.

PATCH /api/v1/teams/{team_id}/announcements/:id

Update an announcement (author/leaders only).

DELETE /api/v1/teams/{team_id}/announcements/:id

Delete an announcement (author/leaders only).

POST /api/v1/teams/{team_id}/announcements/:id/send

Send announcement to all members via email. Can only be sent once.

Announcement Comments

POST /api/v1/teams/{team_id}/announcements/:announcement_id/comments

Create a comment. Comments can be nested up to 3 levels using parent_id.

DELETE /api/v1/teams/{team_id}/announcements/:announcement_id/comments/:id

Delete a comment (author/leaders only).

Races

Manage team-race associations. Link your team to races you're participating in.

GET /api/v1/teams/{team_id}/races

List all races associated with the team.

Query Parameters

upcoming past page per_page

GET /api/v1/teams/{team_id}/races/:race_id

Get details of a specific race association.

POST /api/v1/teams/{team_id}/races

Add a race to the team. Provide race_id directly, or search by race_name + race_date.

Example

curl -X POST "https://racemob.com/api/v1/teams/{team_id}/races" \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "race_id": 456, "is_host_team": false }'

PATCH /api/v1/teams/{team_id}/races/:race_id

Update host team status.

{ "is_host_team": true }

DELETE /api/v1/teams/{team_id}/races/:race_id

Remove a race from the team.

Enums Reference

Activity Types

social_run long_run speed_workout hill_workout trail_run swim_workout bike_workout cross_training custom

Meetup Types

one_time (requires date) recurring (requires dayOfWeek)

Days of Week

sunday monday tuesday wednesday thursday friday saturday

Route Types

park neighborhood track trail custom

Recurrence Patterns

weekly biweekly monthly

Meetup Privacy

public_visibility members_only invite_only

Member Roles

captain (full admin) leader (manage content) member (basic access)

Discussion Categories

training logistics course gear race_day

Join Methods

open request invite_only

Privacy Settings

public private

JSON Schemas

Copy these schemas into your AI assistant (like Claude) for accurate API calls.

Bulk Create Meetups

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Bulk Create Meetups",
  "description": "Create one or more meetups for your team. Supports both one-time events and recurring weekly meetups.",
  "type": "object",
  "required": [
    "meetups"
  ],
  "properties": {
    "meetups": {
      "type": "array",
      "minItems": 1,
      "maxItems": 50,
      "description": "Array of meetups to create (max 50 per request)",
      "items": {
        "$ref": "#/$defs/meetup"
      }
    }
  },
  "$defs": {
    "meetup": {
      "type": "object",
      "required": [
        "title",
        "time"
      ],
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 150,
          "description": "Name of the meetup (e.g., 'Tuesday Track Workout')"
        },
        "meetupType": {
          "type": "string",
          "enum": [
            "one_time",
            "recurring"
          ],
          "default": "recurring",
          "description": "one_time requires 'date', recurring requires 'dayOfWeek'"
        },
        "date": {
          "type": "string",
          "format": "date",
          "description": "Required for one_time meetups. Format: YYYY-MM-DD"
        },
        "dayOfWeek": {
          "type": "string",
          "enum": [
            "sunday",
            "monday",
            "tuesday",
            "wednesday",
            "thursday",
            "friday",
            "saturday"
          ],
          "description": "Required for recurring meetups"
        },
        "time": {
          "type": "string",
          "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$",
          "description": "24-hour format, e.g., '18:00' for 6 PM"
        },
        "location": {
          "type": "string",
          "maxLength": 200,
          "description": "Meeting location name (e.g., 'Central Park Boathouse')"
        },
        "address": {
          "type": "string",
          "maxLength": 500,
          "description": "Full street address for mapping"
        },
        "description": {
          "type": "string",
          "maxLength": 10000,
          "description": "Details about the meetup (pace, distance, notes)"
        },
        "activityType": {
          "type": "string",
          "enum": [
            "social_run",
            "long_run",
            "speed_workout",
            "hill_workout",
            "trail_run",
            "swim_workout",
            "bike_workout",
            "cross_training",
            "custom"
          ],
          "default": "social_run",
          "description": "Type of activity for categorization"
        }
      }
    }
  }
}

Update Team Settings

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Update Team Settings",
  "description": "Update team profile and configuration settings.",
  "type": "object",
  "properties": {
    "team": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "description": {
          "type": "string",
          "maxLength": 5000
        },
        "location": {
          "type": "string",
          "maxLength": 200
        },
        "website_url": {
          "type": "string",
          "format": "uri"
        },
        "facebook_url": {
          "type": "string",
          "format": "uri"
        },
        "strava_club_url": {
          "type": "string",
          "format": "uri"
        },
        "instagram_handle": {
          "type": "string",
          "maxLength": 30
        },
        "public_email": {
          "type": "string",
          "format": "email"
        },
        "primary_sport": {
          "type": "string",
          "enum": [
            "running",
            "trail_running",
            "triathlon",
            "cycling",
            "track_field",
            "swimming",
            "multi_sport",
            "other"
          ]
        },
        "join_method": {
          "type": "string",
          "enum": [
            "open",
            "approval_required",
            "invite_only"
          ]
        },
        "privacy": {
          "type": "string",
          "enum": [
            "public_visibility",
            "private_visibility"
          ]
        },
        "team_rules": {
          "type": "string",
          "maxLength": 10000
        },
        "screening_question": {
          "type": "string",
          "maxLength": 500
        },
        "screening_question_required": {
          "type": "boolean"
        },
        "liability_waiver_url": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}

Update Member Role

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Update Member Role",
  "description": "Change a team member's role.",
  "type": "object",
  "required": [
    "role"
  ],
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "captain",
        "leader",
        "member"
      ],
      "description": "captain: full admin access, leader: can manage content, member: basic access"
    }
  }
}

Create/Update Meetup

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Create/Update Meetup",
  "description": "Create or update a single meetup for your team.",
  "type": "object",
  "required": [
    "meetup"
  ],
  "properties": {
    "meetup": {
      "type": "object",
      "required": [
        "name",
        "start_date"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 150,
          "description": "Name of the meetup"
        },
        "description": {
          "type": "string",
          "maxLength": 10000,
          "description": "Details about the meetup"
        },
        "start_date": {
          "type": "string",
          "format": "date",
          "description": "Date in YYYY-MM-DD format"
        },
        "start_time": {
          "type": "string",
          "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$",
          "description": "Time in HH:MM format"
        },
        "location": {
          "type": "string",
          "description": "Meeting location name"
        },
        "address": {
          "type": "string",
          "description": "Full street address"
        },
        "activity_type": {
          "type": "string",
          "enum": [
            "social_run",
            "long_run",
            "speed_workout",
            "hill_workout",
            "trail_run",
            "swim_workout",
            "bike_workout",
            "cross_training",
            "custom"
          ],
          "default": "social_run"
        },
        "route_type": {
          "type": "string",
          "enum": [
            "park",
            "neighborhood",
            "track",
            "trail",
            "custom"
          ],
          "default": "neighborhood"
        },
        "distance": {
          "type": "number",
          "minimum": 0,
          "description": "Distance in miles"
        },
        "pace_range": {
          "type": "string",
          "description": "e.g., '9:00-10:00'"
        },
        "route_description": {
          "type": "string",
          "description": "Route details"
        },
        "privacy": {
          "type": "string",
          "enum": [
            "public_visibility",
            "members_only",
            "invite_only"
          ],
          "default": "public_visibility"
        },
        "rsvp_required": {
          "type": "string",
          "enum": [
            "optional",
            "required",
            "none"
          ],
          "default": "optional"
        },
        "max_participants": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000
        },
        "draft": {
          "type": "boolean",
          "default": false,
          "description": "Save as draft (not visible to members)"
        }
      }
    }
  }
}

Create/Update Meetup Series

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Create/Update Meetup Series",
  "description": "Create or update a recurring meetup series.",
  "type": "object",
  "required": [
    "meetup_series"
  ],
  "properties": {
    "meetup_series": {
      "type": "object",
      "required": [
        "name",
        "start_date",
        "recurrence_pattern"
      ],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 150
        },
        "description": {
          "type": "string"
        },
        "start_date": {
          "type": "string",
          "format": "date"
        },
        "start_time": {
          "type": "string",
          "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$"
        },
        "recurrence_pattern": {
          "type": "string",
          "enum": [
            "weekly",
            "biweekly",
            "monthly"
          ],
          "description": "How often the meetup repeats"
        },
        "recurrence_end_date": {
          "type": "string",
          "format": "date",
          "description": "When series ends (optional)"
        },
        "recurrence_end_occurrences": {
          "type": "integer",
          "minimum": 1,
          "description": "End after N occurrences (optional)"
        },
        "location": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "activity_type": {
          "type": "string",
          "enum": [
            "social_run",
            "long_run",
            "speed_workout",
            "hill_workout",
            "trail_run",
            "swim_workout",
            "bike_workout",
            "cross_training",
            "custom"
          ]
        },
        "route_type": {
          "type": "string",
          "enum": [
            "park",
            "neighborhood",
            "track",
            "trail",
            "custom"
          ]
        },
        "distance": {
          "type": "number",
          "minimum": 0
        },
        "pace_range": {
          "type": "string"
        },
        "max_participants": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000
        },
        "privacy": {
          "type": "string",
          "enum": [
            "public_visibility",
            "members_only",
            "invite_only"
          ]
        },
        "draft": {
          "type": "boolean"
        }
      }
    },
    "generate_count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 52,
      "default": 12,
      "description": "Number of meetup instances to generate (for create)"
    }
  }
}

Create/Update Discussion

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Create/Update Discussion",
  "description": "Create or update a team discussion topic.",
  "type": "object",
  "required": [
    "discussion"
  ],
  "properties": {
    "discussion": {
      "type": "object",
      "required": [
        "title",
        "content"
      ],
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Discussion title"
        },
        "content": {
          "type": "string",
          "minLength": 1,
          "description": "Discussion body content"
        },
        "category": {
          "type": "string",
          "enum": [
            "training",
            "logistics",
            "course",
            "gear",
            "race_day"
          ],
          "description": "Category for organization"
        }
      }
    }
  }
}

Create Discussion Reply

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Create Discussion Reply",
  "description": "Create a reply to a discussion topic.",
  "type": "object",
  "required": [
    "reply"
  ],
  "properties": {
    "reply": {
      "type": "object",
      "required": [
        "content"
      ],
      "properties": {
        "content": {
          "type": "string",
          "minLength": 1,
          "description": "Reply content"
        },
        "parent_id": {
          "type": "integer",
          "description": "ID of parent reply for nested replies (max 3 levels deep)"
        }
      }
    }
  }
}

Create/Update Announcement

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Create/Update Announcement",
  "description": "Create or update a team announcement.",
  "type": "object",
  "required": [
    "announcement"
  ],
  "properties": {
    "announcement": {
      "type": "object",
      "required": [
        "subject",
        "body"
      ],
      "properties": {
        "subject": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Announcement subject line"
        },
        "body": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50000,
          "description": "Full announcement content"
        },
        "pinned": {
          "type": "boolean",
          "default": false,
          "description": "Pin to top of announcements list"
        }
      }
    }
  }
}

Create Announcement Comment

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Create Announcement Comment",
  "description": "Create a comment on an announcement.",
  "type": "object",
  "required": [
    "comment"
  ],
  "properties": {
    "comment": {
      "type": "object",
      "required": [
        "content"
      ],
      "properties": {
        "content": {
          "type": "string",
          "minLength": 1,
          "maxLength": 10000,
          "description": "Comment content"
        },
        "parent_id": {
          "type": "integer",
          "description": "ID of parent comment for nested replies (max 3 levels deep, depth 0-2)"
        }
      }
    }
  }
}

Add Race to Team

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Add Race to Team",
  "description": "Associate a race with your team.",
  "type": "object",
  "oneOf": [
    {
      "required": [
        "race_id"
      ],
      "properties": {
        "race_id": {
          "type": "integer",
          "description": "The ID of the race to add"
        },
        "is_host_team": {
          "type": "boolean",
          "default": false,
          "description": "Whether this team is the host team for the race"
        }
      }
    },
    {
      "required": [
        "race_name",
        "race_date"
      ],
      "properties": {
        "race_name": {
          "type": "string",
          "description": "Partial name to search for (case-insensitive)"
        },
        "race_date": {
          "type": "string",
          "format": "date",
          "description": "Exact date of the race (YYYY-MM-DD)"
        },
        "is_host_team": {
          "type": "boolean",
          "default": false
        }
      }
    }
  ]
}

Examples

Create a Weekly Recurring Meetup

cURL

curl -X POST "https://racemob.com/api/v1/teams/{team_id}/meetups/bulk" \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "meetups": [{
      "title": "Saturday Long Run",
      "meetupType": "recurring",
      "dayOfWeek": "saturday",
      "time": "07:00",
      "location": "Golden Gate Park",
      "address": "501 Stanyan St, San Francisco, CA",
      "description": "10-15 mile long run. Multiple pace groups.",
      "activityType": "long_run"
    }]
  }'

Create a One-Time Event

cURL

curl -X POST "https://racemob.com/api/v1/teams/{team_id}/meetups/bulk" \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "meetups": [{
      "title": "Pre-Race Shakeout Run",
      "meetupType": "one_time",
      "date": "2026-03-15",
      "time": "08:00",
      "location": "Race Start Area",
      "activityType": "social_run"
    }]
  }'

Create Multiple Meetups at Once

cURL

curl -X POST "https://racemob.com/api/v1/teams/{team_id}/meetups/bulk" \
  -u "YOUR_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "meetups": [
      { "title": "Tuesday Track", "meetupType": "recurring", "dayOfWeek": "tuesday", "time": "18:00", "activityType": "speed_workout" },
      { "title": "Thursday Easy", "meetupType": "recurring", "dayOfWeek": "thursday", "time": "18:30", "activityType": "social_run" },
      { "title": "Saturday Long", "meetupType": "recurring", "dayOfWeek": "saturday", "time": "07:00", "activityType": "long_run" }
    ]
  }'

Using with AI Assistants

This API is designed for use with AI coding assistants like Claude. Tips:

Copy the JSON Schema into your AI conversation for accurate requests
Provide your API key and team ID to the assistant
Describe the meetups you want in natural language
The assistant can generate valid API calls based on the schema

Example Prompt

"I have a running club (team ID {team_id}). Create API calls to set up our weekly schedule: Tuesday at 6pm: Track workout at the local high school, Thursday at 6:30pm: Easy recovery run from the coffee shop, Saturday at 7am: Long run from the park"