> 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/event-lifecycle.md).
# Event Lifecycle
Endpoints for moving an event through its lifecycle (status changes, pricing model lock-in, readiness checks).
## Get the readiness report for an event
> Returns the list of blocking issues and warnings that determine\
> whether an event can transition to \`live\` or \`unlisted\`. An event is\
> ready when \`blocking\` is an empty array; warnings are surfaced for\
> organizer attention but do not gate publishing.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Event Lifecycle","description":"Endpoints for moving an event through its lifecycle (status changes,\npricing model lock-in, readiness checks).\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":{"EventHandle":{"name":"handle","in":"path","required":true,"description":"The unique handle (slug) of the event","schema":{"type":"string"}}},"schemas":{"ReadinessReport":{"type":"object","required":["ready","blocking","warnings"],"properties":{"ready":{"type":"boolean","description":"True when there are no blocking issues."},"blocking":{"type":"array","items":{"$ref":"#/components/schemas/ReadinessIssue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ReadinessIssue"}}}},"ReadinessIssue":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code for the issue."},"message":{"type":"string","description":"Human-readable explanation of what to fix."},"sub_event_id":{"type":"integer","format":"int64","description":"Present when the issue is scoped to a specific sub-event."}}},"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"}}}},"EventNotFound":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/events/{handle}/readiness":{"get":{"tags":["Event Lifecycle"],"summary":"Get the readiness report for an event","description":"Returns the list of blocking issues and warnings that determine\nwhether an event can transition to `live` or `unlisted`. An event is\nready when `blocking` is an empty array; warnings are surfaced for\norganizer attention but do not gate publishing.\n","operationId":"getEventReadiness","parameters":[{"$ref":"#/components/parameters/EventHandle"}],"responses":{"200":{"description":"Readiness report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/EventNotFound"}}}}}}
````
## Update an event's status
> Transition an event between statuses (\`draft\`, \`live\`, \`unlisted\`,\
> \`cancelled\`, \`archived\`). Transitions to \`live\` or \`unlisted\` are\
> gated by the readiness check — if blocking issues remain, the\
> response is \`422\` with the same \`blocking\` / \`warnings\` shape\
> returned by \`GET /readiness\`.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Event Lifecycle","description":"Endpoints for moving an event through its lifecycle (status changes,\npricing model lock-in, readiness checks).\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":{"EventHandle":{"name":"handle","in":"path","required":true,"description":"The unique handle (slug) of the event","schema":{"type":"string"}}},"schemas":{"EventStatusUpdate":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["draft","live","unlisted","cancelled","archived"]}}},"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"}}},"ReadinessGatedError":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"blocking":{"type":"array","items":{"$ref":"#/components/schemas/ReadinessIssue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ReadinessIssue"}}}},"ReadinessIssue":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code for the issue."},"message":{"type":"string","description":"Human-readable explanation of what to fix."},"sub_event_id":{"type":"integer","format":"int64","description":"Present when the issue is scoped to a specific sub-event."}}}},"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"}}}},"EventNotFound":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/events/{handle}/status":{"patch":{"tags":["Event Lifecycle"],"summary":"Update an event's status","description":"Transition an event between statuses (`draft`, `live`, `unlisted`,\n`cancelled`, `archived`). Transitions to `live` or `unlisted` are\ngated by the readiness check — if blocking issues remain, the\nresponse is `422` with the same `blocking` / `warnings` shape\nreturned by `GET /readiness`.\n","operationId":"updateEventStatus","parameters":[{"$ref":"#/components/parameters/EventHandle"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventStatusUpdate"}}}},"responses":{"200":{"description":"Status updated","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"The new event status."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/EventNotFound"},"422":{"description":"Status invalid or readiness check failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessGatedError"}}}}}}}}}
````
## Set or change the event's pricing model (free vs paid)
> Sets whether the event is \`is\_free\`. Restricted to the event owner.\
> \
> On the first call it records the decision and stamps\
> \`pricing\_model\_confirmed\_at\`. It can also be called afterwards to\
> switch an already-configured event: switching to paid\
> (\`is\_free: false\`) requires a connected Stripe account that can accept\
> payments, and switching to free (\`is\_free: true\`) requires a\
> currently-paid event; either returns \`422\` otherwise. Switching to free\
> does not refund or change existing paid registrations.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Event Lifecycle","description":"Endpoints for moving an event through its lifecycle (status changes,\npricing model lock-in, readiness checks).\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":{"EventHandle":{"name":"handle","in":"path","required":true,"description":"The unique handle (slug) of the event","schema":{"type":"string"}}},"schemas":{"PricingModelUpdate":{"type":"object","required":["is_free"],"properties":{"is_free":{"type":"boolean","description":"True for a free event, false for a paid event."}}},"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"}}}},"EventNotFound":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/events/{handle}/pricing_model":{"patch":{"tags":["Event Lifecycle"],"summary":"Set or change the event's pricing model (free vs paid)","description":"Sets whether the event is `is_free`. Restricted to the event owner.\n\nOn the first call it records the decision and stamps\n`pricing_model_confirmed_at`. It can also be called afterwards to\nswitch an already-configured event: switching to paid\n(`is_free: false`) requires a connected Stripe account that can accept\npayments, and switching to free (`is_free: true`) requires a\ncurrently-paid event; either returns `422` otherwise. Switching to free\ndoes not refund or change existing paid registrations.\n","operationId":"updateEventPricingModel","parameters":[{"$ref":"#/components/parameters/EventHandle"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricingModelUpdate"}}}},"responses":{"200":{"description":"Pricing model locked in","content":{"application/json":{"schema":{"type":"object","required":["id","is_free","pricing_model_confirmed_at"],"properties":{"id":{"type":"integer","format":"int64"},"is_free":{"type":"boolean"},"pricing_model_confirmed_at":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/EventNotFound"},"422":{"description":"Already in the requested state, paid requires Stripe, or `is_free` missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````
## Promote a marketing photo to the event cover photo
> Copies a photo from the event's marketing album into the event's\
> ActiveStorage \`cover\_photo\` slot. The source photo must already be\
> \`ready\` (i.e., processed). The marketing photo itself is not\
> removed from the album.
````json
{"openapi":"3.1.0","info":{"title":"Movemint API","version":"1.0"},"tags":[{"name":"Event Lifecycle","description":"Endpoints for moving an event through its lifecycle (status changes,\npricing model lock-in, readiness checks).\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":{"EventHandle":{"name":"handle","in":"path","required":true,"description":"The unique handle (slug) of the event","schema":{"type":"string"}}},"schemas":{"CoverPhotoUpdate":{"type":"object","required":["marketing_photo_uuid"],"properties":{"marketing_photo_uuid":{"type":"string","description":"UUID of a `ready` photo in the event's marketing album."}}},"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"}}}},"EventNotFound":{"description":"Event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/events/{handle}/cover_photo":{"patch":{"tags":["Event Lifecycle"],"summary":"Promote a marketing photo to the event cover photo","description":"Copies a photo from the event's marketing album into the event's\nActiveStorage `cover_photo` slot. The source photo must already be\n`ready` (i.e., processed). The marketing photo itself is not\nremoved from the album.\n","operationId":"updateEventCoverPhoto","parameters":[{"$ref":"#/components/parameters/EventHandle"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverPhotoUpdate"}}}},"responses":{"200":{"description":"Cover photo attached","content":{"application/json":{"schema":{"type":"object","required":["event_handle","cover_photo_attached"],"properties":{"event_handle":{"type":"string"},"cover_photo_attached":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/EventNotFound"},"422":{"description":"Source photo missing or not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
````
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://movemint.gitbook.io/movemint-developer-docs/open-api-specification/core-resources/event-lifecycle.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.