> For the complete documentation index, see [llms.txt](https://movemint.gitbook.io/movemint-developer-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://movemint.gitbook.io/movemint-developer-docs/open-api-specification/core-resources/groups.md).
# Groups
Groups you administer — collections of events run together, such as a race series or a club's calendar — and the events linked to them.
## List the groups you administer
> Returns the groups the authenticated user administers, ordered by\
> name. Use the returned \`handle\` to address a group on other endpoints. For a\
> Movemint AI token, only groups whose role grants the assistant are\
> listed.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Groups","description":"Groups you administer — collections of events run together, such as a\nrace series or a club's calendar — and the events linked to them.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"schemas":{"GroupSummary":{"type":"object","required":["id","handle","name"],"properties":{"id":{"type":"integer"},"handle":{"type":"string","description":"Used to address the group on other endpoints"},"name":{"type":"string"}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}},"paths":{"/api/v1/groups":{"get":{"tags":["Groups"],"summary":"List the groups you administer","description":"Returns the groups the authenticated user administers, ordered by\nname. Use the returned `handle` to address a group on other endpoints. For a\nMovemint AI token, only groups whose role grants the assistant are\nlisted.\n","operationId":"listGroups","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum number of groups to return (default 50, maximum 200).","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Groups the authenticated user administers","content":{"application/json":{"schema":{"type":"object","required":["groups"],"properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/GroupSummary"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
````
## Get a group
> Returns the group's name, contact email, and external links.\
> Requires the \`groups\` permission on the group, which every group\
> admin role grants.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Groups","description":"Groups you administer — collections of events run together, such as a\nrace series or a club's calendar — and the events linked to them.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"parameters":{"GroupHandle":{"name":"group_handle","in":"path","required":true,"description":"The unique handle (slug) of the group","schema":{"type":"string"}}},"schemas":{"Group":{"allOf":[{"$ref":"#/components/schemas/GroupSummary"},{"$ref":"#/components/schemas/GroupWritableFields"},{"type":"object","required":["email","website","instagram_url","facebook_url","x_url","strava_club_url"]}]},"GroupSummary":{"type":"object","required":["id","handle","name"],"properties":{"id":{"type":"integer"},"handle":{"type":"string","description":"Used to address the group on other endpoints"},"name":{"type":"string"}}},"GroupWritableFields":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","nullable":true,"description":"Public contact email for the group"},"website":{"type":"string","nullable":true},"instagram_url":{"type":"string","nullable":true},"facebook_url":{"type":"string","nullable":true},"x_url":{"type":"string","nullable":true},"strava_club_url":{"type":"string","nullable":true}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"Forbidden":{"description":"Forbidden - user is not an admin of this event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"GroupNotFound":{"description":"Group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/groups/{group_handle}":{"get":{"tags":["Groups"],"summary":"Get a group","description":"Returns the group's name, contact email, and external links.\nRequires the `groups` permission on the group, which every group\nadmin role grants.\n","operationId":"getGroup","parameters":[{"$ref":"#/components/parameters/GroupHandle"}],"responses":{"200":{"description":"The group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/GroupNotFound"}}}}}}
````
## Update a group
> Updates the group's name, contact email, or external links. Only the\
> fields sent are changed; send an empty string to clear a link. The\
> name cannot be set blank. The group's handle is not editable.\
> Requires the \`groups\` permission on the group.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Groups","description":"Groups you administer — collections of events run together, such as a\nrace series or a club's calendar — and the events linked to them.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"parameters":{"GroupHandle":{"name":"group_handle","in":"path","required":true,"description":"The unique handle (slug) of the group","schema":{"type":"string"}}},"schemas":{"UpdateGroupRequest":{"type":"object","required":["group"],"properties":{"group":{"$ref":"#/components/schemas/GroupWritableFields"}}},"GroupWritableFields":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","nullable":true,"description":"Public contact email for the group"},"website":{"type":"string","nullable":true},"instagram_url":{"type":"string","nullable":true},"facebook_url":{"type":"string","nullable":true},"x_url":{"type":"string","nullable":true},"strava_club_url":{"type":"string","nullable":true}}},"Group":{"allOf":[{"$ref":"#/components/schemas/GroupSummary"},{"$ref":"#/components/schemas/GroupWritableFields"},{"type":"object","required":["email","website","instagram_url","facebook_url","x_url","strava_club_url"]}]},"GroupSummary":{"type":"object","required":["id","handle","name"],"properties":{"id":{"type":"integer"},"handle":{"type":"string","description":"Used to address the group on other endpoints"},"name":{"type":"string"}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}},"ValidationError":{"type":"object","description":"A validation error response with a list of error messages","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of validation error messages"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"Forbidden":{"description":"Forbidden - user is not an admin of this event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"GroupNotFound":{"description":"Group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/groups/{group_handle}":{"patch":{"tags":["Groups"],"summary":"Update a group","description":"Updates the group's name, contact email, or external links. Only the\nfields sent are changed; send an empty string to clear a link. The\nname cannot be set blank. The group's handle is not editable.\nRequires the `groups` permission on the group.\n","operationId":"updateGroup","parameters":[{"$ref":"#/components/parameters/GroupHandle"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGroupRequest"}}}},"responses":{"200":{"description":"The updated group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/GroupNotFound"},"422":{"description":"Validation failed (for example, a blank name)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}}}}
````
## List a group's events
> Returns the group's upcoming events linked directly to it, earliest\
> first, each with whether it has ended. Pass \`include\_past=true\` to\
> include events that have ended. At most 200 events are returned: the\
> next 200 upcoming, or with \`include\_past\`, the 200 most recent. Events\
> that belong to the group only through one of its series are not\
> included. Requires the \`groups\` permission on the group, which every\
> group admin role grants.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Groups","description":"Groups you administer — collections of events run together, such as a\nrace series or a club's calendar — and the events linked to them.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"parameters":{"GroupHandle":{"name":"group_handle","in":"path","required":true,"description":"The unique handle (slug) of the group","schema":{"type":"string"}}},"schemas":{"GroupEvent":{"description":"An EventSummary plus whether the event has ended.","allOf":[{"$ref":"#/components/schemas/EventSummary"},{"type":"object","required":["past"],"properties":{"past":{"type":"boolean","description":"Whether the event has ended"}}}]},"EventSummary":{"type":"object","description":"Compact list-view representation of an event, returned by\n`GET /api/v1/events`. All properties are always present; nullable\nproperties may have a null value.\n","required":["id","handle","name","status","start_date","end_date","city","state"],"properties":{"id":{"type":"integer","description":"Unique event identifier"},"handle":{"type":"string","description":"URL-safe unique identifier used to address the event on other endpoints"},"name":{"type":"string","nullable":true,"description":"Event name"},"status":{"type":"string","description":"Event lifecycle status"},"start_date":{"type":"string","format":"date","nullable":true,"description":"Event start date (YYYY-MM-DD)"},"end_date":{"type":"string","format":"date","nullable":true,"description":"Event end date (YYYY-MM-DD)"},"city":{"type":"string","nullable":true,"description":"Event city"},"state":{"type":"string","nullable":true,"description":"Event state or region"}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"Forbidden":{"description":"Forbidden - user is not an admin of this event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"GroupNotFound":{"description":"Group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/groups/{group_handle}/events":{"get":{"tags":["Groups"],"summary":"List a group's events","description":"Returns the group's upcoming events linked directly to it, earliest\nfirst, each with whether it has ended. Pass `include_past=true` to\ninclude events that have ended. At most 200 events are returned: the\nnext 200 upcoming, or with `include_past`, the 200 most recent. Events\nthat belong to the group only through one of its series are not\nincluded. Requires the `groups` permission on the group, which every\ngroup admin role grants.\n","operationId":"listGroupEvents","parameters":[{"$ref":"#/components/parameters/GroupHandle"},{"name":"include_past","in":"query","required":false,"description":"Include events that have already ended.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The group's direct events","content":{"application/json":{"schema":{"type":"object","required":["events","truncated"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/GroupEvent"}},"truncated":{"type":"boolean","description":"More events matched than the 200 returned"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/GroupNotFound"}}}}}}
````
## List a group's questions
> Returns the group's own questions: the shared library its events can\
> import. At most 200 are returned. Requires the \`question\_management\`\
> permission on the group, which every group role (owner, admin, race\
> director) grants.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Groups","description":"Groups you administer — collections of events run together, such as a\nrace series or a club's calendar — and the events linked to them.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"parameters":{"GroupHandle":{"name":"group_handle","in":"path","required":true,"description":"The unique handle (slug) of the group","schema":{"type":"string"}}},"schemas":{"CustomQuestion":{"type":"object","required":["id","question_id","title","question_type","required","order","starts_at","ends_at","options","children"],"properties":{"id":{"type":"integer","format":"int64","description":"TransactableCustomQuestion id (the link row, used for update/delete)."},"question_id":{"type":"integer","format":"int64"},"title":{"type":"string"},"question_type":{"type":"string","enum":["text","multiple_choice","time_hr_min_second","time_min_second"]},"required":{"type":"boolean"},"order":{"type":"integer"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"options":{"type":"array","description":"Answer options in the order they are shown to registrants.","items":{"$ref":"#/components/schemas/CustomQuestionOption"}},"children":{"type":"array","description":"Conditional child questions revealed by this question's answers. Only multiple-choice questions can have children; empty otherwise.","items":{"$ref":"#/components/schemas/NestedQuestionChild"}}}},"CustomQuestionOption":{"type":"object","required":["id","label"],"properties":{"id":{"type":"integer","format":"int64"},"label":{"type":"string"}}},"NestedQuestionChild":{"type":"object","description":"A conditional (nested) child question shown only when this question is answered with one of the trigger options. References a question that also appears in full elsewhere in the questions list.","required":["link_id","child_question_id","show_when"],"properties":{"link_id":{"type":"integer","format":"int64","description":"NestedQuestionLink id (used to delete the link)."},"child_question_id":{"type":"integer","format":"int64","description":"Question id (the `id` field) of the child question to show."},"show_when":{"type":"array","description":"Parent option labels that reveal the child question.","items":{"type":"string"}}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"Forbidden":{"description":"Forbidden - user is not an admin of this event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"GroupNotFound":{"description":"Group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/groups/{group_handle}/questions":{"get":{"tags":["Groups"],"summary":"List a group's questions","description":"Returns the group's own questions: the shared library its events can\nimport. At most 200 are returned. Requires the `question_management`\npermission on the group, which every group role (owner, admin, race\ndirector) grants.\n","operationId":"listGroupQuestions","parameters":[{"$ref":"#/components/parameters/GroupHandle"}],"responses":{"200":{"description":"Ordered list of the group's questions","content":{"application/json":{"schema":{"type":"object","required":["questions","truncated"],"properties":{"questions":{"type":"array","items":{"$ref":"#/components/schemas/CustomQuestion"}},"truncated":{"type":"boolean","description":"More questions exist than the 200 returned"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/GroupNotFound"}}}}}}
````
## Add a question to a group
> Adds a question to the group's shared library. It isn't asked on any\
> registration until an event imports it from the group. An import\
> starts from this question's \`required\` flag and visibility window.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Groups","description":"Groups you administer — collections of events run together, such as a\nrace series or a club's calendar — and the events linked to them.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"parameters":{"GroupHandle":{"name":"group_handle","in":"path","required":true,"description":"The unique handle (slug) of the group","schema":{"type":"string"}}},"schemas":{"CreateQuestionRequest":{"type":"object","required":["title","question_type"],"properties":{"title":{"type":"string"},"question_type":{"type":"string","enum":["text","multiple_choice","time_hr_min_second","time_min_second"]},"required":{"type":"boolean"},"options":{"type":"array","description":"Answer options, in the order registrants should see them.","items":{"type":"string"}},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO 8601. A bare date is midnight in the event's time zone, or midnight UTC for a group question, since a group has no time zone. A value that doesn't parse is refused with 422; send an empty string or null to clear it."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"Same rules as starts_at."}}},"CustomQuestion":{"type":"object","required":["id","question_id","title","question_type","required","order","starts_at","ends_at","options","children"],"properties":{"id":{"type":"integer","format":"int64","description":"TransactableCustomQuestion id (the link row, used for update/delete)."},"question_id":{"type":"integer","format":"int64"},"title":{"type":"string"},"question_type":{"type":"string","enum":["text","multiple_choice","time_hr_min_second","time_min_second"]},"required":{"type":"boolean"},"order":{"type":"integer"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"options":{"type":"array","description":"Answer options in the order they are shown to registrants.","items":{"$ref":"#/components/schemas/CustomQuestionOption"}},"children":{"type":"array","description":"Conditional child questions revealed by this question's answers. Only multiple-choice questions can have children; empty otherwise.","items":{"$ref":"#/components/schemas/NestedQuestionChild"}}}},"CustomQuestionOption":{"type":"object","required":["id","label"],"properties":{"id":{"type":"integer","format":"int64"},"label":{"type":"string"}}},"NestedQuestionChild":{"type":"object","description":"A conditional (nested) child question shown only when this question is answered with one of the trigger options. References a question that also appears in full elsewhere in the questions list.","required":["link_id","child_question_id","show_when"],"properties":{"link_id":{"type":"integer","format":"int64","description":"NestedQuestionLink id (used to delete the link)."},"child_question_id":{"type":"integer","format":"int64","description":"Question id (the `id` field) of the child question to show."},"show_when":{"type":"array","description":"Parent option labels that reveal the child question.","items":{"type":"string"}}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"Forbidden":{"description":"Forbidden - user is not an admin of this event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"GroupNotFound":{"description":"Group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/groups/{group_handle}/questions":{"post":{"tags":["Groups"],"summary":"Add a question to a group","description":"Adds a question to the group's shared library. It isn't asked on any\nregistration until an event imports it from the group. An import\nstarts from this question's `required` flag and visibility window.\n","operationId":"createGroupQuestion","parameters":[{"$ref":"#/components/parameters/GroupHandle"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQuestionRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"question":{"$ref":"#/components/schemas/CustomQuestion"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/GroupNotFound"},"422":{"description":"Missing title, unknown question_type, a starts_at/ends_at that isn't ISO 8601, or an ends_at before starts_at","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````
## Delete a group question
> Refused with 422 once any event has imported the question, or if\
> registrants have answered it.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Groups","description":"Groups you administer — collections of events run together, such as a\nrace series or a club's calendar — and the events linked to them.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"parameters":{"GroupHandle":{"name":"group_handle","in":"path","required":true,"description":"The unique handle (slug) of the group","schema":{"type":"string"}},"ResourceId":{"name":"id","in":"path","required":true,"description":"The ID of the resource","schema":{"type":"integer","format":"int64"}}},"responses":{"Unauthorized":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"Forbidden":{"description":"Forbidden - user is not an admin of this event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}}}},"paths":{"/api/v1/groups/{group_handle}/questions/{id}":{"delete":{"tags":["Groups"],"summary":"Delete a group question","description":"Refused with 422 once any event has imported the question, or if\nregistrants have answered it.\n","operationId":"deleteGroupQuestion","parameters":[{"$ref":"#/components/parameters/GroupHandle"},{"$ref":"#/components/parameters/ResourceId"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","enum":[true]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The group, or this question in it, doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The question has been imported by an event, or has answers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````
## Update a group question's settings
> Sets the group's own copy of the question: whether it's required and\
> when it's visible. Events start from these when they import the\
> question later; events that already imported it keep their own\
> settings. Send an empty string to clear a date. A bare date is read as\
> midnight UTC, since a group has no time zone. Other fields (title,\
> question\_type, options) are ignored here.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Groups","description":"Groups you administer — collections of events run together, such as a\nrace series or a club's calendar — and the events linked to them.\n"}],"servers":[{"url":"https://www.movemint.cc","description":"Production"}],"security":[{"bearerAuth":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass the access token in the `Authorization` header:\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n"},"oauth2":{"type":"oauth2","description":"OAuth 2.0 authentication using the Authorization Code or Client\nCredentials grant flow.\n","flows":{"authorizationCode":{"authorizationUrl":"https://www.movemint.cc/oauth/authorize","tokenUrl":"https://www.movemint.cc/oauth/token","refreshUrl":"https://www.movemint.cc/oauth/token","scopes":{}},"clientCredentials":{"tokenUrl":"https://www.movemint.cc/oauth/token","scopes":{}}}}},"parameters":{"GroupHandle":{"name":"group_handle","in":"path","required":true,"description":"The unique handle (slug) of the group","schema":{"type":"string"}},"ResourceId":{"name":"id","in":"path","required":true,"description":"The ID of the resource","schema":{"type":"integer","format":"int64"}}},"schemas":{"UpdateGroupQuestionRequest":{"type":"object","properties":{"required":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"ISO 8601. A bare date is midnight UTC, since a group has no time zone. A value that doesn't parse is refused with 422; send an empty string or null to clear it."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"Same rules as starts_at."}}},"CustomQuestion":{"type":"object","required":["id","question_id","title","question_type","required","order","starts_at","ends_at","options","children"],"properties":{"id":{"type":"integer","format":"int64","description":"TransactableCustomQuestion id (the link row, used for update/delete)."},"question_id":{"type":"integer","format":"int64"},"title":{"type":"string"},"question_type":{"type":"string","enum":["text","multiple_choice","time_hr_min_second","time_min_second"]},"required":{"type":"boolean"},"order":{"type":"integer"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"options":{"type":"array","description":"Answer options in the order they are shown to registrants.","items":{"$ref":"#/components/schemas/CustomQuestionOption"}},"children":{"type":"array","description":"Conditional child questions revealed by this question's answers. Only multiple-choice questions can have children; empty otherwise.","items":{"$ref":"#/components/schemas/NestedQuestionChild"}}}},"CustomQuestionOption":{"type":"object","required":["id","label"],"properties":{"id":{"type":"integer","format":"int64"},"label":{"type":"string"}}},"NestedQuestionChild":{"type":"object","description":"A conditional (nested) child question shown only when this question is answered with one of the trigger options. References a question that also appears in full elsewhere in the questions list.","required":["link_id","child_question_id","show_when"],"properties":{"link_id":{"type":"integer","format":"int64","description":"NestedQuestionLink id (used to delete the link)."},"child_question_id":{"type":"integer","format":"int64","description":"Question id (the `id` field) of the child question to show."},"show_when":{"type":"array","description":"Parent option labels that reveal the child question.","items":{"type":"string"}}}},"OAuthError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code"},"error_description":{"type":"string","description":"Human-readable description of the error"}}},"Error":{"type":"object","description":"A generic error response","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - invalid or missing token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}},"Forbidden":{"description":"Forbidden - user is not an admin of this event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/groups/{group_handle}/questions/{id}":{"patch":{"tags":["Groups"],"summary":"Update a group question's settings","description":"Sets the group's own copy of the question: whether it's required and\nwhen it's visible. Events start from these when they import the\nquestion later; events that already imported it keep their own\nsettings. Send an empty string to clear a date. A bare date is read as\nmidnight UTC, since a group has no time zone. Other fields (title,\nquestion_type, options) are ignored here.\n","operationId":"updateGroupQuestion","parameters":[{"$ref":"#/components/parameters/GroupHandle"},{"$ref":"#/components/parameters/ResourceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGroupQuestionRequest"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"question":{"$ref":"#/components/schemas/CustomQuestion"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The group, or this question in it, doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A date that isn't ISO 8601, or an ends_at before starts_at","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````