{ "components" : { "schemas" : { "AddAreaMemberRequest" : { "description" : "Options when adding a member to an area. The body itself is optional.", "properties" : { "subscribeToNotifications" : { "description" : "Subscribe the member to the area's notifications (new conversation, new event, new survey). Defaults to `true`, which is what the Klubraum app does.", "type" : "boolean" } }, "type" : "object" }, "AddQuestionRequest" : { "description" : "A question to append to the survey.", "properties" : { "question" : { "$ref" : "#/components/schemas/QuestionInput", "description" : "The new question; its id and the ids of its choices are assigned by the server." } }, "required" : [ "question" ], "type" : "object" }, "Address" : { "description" : "A postal address. Every part is free text.", "properties" : { "city" : { "description" : "City.", "maxLength" : 200, "type" : "string" }, "country" : { "description" : "Country.", "maxLength" : 200, "type" : "string" }, "state" : { "description" : "State or region.", "maxLength" : 200, "type" : "string" }, "street" : { "description" : "Street name.", "maxLength" : 200, "type" : "string" }, "streetNumber" : { "description" : "House number.", "maxLength" : 200, "type" : "string" }, "zipCode" : { "description" : "Postal code.", "maxLength" : 200, "type" : "string" } }, "type" : "object" }, "Answer" : { "discriminator" : { "mapping" : { "BOOLEAN" : "#/components/schemas/BooleanAnswer", "CHOICE" : "#/components/schemas/ChoiceAnswer", "FREE_TEXT" : "#/components/schemas/FreeTextAnswer", "MEMBER" : "#/components/schemas/MemberAnswer", "RATING" : "#/components/schemas/RatingAnswer", "SCHEDULING" : "#/components/schemas/SchedulingAnswer" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/BooleanAnswer" }, { "$ref" : "#/components/schemas/ChoiceAnswer" }, { "$ref" : "#/components/schemas/FreeTextAnswer" }, { "$ref" : "#/components/schemas/MemberAnswer" }, { "$ref" : "#/components/schemas/RatingAnswer" }, { "$ref" : "#/components/schemas/SchedulingAnswer" } ] }, "AnswerInput" : { "discriminator" : { "mapping" : { "BOOLEAN" : "#/components/schemas/BooleanAnswerInput", "CHOICE" : "#/components/schemas/ChoiceAnswerInput", "FREE_TEXT" : "#/components/schemas/FreeTextAnswerInput", "MEMBER" : "#/components/schemas/MemberAnswerInput", "RATING" : "#/components/schemas/RatingAnswerInput", "SCHEDULING" : "#/components/schemas/SchedulingAnswerInput" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/BooleanAnswerInput" }, { "$ref" : "#/components/schemas/ChoiceAnswerInput" }, { "$ref" : "#/components/schemas/FreeTextAnswerInput" }, { "$ref" : "#/components/schemas/MemberAnswerInput" }, { "$ref" : "#/components/schemas/RatingAnswerInput" }, { "$ref" : "#/components/schemas/SchedulingAnswerInput" } ] }, "Answerer" : { "discriminator" : { "mapping" : { "CHILD" : "#/components/schemas/ChildAnswerer", "GUEST" : "#/components/schemas/GuestAnswerer", "MEMBER" : "#/components/schemas/MemberAnswerer", "PUBLIC" : "#/components/schemas/PublicAnswerer" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/MemberAnswerer" }, { "$ref" : "#/components/schemas/ChildAnswerer" }, { "$ref" : "#/components/schemas/GuestAnswerer" }, { "$ref" : "#/components/schemas/PublicAnswerer" } ] }, "Area" : { "description" : "An area of a tenant: a team, a department, a committee — the sub-group a Klubraum is divided into.", "properties" : { "administratorIds" : { "description" : "The members who administrate the area; every administrator is also a member.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "archived" : { "description" : "Whether the area is archived. An archived area is read-only and cannot be un-archived.", "type" : "boolean" }, "areaId" : { "description" : "Id of the area.", "format" : "uuid", "type" : "string" }, "color" : { "description" : "Colour of the area as `#RRGGBB` or `#AARRGGBB`.", "type" : "string" }, "conversationCount" : { "description" : "How many conversations are linked to the area.", "format" : "int32", "type" : "integer" }, "createdAt" : { "description" : "When the area was created.", "format" : "date-time", "type" : "string" }, "createdBy" : { "description" : "The member who created the area.", "format" : "uuid", "type" : "string" }, "description" : { "description" : "Description of the area.", "type" : "string" }, "eventCount" : { "description" : "How many calendar events are linked to the area.", "format" : "int32", "type" : "integer" }, "icon" : { "description" : "Icon of the area; one of the names listed in the description of \"Create an area\".", "type" : "string" }, "isHidden" : { "description" : "Whether the area is hidden from the app's area list (it stays reachable through its content).", "type" : "boolean" }, "isPrivate" : { "description" : "Whether only the area's own members see it and its content.", "type" : "boolean" }, "memberIds" : { "description" : "The members of the area.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "name" : { "description" : "Name of the area.", "type" : "string" }, "tenantId" : { "description" : "Id of the tenant the area belongs to.", "format" : "uuid", "type" : "string" } }, "required" : [ "administratorIds", "archived", "areaId", "conversationCount", "createdAt", "createdBy", "eventCount", "isHidden", "isPrivate", "memberIds", "name", "tenantId" ], "type" : "object" }, "AreaAdminSubject" : { "description" : "The administrators of this area.", "properties" : { "type" : { "description" : "Always `areaAdmin`.", "enum" : [ "areaAdmin" ], "type" : "string" } }, "required" : [ "type" ], "type" : "object" }, "AreaCapabilities" : { "description" : "The resolved configuration of all five capabilities of an area.", "properties" : { "configurations" : { "description" : "One entry per capability, always all five.", "items" : { "$ref" : "#/components/schemas/AreaCapabilityConfiguration" }, "type" : "array" } }, "required" : [ "configurations" ], "type" : "object" }, "AreaCapability" : { "enum" : [ "CONVERSATION_CREATOR", "EVENT_CREATOR", "SURVEY_CREATOR", "AREA_READER", "AREA_WRITER" ], "type" : "string" }, "AreaCapabilityConfiguration" : { "description" : "The resolved configuration of one capability of one area.", "properties" : { "capability" : { "$ref" : "#/components/schemas/AreaCapability", "description" : "The capability this configuration is for." }, "isOverride" : { "description" : "`true` when the subjects were configured for this area, `false` when they are the default derived from `isPrivate`.", "type" : "boolean" }, "subjects" : { "description" : "Who the capability is granted to.", "items" : { "$ref" : "#/components/schemas/CapabilitySubject" }, "type" : "array" } }, "required" : [ "capability", "isOverride", "subjects" ], "type" : "object" }, "AreaGroup" : { "description" : "A group that bundles areas for the app's navigation.", "properties" : { "archived" : { "description" : "Whether the area group is archived. An archived group is read-only and cannot be un-archived.", "type" : "boolean" }, "areaGroupId" : { "description" : "Id of the area group.", "format" : "uuid", "type" : "string" }, "areaIds" : { "description" : "The areas in the group, in the order they were added.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "color" : { "description" : "Colour of the area group as `#RRGGBB` or `#AARRGGBB`.", "type" : "string" }, "createdAt" : { "description" : "When the area group was created.", "format" : "date-time", "type" : "string" }, "createdBy" : { "description" : "The member who created the area group.", "format" : "uuid", "type" : "string" }, "description" : { "description" : "Description of the area group.", "type" : "string" }, "icon" : { "description" : "Icon of the area group; one of the names listed in the description of \"Create an area group\".", "type" : "string" }, "name" : { "description" : "Name of the area group.", "type" : "string" }, "tenantId" : { "description" : "Id of the tenant the area group belongs to.", "format" : "uuid", "type" : "string" } }, "required" : [ "archived", "areaGroupId", "areaIds", "createdAt", "createdBy", "name", "tenantId" ], "type" : "object" }, "AreaMemberSubject" : { "description" : "The members of this area.", "properties" : { "type" : { "description" : "Always `areaMember`.", "enum" : [ "areaMember" ], "type" : "string" } }, "required" : [ "type" ], "type" : "object" }, "AreaSummary" : { "description" : "An area as it appears in a list: like `Area`, but with `memberCount` instead of the member and administrator ids.", "properties" : { "areaId" : { "description" : "Id of the area.", "format" : "uuid", "type" : "string" }, "color" : { "description" : "Colour of the area as `#RRGGBB` or `#AARRGGBB`.", "type" : "string" }, "conversationCount" : { "description" : "How many conversations are linked to the area.", "format" : "int32", "type" : "integer" }, "createdAt" : { "description" : "When the area was created.", "format" : "date-time", "type" : "string" }, "createdBy" : { "description" : "The member who created the area.", "format" : "uuid", "type" : "string" }, "description" : { "description" : "Description of the area.", "type" : "string" }, "eventCount" : { "description" : "How many calendar events are linked to the area.", "format" : "int32", "type" : "integer" }, "icon" : { "description" : "Icon of the area.", "type" : "string" }, "isHidden" : { "description" : "Whether the area is hidden from the app's area list.", "type" : "boolean" }, "isPrivate" : { "description" : "Whether only the area's own members see it and its content.", "type" : "boolean" }, "memberCount" : { "description" : "How many members the area has.", "format" : "int32", "type" : "integer" }, "name" : { "description" : "Name of the area.", "type" : "string" }, "tenantId" : { "description" : "Id of the tenant the area belongs to.", "format" : "uuid", "type" : "string" } }, "required" : [ "areaId", "conversationCount", "createdAt", "createdBy", "eventCount", "isHidden", "isPrivate", "memberCount", "name", "tenantId" ], "type" : "object" }, "BooleanAnswer" : { "description" : "An answer to a yes/no question. `type: BOOLEAN`.", "properties" : { "answeredAt" : { "description" : "When the answer was first given.", "format" : "date-time", "type" : "string" }, "answerer" : { "$ref" : "#/components/schemas/Answerer", "description" : "Who answered; absent when the survey hides the answerers." }, "revisedAt" : { "description" : "When the answer was last changed.", "format" : "date-time", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `BOOLEAN`.", "enum" : [ "BOOLEAN" ], "type" : "string" }, "value" : { "description" : "The answer.", "type" : "boolean" } }, "required" : [ "answeredAt", "type", "value" ], "type" : "object" }, "BooleanAnswerInput" : { "description" : "An answer to a yes/no question. `type: BOOLEAN`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `BOOLEAN`.", "enum" : [ "BOOLEAN" ], "type" : "string" }, "value" : { "description" : "The answer.", "type" : "boolean" } }, "required" : [ "type", "value" ], "type" : "object" }, "BooleanQuestion" : { "description" : "A yes/no question. `type: BOOLEAN`.", "properties" : { "description" : { "description" : "Longer explanation shown with the question.", "type" : "string" }, "questionId" : { "description" : "Id of the question.", "format" : "uuid", "type" : "string" }, "questionText" : { "description" : "The question itself.", "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `BOOLEAN`.", "enum" : [ "BOOLEAN" ], "type" : "string" } }, "required" : [ "questionId", "questionText", "required", "type" ], "type" : "object" }, "BooleanQuestionInput" : { "description" : "A yes/no question. `type: BOOLEAN`.", "properties" : { "description" : { "description" : "Longer explanation shown with the question; must not be blank when present.", "maxLength" : 2000, "type" : "string" }, "questionText" : { "description" : "The question itself; must not be blank.", "maxLength" : 500, "minLength" : 1, "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered. Defaults to `false`.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `BOOLEAN`.", "enum" : [ "BOOLEAN" ], "type" : "string" } }, "required" : [ "questionText", "type" ], "type" : "object" }, "BooleanResult" : { "description" : "Aggregated answers of a yes/no question. `type: BOOLEAN`.", "properties" : { "noCount" : { "description" : "How many of them were no.", "format" : "int32", "type" : "integer" }, "resultCount" : { "description" : "How many answers were counted.", "format" : "int32", "type" : "integer" }, "type" : { "description" : "Discriminator of the union; always `BOOLEAN`.", "enum" : [ "BOOLEAN" ], "type" : "string" }, "yesCount" : { "description" : "How many of them were yes.", "format" : "int32", "type" : "integer" } }, "required" : [ "noCount", "resultCount", "type", "yesCount" ], "type" : "object" }, "CancelEventRequest" : { "description" : "Why an event or one of its occurrences is cancelled.", "properties" : { "reason" : { "description" : "Shown to the members next to the cancelled event.", "maxLength" : 200, "type" : "string" } }, "type" : "object" }, "CapabilitySubject" : { "discriminator" : { "mapping" : { "areaAdmin" : "#/components/schemas/AreaAdminSubject", "areaMember" : "#/components/schemas/AreaMemberSubject", "tenantAdmin" : "#/components/schemas/TenantAdminSubject", "tenantMember" : "#/components/schemas/TenantMemberSubject", "tenantRole" : "#/components/schemas/TenantRoleSubject", "user" : "#/components/schemas/UserSubject" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/UserSubject" }, { "$ref" : "#/components/schemas/TenantRoleSubject" }, { "$ref" : "#/components/schemas/AreaAdminSubject" }, { "$ref" : "#/components/schemas/AreaMemberSubject" }, { "$ref" : "#/components/schemas/TenantMemberSubject" }, { "$ref" : "#/components/schemas/TenantAdminSubject" } ] }, "ChildAnswerer" : { "description" : "A member answering for one of their children. `type: CHILD`.", "properties" : { "childId" : { "description" : "The child the answer is for.", "format" : "uuid", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `CHILD`.", "enum" : [ "CHILD" ], "type" : "string" }, "userId" : { "description" : "The member who answered.", "format" : "uuid", "type" : "string" } }, "required" : [ "childId", "type", "userId" ], "type" : "object" }, "Choice" : { "description" : "One choice of a choice question.", "properties" : { "choiceId" : { "description" : "Id of the choice — answers reference it.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label of the choice.", "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "type" : "string" } }, "required" : [ "choiceId", "choiceText" ], "type" : "object" }, "ChoiceAnswer" : { "description" : "An answer to a choice question. `type: CHOICE`.", "properties" : { "answeredAt" : { "description" : "When the answer was first given.", "format" : "date-time", "type" : "string" }, "answerer" : { "$ref" : "#/components/schemas/Answerer", "description" : "Who answered; absent when the survey hides the answerers." }, "choiceIds" : { "description" : "The picked choices.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "customChoices" : { "description" : "Choices the answer added itself.", "items" : { "type" : "string" }, "type" : "array" }, "revisedAt" : { "description" : "When the answer was last changed.", "format" : "date-time", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `CHOICE`.", "enum" : [ "CHOICE" ], "type" : "string" } }, "required" : [ "answeredAt", "choiceIds", "customChoices", "type" ], "type" : "object" }, "ChoiceAnswerInput" : { "description" : "An answer to a choice question. At least one of `choiceIds` and `customChoices` must be non-empty.", "properties" : { "choiceIds" : { "description" : "Ids of the picked choices; each must be a choice of the question.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 100, "type" : "array" }, "customChoices" : { "description" : "Choices of your own; only when the question allows them.", "items" : { "type" : "string" }, "maxItems" : 100, "type" : "array" }, "type" : { "description" : "Discriminator of the union; always `CHOICE`.", "enum" : [ "CHOICE" ], "type" : "string" } }, "required" : [ "type" ], "type" : "object" }, "ChoiceInput" : { "description" : "One choice of a choice question. Leave `choiceId` out for a new choice; when a question is UPDATED every choice that already exists must be sent back with its `choiceId`, or the answers referencing it are lost.", "properties" : { "choiceId" : { "description" : "Id of an existing choice; absent creates a new one.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label of the choice; must not be blank.", "maxLength" : 200, "minLength" : 1, "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "maxLength" : 2000, "type" : "string" } }, "required" : [ "choiceText" ], "type" : "object" }, "ChoiceQuestion" : { "description" : "A question answered by picking from a list of choices. `type: CHOICE`.", "properties" : { "allowCustomChoice" : { "description" : "Whether an answer may add its own choices.", "type" : "boolean" }, "allowMultipleCustomChoices" : { "description" : "Whether an answer may add more than one of its own choices.", "type" : "boolean" }, "choices" : { "description" : "The choices to pick from.", "items" : { "$ref" : "#/components/schemas/Choice" }, "type" : "array" }, "description" : { "description" : "Longer explanation shown with the question.", "type" : "string" }, "maxChoices" : { "description" : "How many choices an answer may pick at most.", "format" : "int32", "type" : "integer" }, "questionId" : { "description" : "Id of the question.", "format" : "uuid", "type" : "string" }, "questionText" : { "description" : "The question itself.", "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered.", "type" : "boolean" }, "singleChoice" : { "description" : "Whether an answer may pick exactly one choice.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `CHOICE`.", "enum" : [ "CHOICE" ], "type" : "string" } }, "required" : [ "allowCustomChoice", "allowMultipleCustomChoices", "choices", "questionId", "questionText", "required", "singleChoice", "type" ], "type" : "object" }, "ChoiceQuestionInput" : { "description" : "A question answered by picking from a list of choices. `type: CHOICE`.", "properties" : { "allowCustomChoice" : { "description" : "Let an answer add its own choices. Defaults to `false`.", "type" : "boolean" }, "allowMultipleCustomChoices" : { "description" : "Let an answer add more than one of its own choices; not allowed together with `singleChoice`.", "type" : "boolean" }, "choices" : { "description" : "The choices to pick from. Required unless `allowCustomChoice` is set.", "items" : { "$ref" : "#/components/schemas/ChoiceInput" }, "maxItems" : 100, "type" : "array" }, "description" : { "description" : "Longer explanation shown with the question; must not be blank when present.", "maxLength" : 2000, "type" : "string" }, "maxChoices" : { "description" : "How many choices an answer may pick at most; not allowed together with `singleChoice`.", "format" : "int32", "maximum" : 100, "minimum" : 1, "type" : "integer" }, "questionText" : { "description" : "The question itself; must not be blank.", "maxLength" : 500, "minLength" : 1, "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered. Defaults to `false`.", "type" : "boolean" }, "singleChoice" : { "description" : "Accept exactly one choice per answer; not allowed together with `maxChoices`.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `CHOICE`.", "enum" : [ "CHOICE" ], "type" : "string" } }, "required" : [ "questionText", "type" ], "type" : "object" }, "ChoiceResult" : { "description" : "Aggregated answers of a choice question. `type: CHOICE`.", "properties" : { "choiceCount" : { "additionalProperties" : { "format" : "int32", "type" : "integer" }, "description" : "How often each choice was picked, by choice id.", "type" : "object" }, "customChoiceCount" : { "additionalProperties" : { "format" : "int32", "type" : "integer" }, "description" : "How often each choice the answers added themselves was given, by its text.", "type" : "object" }, "resultCount" : { "description" : "How many answers were counted.", "format" : "int32", "type" : "integer" }, "type" : { "description" : "Discriminator of the union; always `CHOICE`.", "enum" : [ "CHOICE" ], "type" : "string" } }, "required" : [ "choiceCount", "customChoiceCount", "resultCount", "type" ], "type" : "object" }, "CommitmentOptions" : { "description" : "RSVP behaviour of the event.", "properties" : { "allowChildCommitments" : { "description" : "Members may RSVP for their children.", "type" : "boolean" }, "allowGuestCommitments" : { "description" : "Members may bring guests.", "type" : "boolean" }, "commitmentTimeWindow" : { "$ref" : "#/components/schemas/CommitmentTimeWindow", "description" : "The time window in which RSVPs are accepted." }, "disableCommitmentDeletion" : { "description" : "An RSVP cannot be withdrawn once given.", "type" : "boolean" }, "disableCommitments" : { "description" : "RSVPs are switched off entirely.", "type" : "boolean" }, "disableMaybeCommitments" : { "description" : "The \"maybe\" answer is not offered.", "type" : "boolean" } }, "required" : [ "allowChildCommitments", "allowGuestCommitments", "disableCommitmentDeletion", "disableCommitments", "disableMaybeCommitments" ], "type" : "object" }, "CommitmentOptionsInput" : { "description" : "RSVP behaviour of the event; every flag defaults to `false`.", "properties" : { "allowChildCommitments" : { "description" : "Members may RSVP for their children.", "type" : "boolean" }, "allowGuestCommitments" : { "description" : "Members may bring guests.", "type" : "boolean" }, "commitmentTimeWindow" : { "$ref" : "#/components/schemas/CommitmentTimeWindow", "description" : "The time window in which RSVPs are accepted." }, "disableCommitmentDeletion" : { "description" : "An RSVP cannot be withdrawn once given.", "type" : "boolean" }, "disableCommitments" : { "description" : "Switch RSVPs off entirely.", "type" : "boolean" }, "disableMaybeCommitments" : { "description" : "Do not offer the \"maybe\" answer.", "type" : "boolean" } }, "type" : "object" }, "CommitmentOptionsPatch" : { "description" : "RSVP behaviour in a merge patch: each flag absent (unchanged), `null` (reset to `false`) or set.", "properties" : { "allowChildCommitments" : { "description" : "Members may RSVP for their children.", "type" : [ "boolean", "null" ] }, "allowGuestCommitments" : { "description" : "Members may bring guests.", "type" : [ "boolean", "null" ] }, "commitmentTimeWindow" : { "description" : "The time window in which RSVPs are accepted.", "oneOf" : [ { "$ref" : "#/components/schemas/CommitmentTimeWindow" }, { "type" : "null" } ] }, "disableCommitmentDeletion" : { "description" : "An RSVP cannot be withdrawn once given.", "type" : [ "boolean", "null" ] }, "disableCommitments" : { "description" : "Switch RSVPs off entirely.", "type" : [ "boolean", "null" ] }, "disableMaybeCommitments" : { "description" : "Do not offer the \"maybe\" answer.", "type" : [ "boolean", "null" ] } }, "type" : "object" }, "CommitmentTimeWindow" : { "description" : "When members may RSVP: `earliest` opens the window before the occurrence, `latest` closes it.", "properties" : { "earliest" : { "$ref" : "#/components/schemas/TimeWindowConfig", "description" : "How long before the occurrence RSVPs open." }, "latest" : { "$ref" : "#/components/schemas/TimeWindowConfig", "description" : "How long before the occurrence RSVPs close." } }, "type" : "object" }, "CommitmentType" : { "enum" : [ "PARTICIPATE", "DECLINE", "MAYBE" ], "type" : "string" }, "Conversation" : { "description" : "A conversation with its participants and the state of its message thread.", "properties" : { "context" : { "$ref" : "#/components/schemas/ConversationContext", "description" : "Where the conversation lives; decided at creation." }, "conversationId" : { "description" : "Id of the conversation.", "format" : "uuid", "type" : "string" }, "createdBy" : { "description" : "The member who started the conversation.", "format" : "uuid", "type" : "string" }, "isPrivate" : { "description" : "Whether the conversation is private, i.e. visible only to its participants.", "type" : "boolean" }, "locked" : { "description" : "Whether the conversation is locked, i.e. no further messages are accepted.", "type" : "boolean" }, "messageCount" : { "description" : "How many messages the conversation holds, deleted ones included.", "format" : "int32", "type" : "integer" }, "participantIds" : { "description" : "The members that take part; the creator is always among them.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "subject" : { "description" : "Subject of the conversation; absent when it has none.", "type" : "string" }, "tenantId" : { "description" : "Id of the tenant the conversation belongs to.", "format" : "uuid", "type" : "string" }, "updatedAt" : { "description" : "When the conversation was last changed.", "format" : "date-time", "type" : "string" } }, "required" : [ "context", "conversationId", "createdBy", "isPrivate", "locked", "messageCount", "participantIds", "tenantId", "updatedAt" ], "type" : "object" }, "ConversationContext" : { "description" : "Where the conversation lives. `TENANT` and `AREAS` are standalone conversations, `EVENT` and `RIDE_SHARING` belong to one occurrence of a calendar event and are created on demand when the first message is posted. A private conversation is a `TENANT` context with `isPrivate: true` — privacy is a property of the conversation, not a context of its own.", "properties" : { "areaIds" : { "description" : "The areas the conversation is visible in; empty for a tenant-wide conversation.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "eventId" : { "description" : "`EVENT` and `RIDE_SHARING` only: the calendar event the conversation belongs to.", "format" : "uuid", "type" : "string" }, "instanceId" : { "description" : "`EVENT` and `RIDE_SHARING` only: the occurrence, as the Unix epoch second of its original start.", "format" : "int64", "type" : "integer" }, "rideSharingId" : { "description" : "`RIDE_SHARING` only: the ride sharing the conversation belongs to.", "format" : "uuid", "type" : "string" }, "type" : { "$ref" : "#/components/schemas/ConversationContextType", "description" : "Which kind of context this is: `TENANT` — standalone without areas, tenant-wide unless `isPrivate`; `AREAS` — standalone, visible in `areaIds`; `EVENT` / `RIDE_SHARING` — the conversation of one occurrence or ride sharing." } }, "required" : [ "areaIds", "type" ], "type" : "object" }, "ConversationContextType" : { "enum" : [ "TENANT", "AREAS", "EVENT", "RIDE_SHARING" ], "type" : "string" }, "ConversationSummary" : { "description" : "A conversation as it appears in a list: the same identity and participants as `Conversation`, plus the first message of the thread, and `lastUpdate` instead of `updatedAt` (lists are ordered by it, newest first).", "properties" : { "context" : { "$ref" : "#/components/schemas/ConversationContext", "description" : "Where the conversation lives; decided at creation." }, "conversationId" : { "description" : "Id of the conversation.", "format" : "uuid", "type" : "string" }, "createdBy" : { "description" : "The member who started the conversation.", "format" : "uuid", "type" : "string" }, "headMessage" : { "$ref" : "#/components/schemas/Message", "description" : "The first message of the thread; absent for a conversation without messages." }, "isPrivate" : { "description" : "Whether the conversation is private, i.e. visible only to its participants.", "type" : "boolean" }, "lastUpdate" : { "description" : "When the conversation was last touched — the key the list is ordered and paged by.", "format" : "date-time", "type" : "string" }, "locked" : { "description" : "Whether the conversation is locked, i.e. no further messages are accepted.", "type" : "boolean" }, "messageCount" : { "description" : "How many messages the conversation holds, deleted ones included.", "format" : "int32", "type" : "integer" }, "participantIds" : { "description" : "The members that take part; the creator is always among them.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "subject" : { "description" : "Subject of the conversation; absent when it has none.", "type" : "string" }, "tenantId" : { "description" : "Id of the tenant the conversation belongs to.", "format" : "uuid", "type" : "string" } }, "required" : [ "context", "conversationId", "createdBy", "isPrivate", "lastUpdate", "locked", "messageCount", "participantIds", "tenantId" ], "type" : "object" }, "CreateAreaGroupRequest" : { "description" : "A new area group. Add areas to it with `PUT /v1/tenants/{tenantId}/area-groups/{areaGroupId}/areas/{areaId}`.", "properties" : { "color" : { "description" : "Colour of the area group as `#RRGGBB` or `#AARRGGBB`.", "pattern" : "^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$", "type" : "string" }, "description" : { "description" : "Description of the area group.", "maxLength" : 200, "type" : "string" }, "icon" : { "description" : "Icon of the area group; one of the names listed in the operation description.", "maxLength" : 16, "minLength" : 3, "type" : "string" }, "name" : { "description" : "Name of the area group; must not be blank.", "maxLength" : 75, "minLength" : 1, "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "CreateAreaRequest" : { "description" : "A new area. The token's owner becomes its creator, first member and first administrator.", "properties" : { "color" : { "description" : "Colour of the area as `#RRGGBB` or `#AARRGGBB`.", "pattern" : "^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$", "type" : "string" }, "description" : { "description" : "Description of the area.", "maxLength" : 200, "type" : "string" }, "icon" : { "description" : "Icon of the area; one of the names listed in the operation description.", "maxLength" : 16, "minLength" : 3, "type" : "string" }, "isPrivate" : { "description" : "Whether only the area's own members may see it and its content. Defaults to `false`.", "type" : "boolean" }, "name" : { "description" : "Name of the area; must not be blank.", "maxLength" : 75, "minLength" : 1, "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "CreateConversationRequest" : { "description" : "A new conversation. Its visibility is decided here and is fixed at creation: leave `areaIds`, `isPrivate` and `participantIds` empty for a conversation the whole tenant sees, list `areaIds` for a conversation visible in those areas, or set `isPrivate` and list the members that take part.", "properties" : { "areaIds" : { "description" : "Visibility: the areas the conversation appears in. Empty or absent makes it visible to the whole tenant. Must be empty for a private conversation. Every id must be an area of `{tenantId}` that is not archived, and the token's owner needs the right to start conversations in each of them.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 100, "type" : "array" }, "isPrivate" : { "description" : "Visibility: makes the conversation private, i.e. visible only to `participantIds`. A private conversation must not be assigned to `areaIds`.", "type" : "boolean" }, "message" : { "$ref" : "#/components/schemas/NewMessage", "description" : "The first message of the conversation; a conversation may also start empty." }, "participantIds" : { "description" : "Visibility: the members that take part; each must be an active member of `{tenantId}`. Only allowed together with `isPrivate: true`. The token's owner is always added, so the list may be empty.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 500, "type" : "array" }, "subject" : { "description" : "Subject of the conversation; may be left out.", "maxLength" : 50, "minLength" : 1, "type" : "string" } }, "type" : "object" }, "CreateEventRequest" : { "description" : "A new calendar event. Its visibility is decided here and is fixed at creation: leave `areaIds`, `isPrivate` and `privateInviteeIds` empty for an event the whole tenant sees, list `areaIds` for an event visible in those areas, or set `isPrivate` for an event only its invitees see.", "properties" : { "allDay" : { "description" : "Whether the event covers whole days.", "type" : "boolean" }, "areaIds" : { "description" : "Visibility: the areas the event appears in. Empty or absent makes it visible to the whole tenant. Must be empty for a private event. Every id must be an area of `{tenantId}`, and the token's owner needs the right to create events in each of them.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 100, "type" : "array" }, "color" : { "description" : "Colour of the event as `#RRGGBB` or `#AARRGGBB`.", "type" : "string" }, "commitmentOptions" : { "$ref" : "#/components/schemas/CommitmentOptionsInput", "description" : "RSVP behaviour of the event." }, "description" : { "$ref" : "#/components/schemas/Description", "description" : "Description of the event; `html` is sanitised on write." }, "end" : { "description" : "End of the event; must be after `start`.", "format" : "date-time", "type" : "string" }, "isPrivate" : { "description" : "Visibility: makes the event private, i.e. visible only to `privateInviteeIds` (the token's owner is always among them). A private event must not be assigned to `areaIds`.", "type" : "boolean" }, "location" : { "$ref" : "#/components/schemas/Location", "description" : "Where the event takes place." }, "maxParticipants" : { "description" : "Maximum number of participants; must not be smaller than `minParticipants`.", "format" : "int32", "maximum" : 10000, "minimum" : 0, "type" : "integer" }, "minParticipants" : { "description" : "Minimum number of participants.", "format" : "int32", "maximum" : 10000, "minimum" : 0, "type" : "integer" }, "privateInviteeIds" : { "description" : "Visibility: the members a private event is visible to; each must be an active member of `{tenantId}`. Only allowed together with `isPrivate: true`, where it may also be empty (an event only the token's owner sees).", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 500, "type" : "array" }, "recurrence" : { "$ref" : "#/components/schemas/RecurrenceInput", "description" : "Turns the event into a series. Only the grammar listed in the operation description is accepted." }, "responsibleUserIds" : { "description" : "Members responsible for the event; each must be an active member of `{tenantId}`.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 100, "type" : "array" }, "start" : { "description" : "Start of the event (of the first occurrence for a series). ISO-8601 with offset.", "format" : "date-time", "type" : "string" }, "timeZone" : { "description" : "IANA time zone the event is scheduled in, e.g. `Europe/Berlin`.", "maxLength" : 64, "minLength" : 1, "type" : "string" }, "title" : { "description" : "Title of the event; must not be blank.", "maxLength" : 500, "minLength" : 1, "type" : "string" }, "waitingListDisabled" : { "description" : "Switch the waiting list off once `maxParticipants` is reached.", "type" : "boolean" } }, "required" : [ "end", "start", "timeZone", "title" ], "type" : "object" }, "CreateRoleRequest" : { "description" : "A new role of a tenant.", "properties" : { "description" : { "description" : "Description of the role; trimmed, and an empty string is the same as omitting it.", "maxLength" : 2048, "type" : "string" }, "name" : { "description" : "Name of the role. Surrounding whitespace is removed before the name is checked and stored, so `pattern` describes the trimmed value. It must not collide with an existing live role of this tenant (compared case-insensitively, after trimming).", "maxLength" : 200, "minLength" : 1, "pattern" : "^[A-Za-z0-9À-ÿ'-.,;:*#+/%!\"$&‘’][ A-Za-z0-9À-ÿ'-.,;:*#+/%!\"$&‘’]*$", "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "CreateSurveyRequest" : { "description" : "A new survey or poll.", "properties" : { "activate" : { "description" : "Publish the survey right away instead of leaving it as a draft. With a future `schedule.start` the survey becomes `SCHEDULED` and opens by itself; without one it becomes `ACTIVE`. A survey without questions cannot be published.", "type" : "boolean" }, "context" : { "$ref" : "#/components/schemas/SurveyContextInput", "description" : "Who the survey is for. Fixed at creation." }, "description" : { "description" : "Longer description of the survey.", "maxLength" : 20000, "type" : "string" }, "questions" : { "description" : "The questions, in the order they are answered. A poll must carry exactly one.", "items" : { "$ref" : "#/components/schemas/QuestionInput" }, "maxItems" : 100, "type" : "array" }, "schedule" : { "$ref" : "#/components/schemas/SurveySchedule", "description" : "When the survey opens and closes." }, "settings" : { "$ref" : "#/components/schemas/SurveySettingsInput", "description" : "How the survey behaves and who may see its data." }, "title" : { "description" : "Title of the survey.", "maxLength" : 200, "type" : "string" }, "type" : { "$ref" : "#/components/schemas/SurveyType", "description" : "Whether to create a survey (any number of questions) or a poll (exactly one)." } }, "required" : [ "context", "questions", "type" ], "type" : "object" }, "CustomChoiceSettings" : { "description" : "What kinds of date/time a caller may add to a scheduling question that allows custom choices.", "properties" : { "allowMultiple" : { "description" : "More than one custom choice may be added in the same answer.", "type" : "boolean" }, "allowedDateRange" : { "$ref" : "#/components/schemas/DateRange", "description" : "Custom dates must fall inside this range." }, "allowedDateTimeRange" : { "$ref" : "#/components/schemas/DateTimeRange", "description" : "Custom date-times must fall inside this range." }, "allowedTimeRange" : { "$ref" : "#/components/schemas/TimeRange", "description" : "Custom times must fall inside this range." }, "dateEnabled" : { "description" : "A single date may be added.", "type" : "boolean" }, "dateRangeEnabled" : { "description" : "A range of dates may be added.", "type" : "boolean" }, "dateTimeEnabled" : { "description" : "A single date-time may be added.", "type" : "boolean" }, "dateTimeRangeEnabled" : { "description" : "A range of date-times may be added.", "type" : "boolean" }, "timeEnabled" : { "description" : "A single time of day may be added.", "type" : "boolean" }, "timeRangeEnabled" : { "description" : "A range of times may be added.", "type" : "boolean" } }, "required" : [ "allowMultiple", "dateEnabled", "dateRangeEnabled", "dateTimeEnabled", "dateTimeRangeEnabled", "timeEnabled", "timeRangeEnabled" ], "type" : "object" }, "CustomChoiceSettingsInput" : { "description" : "What kinds of date/time an answer may add. At least one of the six flags must be set when the question allows custom choices; every flag defaults to `false`.", "properties" : { "allowMultiple" : { "description" : "Allow more than one custom choice in the same answer; not allowed together with `singleChoice`.", "type" : "boolean" }, "allowedDateRange" : { "$ref" : "#/components/schemas/DateRange", "description" : "Restrict custom dates to this range." }, "allowedDateTimeRange" : { "$ref" : "#/components/schemas/DateTimeRange", "description" : "Restrict custom date-times to this range." }, "allowedTimeRange" : { "$ref" : "#/components/schemas/TimeRange", "description" : "Restrict custom times to this range." }, "dateEnabled" : { "description" : "Allow a single date.", "type" : "boolean" }, "dateRangeEnabled" : { "description" : "Allow a range of dates.", "type" : "boolean" }, "dateTimeEnabled" : { "description" : "Allow a single date-time.", "type" : "boolean" }, "dateTimeRangeEnabled" : { "description" : "Allow a range of date-times.", "type" : "boolean" }, "timeEnabled" : { "description" : "Allow a single time of day.", "type" : "boolean" }, "timeRangeEnabled" : { "description" : "Allow a range of times.", "type" : "boolean" } }, "type" : "object" }, "CustomDateAnswer" : { "description" : "A single date. `type: DATE`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `DATE`.", "enum" : [ "DATE" ], "type" : "string" }, "value" : { "description" : "The date.", "format" : "date", "type" : "string" } }, "required" : [ "type", "value" ], "type" : "object" }, "CustomDateRangeAnswer" : { "description" : "A range of dates. `type: DATE_RANGE`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `DATE_RANGE`.", "enum" : [ "DATE_RANGE" ], "type" : "string" }, "value" : { "$ref" : "#/components/schemas/DateRange", "description" : "The range of dates." } }, "required" : [ "type", "value" ], "type" : "object" }, "CustomDateTimeAnswer" : { "description" : "A single date-time. `type: DATE_TIME`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `DATE_TIME`.", "enum" : [ "DATE_TIME" ], "type" : "string" }, "value" : { "description" : "The date-time.", "format" : "date-time", "type" : "string" } }, "required" : [ "type", "value" ], "type" : "object" }, "CustomDateTimeRangeAnswer" : { "description" : "A range of date-times. `type: DATE_TIME_RANGE`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `DATE_TIME_RANGE`.", "enum" : [ "DATE_TIME_RANGE" ], "type" : "string" }, "value" : { "$ref" : "#/components/schemas/DateTimeRange", "description" : "The range of date-times." } }, "required" : [ "type", "value" ], "type" : "object" }, "CustomSchedulingAnswer" : { "discriminator" : { "mapping" : { "DATE" : "#/components/schemas/CustomDateAnswer", "DATE_RANGE" : "#/components/schemas/CustomDateRangeAnswer", "DATE_TIME" : "#/components/schemas/CustomDateTimeAnswer", "DATE_TIME_RANGE" : "#/components/schemas/CustomDateTimeRangeAnswer", "TIME" : "#/components/schemas/CustomTimeAnswer", "TIME_RANGE" : "#/components/schemas/CustomTimeRangeAnswer" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/CustomDateAnswer" }, { "$ref" : "#/components/schemas/CustomTimeAnswer" }, { "$ref" : "#/components/schemas/CustomDateTimeAnswer" }, { "$ref" : "#/components/schemas/CustomDateRangeAnswer" }, { "$ref" : "#/components/schemas/CustomTimeRangeAnswer" }, { "$ref" : "#/components/schemas/CustomDateTimeRangeAnswer" } ] }, "CustomTimeAnswer" : { "description" : "A single time of day. `type: TIME`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `TIME`.", "enum" : [ "TIME" ], "type" : "string" }, "value" : { "description" : "The time of day.", "format" : "time", "type" : "string" } }, "required" : [ "type", "value" ], "type" : "object" }, "CustomTimeRangeAnswer" : { "description" : "A range of times of day. `type: TIME_RANGE`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `TIME_RANGE`.", "enum" : [ "TIME_RANGE" ], "type" : "string" }, "value" : { "$ref" : "#/components/schemas/TimeRange", "description" : "The range of times." } }, "required" : [ "type", "value" ], "type" : "object" }, "DateChoice" : { "description" : "A single date. `type: DATE`.", "properties" : { "choiceId" : { "description" : "Id of the choice — answers reference it.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the date.", "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `DATE`.", "enum" : [ "DATE" ], "type" : "string" }, "value" : { "description" : "The date.", "format" : "date", "type" : "string" } }, "required" : [ "choiceId", "type", "value" ], "type" : "object" }, "DateChoiceInput" : { "description" : "A single date. `type: DATE`.", "properties" : { "choiceId" : { "description" : "Id of an existing choice; absent creates a new one.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the date.", "maxLength" : 200, "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "maxLength" : 2000, "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `DATE`.", "enum" : [ "DATE" ], "type" : "string" }, "value" : { "description" : "The date.", "format" : "date", "type" : "string" } }, "required" : [ "type", "value" ], "type" : "object" }, "DateRange" : { "description" : "A range of dates, both ends inclusive.", "properties" : { "end" : { "description" : "Last date of the range; must not be before `start`.", "format" : "date", "type" : "string" }, "start" : { "description" : "First date of the range.", "format" : "date", "type" : "string" } }, "required" : [ "end", "start" ], "type" : "object" }, "DateRangeChoice" : { "description" : "A range of dates. `type: DATE_RANGE`.", "properties" : { "choiceId" : { "description" : "Id of the choice — answers reference it.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the range.", "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `DATE_RANGE`.", "enum" : [ "DATE_RANGE" ], "type" : "string" }, "value" : { "$ref" : "#/components/schemas/DateRange", "description" : "The range of dates." } }, "required" : [ "choiceId", "type", "value" ], "type" : "object" }, "DateRangeChoiceInput" : { "description" : "A range of dates. `type: DATE_RANGE`.", "properties" : { "choiceId" : { "description" : "Id of an existing choice; absent creates a new one.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the range.", "maxLength" : 200, "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "maxLength" : 2000, "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `DATE_RANGE`.", "enum" : [ "DATE_RANGE" ], "type" : "string" }, "value" : { "$ref" : "#/components/schemas/DateRange", "description" : "The range of dates; `end` must not be before `start`." } }, "required" : [ "type", "value" ], "type" : "object" }, "DateTimeChoice" : { "description" : "A single date-time. `type: DATE_TIME`.", "properties" : { "choiceId" : { "description" : "Id of the choice — answers reference it.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the date-time.", "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `DATE_TIME`.", "enum" : [ "DATE_TIME" ], "type" : "string" }, "value" : { "description" : "The date-time.", "format" : "date-time", "type" : "string" } }, "required" : [ "choiceId", "type", "value" ], "type" : "object" }, "DateTimeChoiceInput" : { "description" : "A single date-time. `type: DATE_TIME`.", "properties" : { "choiceId" : { "description" : "Id of an existing choice; absent creates a new one.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the date-time.", "maxLength" : 200, "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "maxLength" : 2000, "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `DATE_TIME`.", "enum" : [ "DATE_TIME" ], "type" : "string" }, "value" : { "description" : "The date-time.", "format" : "date-time", "type" : "string" } }, "required" : [ "type", "value" ], "type" : "object" }, "DateTimeRange" : { "description" : "A range of date-times, both ends inclusive.", "properties" : { "end" : { "description" : "End of the range; must not be before `start`.", "format" : "date-time", "type" : "string" }, "start" : { "description" : "Start of the range.", "format" : "date-time", "type" : "string" } }, "required" : [ "end", "start" ], "type" : "object" }, "DateTimeRangeChoice" : { "description" : "A range of date-times. `type: DATE_TIME_RANGE`.", "properties" : { "choiceId" : { "description" : "Id of the choice — answers reference it.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the range.", "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `DATE_TIME_RANGE`.", "enum" : [ "DATE_TIME_RANGE" ], "type" : "string" }, "value" : { "$ref" : "#/components/schemas/DateTimeRange", "description" : "The range of date-times." } }, "required" : [ "choiceId", "type", "value" ], "type" : "object" }, "DateTimeRangeChoiceInput" : { "description" : "A range of date-times. `type: DATE_TIME_RANGE`.", "properties" : { "choiceId" : { "description" : "Id of an existing choice; absent creates a new one.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the range.", "maxLength" : 200, "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "maxLength" : 2000, "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `DATE_TIME_RANGE`.", "enum" : [ "DATE_TIME_RANGE" ], "type" : "string" }, "value" : { "$ref" : "#/components/schemas/DateTimeRange", "description" : "The range of date-times; `end` must not be before `start`." } }, "required" : [ "type", "value" ], "type" : "object" }, "Description" : { "description" : "Description of an event: plain text and an optional rich-text version.", "properties" : { "html" : { "description" : "Rich-text description. Sanitised on write: only a safe subset of HTML survives.", "maxLength" : 50000, "type" : "string" }, "text" : { "description" : "Plain-text description.", "maxLength" : 20000, "type" : "string" } }, "required" : [ "text" ], "type" : "object" }, "EditMessageRequest" : { "description" : "The new body of a message; it replaces the previous one entirely.", "properties" : { "html" : { "description" : "Rich-text body. Sanitised on write: only a safe subset of HTML survives.", "maxLength" : 50000, "type" : "string" }, "text" : { "description" : "Plain-text body; must not be blank.", "maxLength" : 20000, "minLength" : 1, "type" : "string" } }, "required" : [ "text" ], "type" : "object" }, "Event" : { "description" : "A calendar event. Its visibility (`isPrivate`, `areaIds`, `privateInviteeIds`) is fixed at creation.", "properties" : { "allDay" : { "description" : "Whether the event covers whole days (`start`/`end` still carry the times).", "type" : "boolean" }, "areaIds" : { "description" : "The areas the event is visible in; empty means it is visible to the whole tenant (or, with `isPrivate`, only to its invitees). Fixed at creation.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "cancellationReason" : { "description" : "Why the event was cancelled.", "type" : "string" }, "cancelled" : { "description" : "Whether the whole series is cancelled.", "type" : "boolean" }, "color" : { "description" : "Colour of the event as `#RRGGBB` or `#AARRGGBB`.", "type" : "string" }, "commitmentOptions" : { "$ref" : "#/components/schemas/CommitmentOptions", "description" : "RSVP behaviour of the event." }, "createdBy" : { "description" : "The member who created the event.", "format" : "uuid", "type" : "string" }, "description" : { "$ref" : "#/components/schemas/Description", "description" : "Description of the event." }, "end" : { "description" : "End of the event (of the first occurrence for a series), in `timeZone`.", "format" : "date-time", "type" : "string" }, "eventId" : { "description" : "Id of the event.", "format" : "uuid", "type" : "string" }, "instanceOverrides" : { "description" : "Occurrences of a series that deviate from it (moved, cancelled or deleted).", "items" : { "$ref" : "#/components/schemas/InstanceOverride" }, "type" : "array" }, "isPrivate" : { "description" : "Whether the event is private, i.e. visible only to `privateInviteeIds`. Fixed at creation.", "type" : "boolean" }, "location" : { "$ref" : "#/components/schemas/Location", "description" : "Where the event takes place." }, "maxParticipants" : { "description" : "Maximum number of participants; further RSVPs go to the waiting list.", "format" : "int32", "type" : "integer" }, "minParticipants" : { "description" : "Minimum number of participants.", "format" : "int32", "type" : "integer" }, "privateInviteeIds" : { "description" : "The members a private event is visible to (the creator included); empty for a non-private event. Fixed at creation.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "recurrence" : { "$ref" : "#/components/schemas/Recurrence", "description" : "The recurrence rule; absent for a one-off event." }, "responsibleUserIds" : { "description" : "Members responsible for the event; they may edit it.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "start" : { "description" : "Start of the event (of the first occurrence for a series), in `timeZone`.", "format" : "date-time", "type" : "string" }, "tenantId" : { "description" : "Id of the tenant the event belongs to.", "format" : "uuid", "type" : "string" }, "timeZone" : { "description" : "IANA time zone the event is scheduled in, e.g. `Europe/Berlin`.", "type" : "string" }, "title" : { "description" : "Title of the event.", "type" : "string" }, "updatedAt" : { "description" : "When the event was last changed.", "format" : "date-time", "type" : "string" }, "waitingListDisabled" : { "description" : "Whether the waiting list is switched off once `maxParticipants` is reached.", "type" : "boolean" } }, "required" : [ "allDay", "areaIds", "cancelled", "commitmentOptions", "createdBy", "end", "eventId", "instanceOverrides", "isPrivate", "privateInviteeIds", "responsibleUserIds", "start", "tenantId", "timeZone", "title", "updatedAt", "waitingListDisabled" ], "type" : "object" }, "FieldError" : { "properties" : { "field" : { "type" : "string" }, "message" : { "type" : "string" } }, "required" : [ "field", "message" ], "type" : "object" }, "FreeTextAnswer" : { "description" : "An answer to a free-text question. `type: FREE_TEXT`.", "properties" : { "answeredAt" : { "description" : "When the answer was first given.", "format" : "date-time", "type" : "string" }, "answerer" : { "$ref" : "#/components/schemas/Answerer", "description" : "Who answered; absent when the survey hides the answerers." }, "revisedAt" : { "description" : "When the answer was last changed.", "format" : "date-time", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `FREE_TEXT`.", "enum" : [ "FREE_TEXT" ], "type" : "string" }, "value" : { "description" : "The answer.", "type" : "string" } }, "required" : [ "answeredAt", "type", "value" ], "type" : "object" }, "FreeTextAnswerInput" : { "description" : "An answer to a free-text question. `type: FREE_TEXT`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `FREE_TEXT`.", "enum" : [ "FREE_TEXT" ], "type" : "string" }, "value" : { "description" : "The answer; must not be blank and must respect the question's length bounds.", "maxLength" : 20000, "minLength" : 1, "type" : "string" } }, "required" : [ "type", "value" ], "type" : "object" }, "FreeTextQuestion" : { "description" : "A question answered with free text. `type: FREE_TEXT`.", "properties" : { "description" : { "description" : "Longer explanation shown with the question.", "type" : "string" }, "maxTextLength" : { "description" : "Longest accepted answer.", "format" : "int32", "type" : "integer" }, "minTextLength" : { "description" : "Shortest accepted answer.", "format" : "int32", "type" : "integer" }, "questionId" : { "description" : "Id of the question.", "format" : "uuid", "type" : "string" }, "questionText" : { "description" : "The question itself.", "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `FREE_TEXT`.", "enum" : [ "FREE_TEXT" ], "type" : "string" } }, "required" : [ "questionId", "questionText", "required", "type" ], "type" : "object" }, "FreeTextQuestionInput" : { "description" : "A question answered with free text. `type: FREE_TEXT`.", "properties" : { "description" : { "description" : "Longer explanation shown with the question; must not be blank when present.", "maxLength" : 2000, "type" : "string" }, "maxTextLength" : { "description" : "Longest accepted answer; must be greater than zero and not below `minTextLength`.", "format" : "int32", "maximum" : 20000, "minimum" : 0, "type" : "integer" }, "minTextLength" : { "description" : "Shortest accepted answer.", "format" : "int32", "maximum" : 20000, "minimum" : 0, "type" : "integer" }, "questionText" : { "description" : "The question itself; must not be blank.", "maxLength" : 500, "minLength" : 1, "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered. Defaults to `false`.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `FREE_TEXT`.", "enum" : [ "FREE_TEXT" ], "type" : "string" } }, "required" : [ "questionText", "type" ], "type" : "object" }, "FreeTextResult" : { "description" : "Aggregated answers of a free-text question. `type: FREE_TEXT`.", "properties" : { "resultCount" : { "description" : "How many answers were counted.", "format" : "int32", "type" : "integer" }, "textCount" : { "additionalProperties" : { "format" : "int32", "type" : "integer" }, "description" : "How often each distinct text was given.", "type" : "object" }, "type" : { "description" : "Discriminator of the union; always `FREE_TEXT`.", "enum" : [ "FREE_TEXT" ], "type" : "string" } }, "required" : [ "resultCount", "textCount", "type" ], "type" : "object" }, "GuestAnswerer" : { "description" : "A member answering for a guest they brought. `type: GUEST`.", "properties" : { "guestId" : { "description" : "The guest the answer is for.", "format" : "uuid", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `GUEST`.", "enum" : [ "GUEST" ], "type" : "string" }, "userId" : { "description" : "The member who answered.", "format" : "uuid", "type" : "string" } }, "required" : [ "guestId", "type", "userId" ], "type" : "object" }, "InstanceOverride" : { "description" : "An occurrence of a recurring event that deviates from the series.", "properties" : { "cancellationReason" : { "description" : "Why this occurrence was cancelled.", "type" : "string" }, "cancelled" : { "description" : "Whether this occurrence is cancelled.", "type" : "boolean" }, "deleted" : { "description" : "Whether this occurrence was removed from the series.", "type" : "boolean" }, "end" : { "description" : "The moved end, when the occurrence was moved.", "format" : "date-time", "type" : "string" }, "instanceId" : { "description" : "Unix epoch seconds of the occurrence's original start — the id to address it with.", "format" : "int64", "type" : "integer" }, "originalStart" : { "description" : "The occurrence's original start, as computed from the series.", "format" : "date-time", "type" : "string" }, "start" : { "description" : "The moved start, when the occurrence was moved.", "format" : "date-time", "type" : "string" }, "title" : { "description" : "The overridden title of this occurrence.", "type" : "string" } }, "required" : [ "cancelled", "deleted", "instanceId", "originalStart" ], "type" : "object" }, "Invitation" : { "description" : "The result of an invitation.", "properties" : { "email" : { "description" : "The normalised address the invitation was sent to.", "type" : "string" }, "status" : { "description" : "Always `invited`.", "type" : "string" }, "userId" : { "description" : "Id the invited person will have as a member.", "format" : "uuid", "type" : "string" } }, "required" : [ "email", "status", "userId" ], "type" : "object" }, "InviteMemberRequest" : { "description" : "Who to invite, and in which language the invitation e-mail is written.", "properties" : { "email" : { "description" : "E-mail address to invite; trimmed and lower-cased before it is used.", "maxLength" : 254, "minLength" : 3, "type" : "string" }, "language" : { "description" : "Language of the invitation e-mail, e.g. `de` or `de-AT`. Defaults to the tenant's language.", "maxLength" : 8, "pattern" : "^[a-z]{2}(-[A-Z]{2})?$", "type" : "string" } }, "required" : [ "email" ], "type" : "object" }, "Location" : { "description" : "Where the event takes place. Every part is optional; nothing is geocoded on the server.", "properties" : { "address" : { "$ref" : "#/components/schemas/Address", "description" : "Structured address." }, "formattedAddress" : { "description" : "One-line address as it should be shown.", "maxLength" : 500, "type" : "string" }, "name" : { "description" : "Display name of the venue.", "maxLength" : 200, "type" : "string" }, "placeId" : { "description" : "Opaque place identifier of the map provider the address came from.", "maxLength" : 300, "type" : "string" }, "position" : { "$ref" : "#/components/schemas/Position", "description" : "Coordinates of the venue." } }, "type" : "object" }, "Member" : { "description" : "A member of a tenant.", "properties" : { "email" : { "description" : "E-mail address; only present when the token's owner administrates the tenant.", "type" : "string" }, "firstName" : { "description" : "First name.", "type" : "string" }, "isAdmin" : { "description" : "Whether the member administrates the tenant.", "type" : "boolean" }, "joinedAt" : { "description" : "When the invitation was accepted; absent while the member is still invited.", "format" : "date-time", "type" : "string" }, "lastName" : { "description" : "Last name.", "type" : "string" }, "profileImageUrl" : { "description" : "URL of the profile picture.", "type" : "string" }, "status" : { "$ref" : "#/components/schemas/MemberStatus", "description" : "Where the member stands between invitation and cancellation." }, "userId" : { "description" : "Id of the member.", "format" : "uuid", "type" : "string" } }, "required" : [ "firstName", "isAdmin", "lastName", "status", "userId" ], "type" : "object" }, "MemberAnswer" : { "description" : "An answer to a member question. `type: MEMBER`.", "properties" : { "answeredAt" : { "description" : "When the answer was first given.", "format" : "date-time", "type" : "string" }, "answerer" : { "$ref" : "#/components/schemas/Answerer", "description" : "Who answered; absent when the survey hides the answerers." }, "customMemberIds" : { "description" : "Members the answer added itself.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "memberIds" : { "description" : "The picked members.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "revisedAt" : { "description" : "When the answer was last changed.", "format" : "date-time", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `MEMBER`.", "enum" : [ "MEMBER" ], "type" : "string" } }, "required" : [ "answeredAt", "customMemberIds", "memberIds", "type" ], "type" : "object" }, "MemberAnswerInput" : { "description" : "An answer to a member question. At least one of `memberIds` and `customMemberIds` must be non-empty.", "properties" : { "customMemberIds" : { "description" : "Members of your own; only when the question allows them, and never one the question already offers.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 500, "type" : "array" }, "memberIds" : { "description" : "Ids of the picked members; each must be offered by the question unless it offers all members.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 500, "type" : "array" }, "type" : { "description" : "Discriminator of the union; always `MEMBER`.", "enum" : [ "MEMBER" ], "type" : "string" } }, "required" : [ "type" ], "type" : "object" }, "MemberAnswerer" : { "description" : "A member of the tenant answering for themselves. `type: MEMBER`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `MEMBER`.", "enum" : [ "MEMBER" ], "type" : "string" }, "userId" : { "description" : "The member.", "format" : "uuid", "type" : "string" } }, "required" : [ "type", "userId" ], "type" : "object" }, "MemberQuestion" : { "description" : "A question answered by picking members. `type: MEMBER`.", "properties" : { "allMembers" : { "description" : "Whether every member of the tenant may be picked.", "type" : "boolean" }, "allowCustomMember" : { "description" : "Whether an answer may add members of its own.", "type" : "boolean" }, "allowMultipleCustomMembers" : { "description" : "Whether an answer may add more than one member of its own.", "type" : "boolean" }, "description" : { "description" : "Longer explanation shown with the question.", "type" : "string" }, "maxChoices" : { "description" : "How many members an answer may pick at most.", "format" : "int32", "type" : "integer" }, "memberIds" : { "description" : "The members to pick from; empty when `allMembers` is set.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "questionId" : { "description" : "Id of the question.", "format" : "uuid", "type" : "string" }, "questionText" : { "description" : "The question itself.", "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered.", "type" : "boolean" }, "singleChoice" : { "description" : "Whether an answer may pick exactly one member.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `MEMBER`.", "enum" : [ "MEMBER" ], "type" : "string" } }, "required" : [ "allMembers", "allowCustomMember", "allowMultipleCustomMembers", "memberIds", "questionId", "questionText", "required", "singleChoice", "type" ], "type" : "object" }, "MemberQuestionInput" : { "description" : "A question answered by picking members. `type: MEMBER`.", "properties" : { "allMembers" : { "description" : "Offer every member of the tenant; excludes `memberIds`, `allowCustomMember` and custom members.", "type" : "boolean" }, "allowCustomMember" : { "description" : "Let an answer add members of its own.", "type" : "boolean" }, "allowMultipleCustomMembers" : { "description" : "Let an answer add more than one member of its own; not allowed together with `singleChoice`.", "type" : "boolean" }, "description" : { "description" : "Longer explanation shown with the question; must not be blank when present.", "maxLength" : 2000, "type" : "string" }, "maxChoices" : { "description" : "How many members an answer may pick at most; not allowed together with `singleChoice`.", "format" : "int32", "maximum" : 100, "minimum" : 1, "type" : "integer" }, "memberIds" : { "description" : "The members to pick from; must be empty when `allMembers` is set, required otherwise.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 500, "type" : "array" }, "questionText" : { "description" : "The question itself; must not be blank.", "maxLength" : 500, "minLength" : 1, "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered. Defaults to `false`.", "type" : "boolean" }, "singleChoice" : { "description" : "Accept exactly one member per answer; not allowed together with `maxChoices`.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `MEMBER`.", "enum" : [ "MEMBER" ], "type" : "string" } }, "required" : [ "questionText", "type" ], "type" : "object" }, "MemberResult" : { "description" : "Aggregated answers of a member question. `type: MEMBER`.", "properties" : { "customMemberCount" : { "additionalProperties" : { "format" : "int32", "type" : "integer" }, "description" : "How often each member the answers added themselves was picked, by user id.", "type" : "object" }, "memberCount" : { "additionalProperties" : { "format" : "int32", "type" : "integer" }, "description" : "How often each member was picked, by user id.", "type" : "object" }, "resultCount" : { "description" : "How many answers were counted.", "format" : "int32", "type" : "integer" }, "type" : { "description" : "Discriminator of the union; always `MEMBER`.", "enum" : [ "MEMBER" ], "type" : "string" } }, "required" : [ "customMemberCount", "memberCount", "resultCount", "type" ], "type" : "object" }, "MemberStatus" : { "enum" : [ "INVITED", "ACTIVE", "INACTIVE", "CANCELLED", "QUARANTINED", "UNKNOWN" ], "type" : "string" }, "Message" : { "description" : "A message of a conversation. Attachments (images, documents, audio, the location of a location message) are not part of the public API yet — such a message is reported with its `kind` and its text only.", "properties" : { "createdAt" : { "description" : "When the message was posted.", "format" : "date-time", "type" : "string" }, "createdBy" : { "description" : "The member who wrote the message.", "format" : "uuid", "type" : "string" }, "deleted" : { "description" : "Whether the message was deleted; a deleted message keeps its place with an empty body.", "type" : "boolean" }, "edited" : { "description" : "Whether the message was edited after it was posted.", "type" : "boolean" }, "editedAt" : { "description" : "When the message was last edited.", "format" : "date-time", "type" : "string" }, "html" : { "description" : "Rich-text body, as it was stored after sanitising.", "type" : "string" }, "kind" : { "$ref" : "#/components/schemas/MessageKind", "description" : "What the message carries. Only `TEXT` messages can be written through this API." }, "likeCount" : { "description" : "How many members liked the message.", "format" : "int32", "type" : "integer" }, "likedByMe" : { "description" : "Whether the token's owner liked the message.", "type" : "boolean" }, "mentionIds" : { "description" : "The members mentioned in the message.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "messageId" : { "description" : "Id of the message.", "format" : "uuid", "type" : "string" }, "replyToMessageId" : { "description" : "The message this one replies to.", "format" : "uuid", "type" : "string" }, "surveyId" : { "description" : "`SURVEY` only: the survey the message announces.", "format" : "uuid", "type" : "string" }, "text" : { "description" : "Plain-text body; empty for a deleted message.", "type" : "string" } }, "required" : [ "createdAt", "createdBy", "deleted", "edited", "kind", "likeCount", "likedByMe", "mentionIds", "messageId", "text" ], "type" : "object" }, "MessageKind" : { "enum" : [ "TEXT", "IMAGE", "DOCUMENT", "LOCATION", "AUDIO", "SURVEY" ], "type" : "string" }, "MoveQuestionRequest" : { "description" : "Where the question should sit.", "properties" : { "index" : { "description" : "Its new position, counted from zero; at most the number of questions minus one.", "format" : "int32", "maximum" : 100, "minimum" : 0, "type" : "integer" } }, "required" : [ "index" ], "type" : "object" }, "MySurveyAnswers" : { "description" : "The answers the token's owner gave.", "properties" : { "answers" : { "description" : "One entry per answered question, in the order the questions are answered.", "items" : { "$ref" : "#/components/schemas/QuestionAnswer" }, "type" : "array" }, "surveyId" : { "description" : "Id of the survey.", "format" : "uuid", "type" : "string" } }, "required" : [ "answers", "surveyId" ], "type" : "object" }, "NewMessage" : { "description" : "The first message of a new conversation.", "properties" : { "html" : { "description" : "Rich-text body. Sanitised on write: only a safe subset of HTML survives.", "maxLength" : 50000, "type" : "string" }, "text" : { "description" : "Plain-text body; must not be blank.", "maxLength" : 20000, "minLength" : 1, "type" : "string" } }, "required" : [ "text" ], "type" : "object" }, "PageOfAreaGroup" : { "properties" : { "items" : { "items" : { "$ref" : "#/components/schemas/AreaGroup" }, "type" : "array" }, "nextCursor" : { "description" : "Absent on the last page; pass as `cursor` to fetch the next page.", "type" : "string" } }, "required" : [ "items" ], "type" : "object" }, "PageOfAreaSummary" : { "properties" : { "items" : { "items" : { "$ref" : "#/components/schemas/AreaSummary" }, "type" : "array" }, "nextCursor" : { "description" : "Absent on the last page; pass as `cursor` to fetch the next page.", "type" : "string" } }, "required" : [ "items" ], "type" : "object" }, "PageOfConversationSummary" : { "properties" : { "items" : { "items" : { "$ref" : "#/components/schemas/ConversationSummary" }, "type" : "array" }, "nextCursor" : { "description" : "Absent on the last page; pass as `cursor` to fetch the next page.", "type" : "string" } }, "required" : [ "items" ], "type" : "object" }, "PageOfEvent" : { "properties" : { "items" : { "items" : { "$ref" : "#/components/schemas/Event" }, "type" : "array" }, "nextCursor" : { "description" : "Absent on the last page; pass as `cursor` to fetch the next page.", "type" : "string" } }, "required" : [ "items" ], "type" : "object" }, "PageOfMember" : { "properties" : { "items" : { "items" : { "$ref" : "#/components/schemas/Member" }, "type" : "array" }, "nextCursor" : { "description" : "Absent on the last page; pass as `cursor` to fetch the next page.", "type" : "string" } }, "required" : [ "items" ], "type" : "object" }, "PageOfMessage" : { "properties" : { "items" : { "items" : { "$ref" : "#/components/schemas/Message" }, "type" : "array" }, "nextCursor" : { "description" : "Absent on the last page; pass as `cursor` to fetch the next page.", "type" : "string" } }, "required" : [ "items" ], "type" : "object" }, "PageOfRole" : { "properties" : { "items" : { "items" : { "$ref" : "#/components/schemas/Role" }, "type" : "array" }, "nextCursor" : { "description" : "Absent on the last page; pass as `cursor` to fetch the next page.", "type" : "string" } }, "required" : [ "items" ], "type" : "object" }, "PageOfSurvey" : { "properties" : { "items" : { "items" : { "$ref" : "#/components/schemas/Survey" }, "type" : "array" }, "nextCursor" : { "description" : "Absent on the last page; pass as `cursor` to fetch the next page.", "type" : "string" } }, "required" : [ "items" ], "type" : "object" }, "PatchEventRequest" : { "description" : "Changes to a calendar event (JSON Merge Patch): absent = unchanged, `null` = clear, a value = set. `recurrence`, `location` and `description` are replaced as a whole; `commitmentOptions` is merged field by field. The visibility of an event is fixed at creation, so `isPrivate`, `areaIds` and `privateInviteeIds` are not part of this body.", "properties" : { "allDay" : { "description" : "Whether the event covers whole days.", "type" : [ "boolean", "null" ] }, "commitmentOptions" : { "description" : "Merged field by field into the current RSVP behaviour.", "oneOf" : [ { "$ref" : "#/components/schemas/CommitmentOptionsPatch" }, { "type" : "null" } ] }, "description" : { "description" : "Replaces the description as a whole; `null` removes it.", "oneOf" : [ { "$ref" : "#/components/schemas/Description" }, { "type" : "null" } ] }, "end" : { "description" : "New end; must be after the effective start and cannot be cleared.", "format" : "date-time", "type" : [ "string", "null" ] }, "fromInstanceId" : { "description" : "Restricts the change to the occurrences from that instance on (splits the series); the instance id is the Unix epoch seconds of the occurrence's original start.", "format" : "int64", "type" : [ "integer", "null" ] }, "location" : { "description" : "Replaces the location as a whole; `null` removes it.", "oneOf" : [ { "$ref" : "#/components/schemas/Location" }, { "type" : "null" } ] }, "maxParticipants" : { "description" : "New maximum number of participants; must not be smaller than the effective minimum. `null` removes it.", "format" : "int32", "maximum" : 10000, "minimum" : 0, "type" : [ "integer", "null" ] }, "minParticipants" : { "description" : "New minimum number of participants; `null` removes it.", "format" : "int32", "maximum" : 10000, "minimum" : 0, "type" : [ "integer", "null" ] }, "recurrence" : { "description" : "Replaces the recurrence rule as a whole; `null` turns the series into a one-off event.", "oneOf" : [ { "$ref" : "#/components/schemas/RecurrenceInput" }, { "type" : "null" } ] }, "responsibleUserIds" : { "description" : "Replaces the responsible members; each must be an active member of `{tenantId}`. `null` clears the list.", "oneOf" : [ { "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 100, "type" : "array" }, { "type" : "null" } ] }, "start" : { "description" : "New start; cannot be cleared.", "format" : "date-time", "type" : [ "string", "null" ] }, "timeZone" : { "description" : "New IANA time zone; only together with `start` and `end`, and it cannot be cleared.", "maxLength" : 64, "minLength" : 1, "type" : [ "string", "null" ] }, "title" : { "description" : "New title; must not be blank and cannot be cleared.", "maxLength" : 500, "minLength" : 1, "type" : [ "string", "null" ] }, "waitingListDisabled" : { "description" : "Switch the waiting list off once `maxParticipants` is reached.", "type" : [ "boolean", "null" ] } }, "type" : "object" }, "PatchSurveyRequest" : { "description" : "Changes to a survey (JSON Merge Patch): absent = unchanged, `null` = clear, a value = set. Only the fields that actually change are written. The audience, the type and the questions are not part of this body.", "properties" : { "allowComments" : { "description" : "Whether members may discuss the survey; `null` resets it to `false`.", "type" : [ "boolean", "null" ] }, "allowRevisions" : { "description" : "Whether an answer may be changed or withdrawn; `null` resets it to `false`.", "type" : [ "boolean", "null" ] }, "answerVisibility" : { "description" : "Who may see the individual answers; `null` resets it to `NONE`.", "oneOf" : [ { "$ref" : "#/components/schemas/SurveyVisibility" }, { "type" : "null" } ] }, "answererVisibility" : { "description" : "Who may see who gave an answer; `null` resets it to `NONE`.", "oneOf" : [ { "$ref" : "#/components/schemas/SurveyVisibility" }, { "type" : "null" } ] }, "description" : { "description" : "New description; `null` removes it.", "maxLength" : 20000, "type" : [ "string", "null" ] }, "liveResultVisibility" : { "description" : "Who may see the results while the survey runs; `null` resets it to `NONE`.", "oneOf" : [ { "$ref" : "#/components/schemas/SurveyVisibility" }, { "type" : "null" } ] }, "resultVisibility" : { "description" : "Who may see the results once the survey is complete; `null` resets it to `NONE`.", "oneOf" : [ { "$ref" : "#/components/schemas/SurveyVisibility" }, { "type" : "null" } ] }, "schedule" : { "description" : "Replaces the schedule as a whole; `null` removes it and turns a scheduled survey back into a draft.", "oneOf" : [ { "$ref" : "#/components/schemas/SurveySchedule" }, { "type" : "null" } ] }, "title" : { "description" : "New title; `null` removes it.", "maxLength" : 200, "type" : [ "string", "null" ] } }, "type" : "object" }, "PersonalAccessTokenInfo" : { "properties" : { "expiresAt" : { "format" : "date-time", "type" : "string" }, "plan" : { "type" : "string" }, "scopes" : { "items" : { "type" : "string" }, "type" : "array" }, "tenantId" : { "format" : "uuid", "type" : "string" }, "tokenId" : { "format" : "uuid", "type" : "string" }, "tokenName" : { "type" : "string" }, "userId" : { "format" : "uuid", "type" : "string" } }, "required" : [ "plan", "scopes", "tenantId", "tokenId", "tokenName", "userId" ], "type" : "object" }, "Position" : { "description" : "WGS-84 coordinates of a location.", "properties" : { "latitude" : { "description" : "Latitude in degrees.", "format" : "double", "type" : "number" }, "longitude" : { "description" : "Longitude in degrees.", "format" : "double", "type" : "number" } }, "required" : [ "latitude", "longitude" ], "type" : "object" }, "PostMessageRequest" : { "description" : "A new message.", "properties" : { "html" : { "description" : "Rich-text body. Sanitised on write: only a safe subset of HTML survives.", "maxLength" : 50000, "type" : "string" }, "replyToMessageId" : { "description" : "The message this one replies to.", "format" : "uuid", "type" : "string" }, "text" : { "description" : "Plain-text body; must not be blank.", "maxLength" : 20000, "minLength" : 1, "type" : "string" } }, "required" : [ "text" ], "type" : "object" }, "PostedMessage" : { "description" : "The result of posting a message to a calendar-event occurrence or to a ride sharing.", "properties" : { "conversationCreated" : { "description" : "Whether this call created the conversation (the first message creates it on demand).", "type" : "boolean" }, "conversationId" : { "description" : "The conversation the message was posted to — existing or just created.", "format" : "uuid", "type" : "string" }, "message" : { "$ref" : "#/components/schemas/Message", "description" : "The message that was posted." } }, "required" : [ "conversationCreated", "conversationId", "message" ], "type" : "object" }, "Problem" : { "additionalProperties" : true, "description" : "RFC 9457 Problem Details. `code` is the stable identifier to branch on; `type` is its URI form, `title`/`detail` are human-readable, `instance` is the request path and `requestId` the `X-Request-Id` of the failed request. Depending on `code` further members are present (`errors`, `requiredPlan`, `currentPlan`, `requiredScope`, `tenantStatus`, `scope`, `retryAfterSeconds`).", "properties" : { "code" : { "description" : "Stable, machine-readable error code.", "enum" : [ "unauthenticated", "token_expired", "token_revoked", "tenant_mismatch", "tenant_unavailable", "plan_required", "insufficient_scope", "forbidden", "not_found", "validation_failed", "conflict", "rate_limited", "payload_too_large", "service_unavailable", "internal_error", "unsupported_media_type", "method_not_allowed" ], "type" : "string" }, "currentPlan" : { "description" : "`plan_required` only: the tenant's current plan (`FREE`, `PLUS`, `PRO`).", "type" : "string" }, "detail" : { "type" : "string" }, "errors" : { "description" : "`validation_failed` only: the offending fields.", "items" : { "$ref" : "#/components/schemas/FieldError" }, "type" : "array" }, "instance" : { "description" : "The path of the failed request.", "type" : "string" }, "requestId" : { "description" : "The `X-Request-Id` of the failed request — quote it when you contact us.", "type" : "string" }, "requiredPlan" : { "description" : "`plan_required` only: the plan the endpoint needs (`PLUS`, `PRO`).", "type" : "string" }, "requiredScope" : { "description" : "`insufficient_scope` only: the scope the endpoint needs.", "type" : "string" }, "retryAfterSeconds" : { "description" : "`rate_limited` only: seconds until the tightest window resets.", "format" : "int64", "type" : "integer" }, "scope" : { "description" : "`rate_limited` only: which budget was exhausted (`token`, `tenant`, `ip`).", "type" : "string" }, "status" : { "format" : "int32", "type" : "integer" }, "tenantStatus" : { "description" : "`tenant_unavailable` only: the tenant's status.", "type" : "string" }, "title" : { "type" : "string" }, "type" : { "description" : "`https://api.klubraum.com/problems/`", "format" : "uri", "type" : "string" } }, "required" : [ "type", "title", "status", "detail", "instance", "code", "requestId" ], "type" : "object" }, "PublicAnswerer" : { "description" : "Somebody outside the tenant answering a public survey. `type: PUBLIC`.", "properties" : { "answererId" : { "description" : "Opaque id of the anonymous answerer.", "format" : "uuid", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `PUBLIC`.", "enum" : [ "PUBLIC" ], "type" : "string" } }, "required" : [ "answererId", "type" ], "type" : "object" }, "Question" : { "discriminator" : { "mapping" : { "BOOLEAN" : "#/components/schemas/BooleanQuestion", "CHOICE" : "#/components/schemas/ChoiceQuestion", "FREE_TEXT" : "#/components/schemas/FreeTextQuestion", "MEMBER" : "#/components/schemas/MemberQuestion", "RATING" : "#/components/schemas/RatingQuestion", "SCHEDULING" : "#/components/schemas/SchedulingQuestion" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/BooleanQuestion" }, { "$ref" : "#/components/schemas/ChoiceQuestion" }, { "$ref" : "#/components/schemas/FreeTextQuestion" }, { "$ref" : "#/components/schemas/MemberQuestion" }, { "$ref" : "#/components/schemas/RatingQuestion" }, { "$ref" : "#/components/schemas/SchedulingQuestion" } ] }, "QuestionAnswer" : { "description" : "One answer of the token's owner.", "properties" : { "answer" : { "$ref" : "#/components/schemas/Answer", "description" : "The answer." }, "questionId" : { "description" : "Id of the question.", "format" : "uuid", "type" : "string" }, "questionText" : { "description" : "The question itself.", "type" : "string" } }, "required" : [ "answer", "questionId", "questionText" ], "type" : "object" }, "QuestionAnswers" : { "description" : "The individual answers of one question.", "properties" : { "answers" : { "description" : "The answers; `answerer` is only present when the survey shows who answered.", "items" : { "$ref" : "#/components/schemas/Answer" }, "type" : "array" }, "questionId" : { "description" : "Id of the question.", "format" : "uuid", "type" : "string" }, "questionText" : { "description" : "The question itself.", "type" : "string" } }, "required" : [ "answers", "questionId", "questionText" ], "type" : "object" }, "QuestionInput" : { "discriminator" : { "mapping" : { "BOOLEAN" : "#/components/schemas/BooleanQuestionInput", "CHOICE" : "#/components/schemas/ChoiceQuestionInput", "FREE_TEXT" : "#/components/schemas/FreeTextQuestionInput", "MEMBER" : "#/components/schemas/MemberQuestionInput", "RATING" : "#/components/schemas/RatingQuestionInput", "SCHEDULING" : "#/components/schemas/SchedulingQuestionInput" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/BooleanQuestionInput" }, { "$ref" : "#/components/schemas/ChoiceQuestionInput" }, { "$ref" : "#/components/schemas/FreeTextQuestionInput" }, { "$ref" : "#/components/schemas/MemberQuestionInput" }, { "$ref" : "#/components/schemas/RatingQuestionInput" }, { "$ref" : "#/components/schemas/SchedulingQuestionInput" } ] }, "QuestionResult" : { "description" : "The aggregated answers of one question.", "properties" : { "questionId" : { "description" : "Id of the question.", "format" : "uuid", "type" : "string" }, "questionText" : { "description" : "The question itself.", "type" : "string" }, "result" : { "$ref" : "#/components/schemas/SurveyResult", "description" : "The aggregate; the counts are zero while nobody has answered." } }, "required" : [ "questionId", "questionText", "result" ], "type" : "object" }, "RatingAnswer" : { "description" : "An answer to a rating question. `type: RATING`.", "properties" : { "answeredAt" : { "description" : "When the answer was first given.", "format" : "date-time", "type" : "string" }, "answerer" : { "$ref" : "#/components/schemas/Answerer", "description" : "Who answered; absent when the survey hides the answerers." }, "revisedAt" : { "description" : "When the answer was last changed.", "format" : "date-time", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `RATING`.", "enum" : [ "RATING" ], "type" : "string" }, "value" : { "description" : "The value on the scale.", "format" : "int32", "type" : "integer" } }, "required" : [ "answeredAt", "type", "value" ], "type" : "object" }, "RatingAnswerInput" : { "description" : "An answer to a rating question. `type: RATING`.", "properties" : { "type" : { "description" : "Discriminator of the union; always `RATING`.", "enum" : [ "RATING" ], "type" : "string" }, "value" : { "description" : "The value on the scale; between the question's `minValue` and `maxValue` and a multiple of its `stepSize`.", "format" : "int32", "type" : "integer" } }, "required" : [ "type", "value" ], "type" : "object" }, "RatingQuestion" : { "description" : "A question answered with a value on a scale. `type: RATING`.", "properties" : { "description" : { "description" : "Longer explanation shown with the question.", "type" : "string" }, "maxLabel" : { "description" : "Label of the highest value.", "type" : "string" }, "maxValue" : { "description" : "Highest value of the scale.", "format" : "int32", "type" : "integer" }, "minLabel" : { "description" : "Label of the lowest value.", "type" : "string" }, "minValue" : { "description" : "Lowest value of the scale.", "format" : "int32", "type" : "integer" }, "questionId" : { "description" : "Id of the question.", "format" : "uuid", "type" : "string" }, "questionText" : { "description" : "The question itself.", "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered.", "type" : "boolean" }, "stepSize" : { "description" : "Distance between two neighbouring values of the scale.", "format" : "int32", "type" : "integer" }, "style" : { "$ref" : "#/components/schemas/RatingStyle", "description" : "How the scale is drawn." }, "type" : { "description" : "Discriminator of the union; always `RATING`.", "enum" : [ "RATING" ], "type" : "string" } }, "required" : [ "maxValue", "minValue", "questionId", "questionText", "required", "stepSize", "style", "type" ], "type" : "object" }, "RatingQuestionInput" : { "description" : "A question answered with a value on a scale. `type: RATING`.", "properties" : { "description" : { "description" : "Longer explanation shown with the question; must not be blank when present.", "maxLength" : 2000, "type" : "string" }, "maxLabel" : { "description" : "Label of the highest value; only together with `minLabel`.", "maxLength" : 20, "type" : "string" }, "maxValue" : { "description" : "Highest value of the scale; must be greater than `minValue`.", "format" : "int32", "maximum" : 10000, "minimum" : -10000, "type" : "integer" }, "minLabel" : { "description" : "Label of the lowest value; only together with `maxLabel`.", "maxLength" : 20, "type" : "string" }, "minValue" : { "description" : "Lowest value of the scale.", "format" : "int32", "maximum" : 10000, "minimum" : -10000, "type" : "integer" }, "questionText" : { "description" : "The question itself; must not be blank.", "maxLength" : 500, "minLength" : 1, "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered. Defaults to `false`.", "type" : "boolean" }, "stepSize" : { "description" : "Distance between two neighbouring values; `maxValue - minValue` must be a multiple of it. Defaults to `1`.", "format" : "int32", "maximum" : 10000, "minimum" : 1, "type" : "integer" }, "style" : { "$ref" : "#/components/schemas/RatingStyle", "description" : "How the scale is drawn. Defaults to `STAR`." }, "type" : { "description" : "Discriminator of the union; always `RATING`.", "enum" : [ "RATING" ], "type" : "string" } }, "required" : [ "maxValue", "minValue", "questionText", "type" ], "type" : "object" }, "RatingResult" : { "description" : "Aggregated answers of a rating question. `type: RATING`.", "properties" : { "ratingCount" : { "additionalProperties" : { "format" : "int32", "type" : "integer" }, "description" : "How often each value of the scale was given, by value.", "type" : "object" }, "resultCount" : { "description" : "How many answers were counted.", "format" : "int32", "type" : "integer" }, "type" : { "description" : "Discriminator of the union; always `RATING`.", "enum" : [ "RATING" ], "type" : "string" } }, "required" : [ "ratingCount", "resultCount", "type" ], "type" : "object" }, "RatingStyle" : { "enum" : [ "STAR", "HEART", "SMILEY", "NUMBER" ], "type" : "string" }, "Recurrence" : { "description" : "The recurrence rule of a series.", "properties" : { "bySetPos" : { "description" : "Which occurrence of `byWeekday` in the month (`1`–`4`, or `-1` for the last one).", "items" : { "format" : "int32", "type" : "integer" }, "type" : "array" }, "byWeekday" : { "description" : "The weekdays the series repeats on.", "items" : { "$ref" : "#/components/schemas/Weekday" }, "type" : "array" }, "count" : { "description" : "Number of occurrences of an imported series. Informational: only the iCal export honours it, and it cannot be set through this API.", "format" : "int32", "type" : "integer" }, "frequency" : { "$ref" : "#/components/schemas/RecurrenceFrequency", "description" : "How the series repeats." }, "interval" : { "description" : "Repeat every n periods.", "format" : "int32", "type" : "integer" }, "start" : { "description" : "First occurrence of the series.", "format" : "date-time", "type" : "string" }, "until" : { "description" : "Last possible occurrence; absent when the series never ends.", "format" : "date-time", "type" : "string" } }, "required" : [ "frequency", "interval", "start" ], "type" : "object" }, "RecurrenceFrequency" : { "enum" : [ "DAILY", "WEEKLY", "MONTHLY", "YEARLY" ], "type" : "string" }, "RecurrenceInput" : { "description" : "The recurrence rule of a series. Only the grammar the Klubraum app can render is accepted — see the \"Create a calendar event\" description for the table of supported combinations.", "properties" : { "bySetPos" : { "description" : "`MONTHLY` only: which occurrence of `byWeekday` in the month — `1`–`4` or `-1` for the last one.", "items" : { "format" : "int32", "type" : "integer" }, "maxItems" : 1, "minItems" : 1, "type" : "array" }, "byWeekday" : { "description" : "`WEEKLY`: the weekdays the series repeats on (required, unique). `MONTHLY`: exactly one weekday.", "items" : { "$ref" : "#/components/schemas/Weekday" }, "maxItems" : 7, "minItems" : 1, "type" : "array" }, "frequency" : { "$ref" : "#/components/schemas/RecurrenceFrequency", "description" : "How the series repeats." }, "interval" : { "description" : "Repeat every n periods. `MONTHLY` supports only `1`.", "format" : "int32", "maximum" : 100, "minimum" : 1, "type" : "integer" }, "start" : { "description" : "First occurrence of the series. Defaults to the event's `start` (create) or to the current rule's start.", "format" : "date-time", "type" : "string" }, "until" : { "description" : "Last possible occurrence. Must be after `start` and at most 50 years later. Absent = the series never ends.", "format" : "date-time", "type" : "string" } }, "required" : [ "frequency", "interval" ], "type" : "object" }, "RideSharingSummary" : { "description" : "A ride sharing offered for one occurrence of a calendar event.", "properties" : { "cancelled" : { "description" : "Whether the ride was cancelled; a cancelled ride stays visible with its passengers.", "type" : "boolean" }, "conversationId" : { "description" : "The ride's conversation, once a first message has been posted to it.", "format" : "uuid", "type" : "string" }, "departure" : { "description" : "When the ride departs.", "format" : "date-time", "type" : "string" }, "driverId" : { "description" : "The member who drives.", "format" : "uuid", "type" : "string" }, "passengerCount" : { "description" : "How many passengers are booked so far.", "format" : "int32", "type" : "integer" }, "rideSharingId" : { "description" : "Id of the ride sharing — address it with `POST /ride-sharings/{rideSharingId}/messages`.", "format" : "uuid", "type" : "string" }, "seats" : { "description" : "How many seats the driver offers.", "format" : "int32", "type" : "integer" } }, "required" : [ "cancelled", "departure", "driverId", "passengerCount", "rideSharingId", "seats" ], "type" : "object" }, "Role" : { "description" : "A role of a tenant.", "properties" : { "createdBy" : { "description" : "The member who created the role.", "format" : "uuid", "type" : "string" }, "deleted" : { "description" : "Whether the role is deleted. A deleted role is not part of any list and cannot be renamed, re-described or assigned; `POST /v1/tenants/{tenantId}/roles/{roleId}/undelete` brings it back.", "type" : "boolean" }, "description" : { "description" : "Description of the role; absent when it has none.", "type" : "string" }, "name" : { "description" : "Name of the role. Unique among the tenant's live roles, compared case-insensitively.", "type" : "string" }, "roleId" : { "description" : "Id of the role.", "format" : "uuid", "type" : "string" }, "updatedAt" : { "description" : "When the role was last changed.", "format" : "date-time", "type" : "string" }, "updatedBy" : { "description" : "The member who last changed the role; absent while it is unchanged since its creation.", "format" : "uuid", "type" : "string" } }, "required" : [ "createdBy", "deleted", "name", "roleId", "updatedAt" ], "type" : "object" }, "SchedulingAnswer" : { "description" : "An answer to a scheduling question. `type: SCHEDULING`.", "properties" : { "answeredAt" : { "description" : "When the answer was first given.", "format" : "date-time", "type" : "string" }, "answerer" : { "$ref" : "#/components/schemas/Answerer", "description" : "Who answered; absent when the survey hides the answerers." }, "choiceIds" : { "description" : "The picked choices.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "customChoices" : { "description" : "Dates/times the answer added itself.", "items" : { "$ref" : "#/components/schemas/CustomSchedulingAnswer" }, "type" : "array" }, "revisedAt" : { "description" : "When the answer was last changed.", "format" : "date-time", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `SCHEDULING`.", "enum" : [ "SCHEDULING" ], "type" : "string" } }, "required" : [ "answeredAt", "choiceIds", "customChoices", "type" ], "type" : "object" }, "SchedulingAnswerInput" : { "description" : "An answer to a scheduling question. At least one of `choiceIds` and `customChoices` must be non-empty.", "properties" : { "choiceIds" : { "description" : "Ids of the picked choices; each must be a choice of the question.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 100, "type" : "array" }, "customChoices" : { "description" : "Dates/times of your own; only the kinds the question's `customChoiceSettings` enable.", "items" : { "$ref" : "#/components/schemas/CustomSchedulingAnswer" }, "maxItems" : 100, "type" : "array" }, "type" : { "description" : "Discriminator of the union; always `SCHEDULING`.", "enum" : [ "SCHEDULING" ], "type" : "string" } }, "required" : [ "type" ], "type" : "object" }, "SchedulingChoice" : { "discriminator" : { "mapping" : { "DATE" : "#/components/schemas/DateChoice", "DATE_RANGE" : "#/components/schemas/DateRangeChoice", "DATE_TIME" : "#/components/schemas/DateTimeChoice", "DATE_TIME_RANGE" : "#/components/schemas/DateTimeRangeChoice", "TIME" : "#/components/schemas/TimeChoice", "TIME_RANGE" : "#/components/schemas/TimeRangeChoice" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/DateChoice" }, { "$ref" : "#/components/schemas/TimeChoice" }, { "$ref" : "#/components/schemas/DateTimeChoice" }, { "$ref" : "#/components/schemas/DateRangeChoice" }, { "$ref" : "#/components/schemas/TimeRangeChoice" }, { "$ref" : "#/components/schemas/DateTimeRangeChoice" } ] }, "SchedulingChoiceInput" : { "discriminator" : { "mapping" : { "DATE" : "#/components/schemas/DateChoiceInput", "DATE_RANGE" : "#/components/schemas/DateRangeChoiceInput", "DATE_TIME" : "#/components/schemas/DateTimeChoiceInput", "DATE_TIME_RANGE" : "#/components/schemas/DateTimeRangeChoiceInput", "TIME" : "#/components/schemas/TimeChoiceInput", "TIME_RANGE" : "#/components/schemas/TimeRangeChoiceInput" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/DateChoiceInput" }, { "$ref" : "#/components/schemas/TimeChoiceInput" }, { "$ref" : "#/components/schemas/DateTimeChoiceInput" }, { "$ref" : "#/components/schemas/DateRangeChoiceInput" }, { "$ref" : "#/components/schemas/TimeRangeChoiceInput" }, { "$ref" : "#/components/schemas/DateTimeRangeChoiceInput" } ] }, "SchedulingQuestion" : { "description" : "A question answered by picking dates or times. `type: SCHEDULING`.", "properties" : { "allowCustomChoice" : { "description" : "Whether an answer may add dates/times of its own.", "type" : "boolean" }, "choices" : { "description" : "The dates/times to pick from.", "items" : { "$ref" : "#/components/schemas/SchedulingChoice" }, "type" : "array" }, "customChoiceSettings" : { "$ref" : "#/components/schemas/CustomChoiceSettings", "description" : "What kinds of date/time an answer may add." }, "description" : { "description" : "Longer explanation shown with the question.", "type" : "string" }, "maxChoices" : { "description" : "How many choices an answer may pick at most.", "format" : "int32", "type" : "integer" }, "questionId" : { "description" : "Id of the question.", "format" : "uuid", "type" : "string" }, "questionText" : { "description" : "The question itself.", "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered.", "type" : "boolean" }, "singleChoice" : { "description" : "Whether an answer may pick exactly one choice.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `SCHEDULING`.", "enum" : [ "SCHEDULING" ], "type" : "string" } }, "required" : [ "allowCustomChoice", "choices", "customChoiceSettings", "questionId", "questionText", "required", "singleChoice", "type" ], "type" : "object" }, "SchedulingQuestionInput" : { "description" : "A question answered by picking dates or times. `type: SCHEDULING`.", "properties" : { "allowCustomChoice" : { "description" : "Let an answer add dates/times of its own; then `customChoiceSettings` must enable at least one kind.", "type" : "boolean" }, "choices" : { "description" : "The dates/times to pick from. Required unless `allowCustomChoice` is set.", "items" : { "$ref" : "#/components/schemas/SchedulingChoiceInput" }, "maxItems" : 100, "type" : "array" }, "customChoiceSettings" : { "$ref" : "#/components/schemas/CustomChoiceSettingsInput", "description" : "What kinds of date/time an answer may add." }, "description" : { "description" : "Longer explanation shown with the question; must not be blank when present.", "maxLength" : 2000, "type" : "string" }, "maxChoices" : { "description" : "How many choices an answer may pick at most; not allowed together with `singleChoice`.", "format" : "int32", "maximum" : 100, "minimum" : 1, "type" : "integer" }, "questionText" : { "description" : "The question itself; must not be blank.", "maxLength" : 500, "minLength" : 1, "type" : "string" }, "required" : { "description" : "Whether an answer is required before later questions may be answered. Defaults to `false`.", "type" : "boolean" }, "singleChoice" : { "description" : "Accept exactly one choice per answer; not allowed together with `maxChoices`.", "type" : "boolean" }, "type" : { "description" : "Discriminator of the union; always `SCHEDULING`.", "enum" : [ "SCHEDULING" ], "type" : "string" } }, "required" : [ "questionText", "type" ], "type" : "object" }, "SchedulingResult" : { "description" : "Aggregated answers of a scheduling question. `type: SCHEDULING`.", "properties" : { "choiceCount" : { "additionalProperties" : { "format" : "int32", "type" : "integer" }, "description" : "How often each choice was picked, by choice id.", "type" : "object" }, "customChoiceCount" : { "additionalProperties" : { "format" : "int32", "type" : "integer" }, "description" : "How often each date/time the answers added themselves was picked, by its rendered value.", "type" : "object" }, "resultCount" : { "description" : "How many answers were counted.", "format" : "int32", "type" : "integer" }, "type" : { "description" : "Discriminator of the union; always `SCHEDULING`.", "enum" : [ "SCHEDULING" ], "type" : "string" } }, "required" : [ "choiceCount", "customChoiceCount", "resultCount", "type" ], "type" : "object" }, "SetAreaCapabilityRequest" : { "description" : "The complete subject set of one capability. An empty list reverts the capability to its default.", "properties" : { "subjects" : { "description" : "Who the capability is granted to; duplicates are removed.", "items" : { "$ref" : "#/components/schemas/CapabilitySubject" }, "maxItems" : 100, "type" : "array" } }, "required" : [ "subjects" ], "type" : "object" }, "SetAreaColorRequest" : { "description" : "The new colour of an area. Use `DELETE` to remove it.", "properties" : { "color" : { "description" : "Colour as `#RRGGBB` or `#AARRGGBB`.", "pattern" : "^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$", "type" : "string" } }, "required" : [ "color" ], "type" : "object" }, "SetAreaDescriptionRequest" : { "description" : "The new description of an area. Use `DELETE` to remove it.", "properties" : { "description" : { "description" : "Description of the area; must not be blank.", "maxLength" : 200, "minLength" : 1, "type" : "string" } }, "required" : [ "description" ], "type" : "object" }, "SetAreaGroupColorRequest" : { "description" : "The new colour of an area group. Use `DELETE` to remove it.", "properties" : { "color" : { "description" : "Colour as `#RRGGBB` or `#AARRGGBB`.", "pattern" : "^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$", "type" : "string" } }, "required" : [ "color" ], "type" : "object" }, "SetAreaGroupDescriptionRequest" : { "description" : "The new description of an area group. Use `DELETE` to remove it.", "properties" : { "description" : { "description" : "Description of the area group; must not be blank.", "maxLength" : 200, "minLength" : 1, "type" : "string" } }, "required" : [ "description" ], "type" : "object" }, "SetAreaGroupIconRequest" : { "description" : "The new icon of an area group. Use `DELETE` to remove it.", "properties" : { "icon" : { "description" : "One of the icon names listed in the description of \"Create an area group\".", "maxLength" : 16, "minLength" : 3, "type" : "string" } }, "required" : [ "icon" ], "type" : "object" }, "SetAreaGroupNameRequest" : { "description" : "The new name of an area group.", "properties" : { "name" : { "description" : "Name of the area group; must not be blank.", "maxLength" : 75, "minLength" : 1, "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "SetAreaIconRequest" : { "description" : "The new icon of an area. Use `DELETE` to remove it.", "properties" : { "icon" : { "description" : "One of the icon names listed in the description of \"Create an area\".", "maxLength" : 16, "minLength" : 3, "type" : "string" } }, "required" : [ "icon" ], "type" : "object" }, "SetAreaNameRequest" : { "description" : "The new name of an area.", "properties" : { "name" : { "description" : "Name of the area; must not be blank.", "maxLength" : 75, "minLength" : 1, "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "SetAreaPrivacyRequest" : { "description" : "Whether the area is private.", "properties" : { "isPrivate" : { "description" : "`true` restricts the area to its own members.", "type" : "boolean" } }, "required" : [ "isPrivate" ], "type" : "object" }, "SetConversationAreasRequest" : { "description" : "The areas a standalone conversation is visible in — the list REPLACES the current one.", "properties" : { "areaIds" : { "description" : "Every id must be an area of `{tenantId}` that is not archived. An empty list makes the conversation visible to the whole tenant.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 100, "type" : "array" } }, "required" : [ "areaIds" ], "type" : "object" }, "SetMemberRolesRequest" : { "description" : "The complete set of roles a member holds.", "properties" : { "roleIds" : { "description" : "The roles the member holds afterwards; roles that are not listed are removed. Duplicates are ignored, and an empty list removes every role. Every id must be a live role of this tenant — the offending entry is reported as `roleIds[0]` and so on.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 100, "type" : "array" } }, "required" : [ "roleIds" ], "type" : "object" }, "SetRoleDescriptionRequest" : { "description" : "A new description for a role.", "properties" : { "description" : { "description" : "The new description; trimmed before it is stored, and it must not be blank — use `DELETE` to clear it.", "maxLength" : 2048, "minLength" : 1, "type" : "string" } }, "required" : [ "description" ], "type" : "object" }, "SetRoleNameRequest" : { "description" : "A new name for a role.", "properties" : { "name" : { "description" : "The new name. Surrounding whitespace is removed before the name is checked and stored, so `pattern` describes the trimmed value. It must not collide with another live role of this tenant (compared case-insensitively, after trimming) — keeping the role's own name is always allowed.", "maxLength" : 200, "minLength" : 1, "pattern" : "^[A-Za-z0-9À-ÿ'-.,;:*#+/%!\"$&‘’][ A-Za-z0-9À-ÿ'-.,;:*#+/%!\"$&‘’]*$", "type" : "string" } }, "required" : [ "name" ], "type" : "object" }, "SetSubjectRequest" : { "description" : "The new subject of a conversation.", "properties" : { "subject" : { "description" : "Subject of the conversation; must not be blank.", "maxLength" : 50, "minLength" : 1, "type" : "string" } }, "required" : [ "subject" ], "type" : "object" }, "Survey" : { "description" : "A survey or poll. Its audience (`context`) and its `type` are fixed at creation.", "properties" : { "collaboratorIds" : { "description" : "Members who may edit the survey alongside its creator.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "context" : { "$ref" : "#/components/schemas/SurveyContext", "description" : "Who the survey is for." }, "conversationId" : { "description" : "The conversation the survey is discussed in, when comments are enabled and one was started.", "format" : "uuid", "type" : "string" }, "createdBy" : { "description" : "The member who created the survey.", "format" : "uuid", "type" : "string" }, "description" : { "description" : "Longer description of the survey.", "type" : "string" }, "metadata" : { "$ref" : "#/components/schemas/SurveyMetadata", "description" : "Counters and timestamps." }, "questions" : { "description" : "The questions, in the order they are answered.", "items" : { "$ref" : "#/components/schemas/Question" }, "type" : "array" }, "schedule" : { "$ref" : "#/components/schemas/SurveySchedule", "description" : "When the survey opens and closes." }, "settings" : { "$ref" : "#/components/schemas/SurveySettings", "description" : "How the survey behaves and who may see its data." }, "status" : { "$ref" : "#/components/schemas/SurveyStatus", "description" : "Lifecycle state of the survey." }, "surveyId" : { "description" : "Id of the survey.", "format" : "uuid", "type" : "string" }, "tenantId" : { "description" : "Id of the tenant the survey belongs to.", "format" : "uuid", "type" : "string" }, "title" : { "description" : "Title of the survey.", "type" : "string" }, "type" : { "$ref" : "#/components/schemas/SurveyType", "description" : "Whether this is a survey or a poll." } }, "required" : [ "collaboratorIds", "context", "createdBy", "metadata", "questions", "settings", "status", "surveyId", "tenantId", "type" ], "type" : "object" }, "SurveyAnswers" : { "description" : "The individual answers of a survey.", "properties" : { "questions" : { "description" : "One entry per question, in the order the questions are answered.", "items" : { "$ref" : "#/components/schemas/QuestionAnswers" }, "type" : "array" }, "surveyId" : { "description" : "Id of the survey.", "format" : "uuid", "type" : "string" } }, "required" : [ "questions", "surveyId" ], "type" : "object" }, "SurveyContext" : { "description" : "Who the survey is for. `areaIds` is only used for `AREAS`, `participantIds` only for `PRIVATE`.", "properties" : { "areaIds" : { "description" : "The areas the survey is visible in; empty unless the type is `AREAS`.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "participantIds" : { "description" : "The members a private survey is visible to; empty unless the type is `PRIVATE`.", "items" : { "format" : "uuid", "type" : "string" }, "type" : "array" }, "type" : { "$ref" : "#/components/schemas/SurveyContextType", "description" : "Which audience the survey was created for." } }, "required" : [ "areaIds", "participantIds", "type" ], "type" : "object" }, "SurveyContextInput" : { "description" : "Who the new survey is for. `TENANT` needs neither list, `AREAS` needs a non-empty `areaIds`, `PRIVATE` a non-empty `participantIds`. The audience is fixed at creation — `PATCH` cannot change it.", "properties" : { "areaIds" : { "description" : "`AREAS` only: the areas the survey appears in. Each must be an area of `{tenantId}` that is not archived, and the token's owner needs the right to create surveys in each of them.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 100, "minItems" : 1, "type" : "array" }, "participantIds" : { "description" : "`PRIVATE` only: the members the survey is for (at least one). Each must be an active member of `{tenantId}`. The token's owner may answer their own private survey without being listed.", "items" : { "format" : "uuid", "type" : "string" }, "maxItems" : 500, "minItems" : 1, "type" : "array" }, "type" : { "$ref" : "#/components/schemas/SurveyContextType", "description" : "Which audience the survey is for." } }, "required" : [ "type" ], "type" : "object" }, "SurveyContextType" : { "enum" : [ "TENANT", "AREAS", "PRIVATE" ], "type" : "string" }, "SurveyMetadata" : { "description" : "Counters and timestamps of a survey.", "properties" : { "activatedAt" : { "description" : "When the survey became active.", "format" : "date-time", "type" : "string" }, "answersCompleted" : { "description" : "How many people have answered every required question.", "format" : "int32", "type" : "integer" }, "answersStarted" : { "description" : "How many people have answered at least one question.", "format" : "int32", "type" : "integer" }, "completedAt" : { "description" : "When the survey was completed.", "format" : "date-time", "type" : "string" }, "createdAt" : { "description" : "When the survey was created.", "format" : "date-time", "type" : "string" }, "firstAnswerAt" : { "description" : "When the first answer was given.", "format" : "date-time", "type" : "string" }, "lastAnswerAt" : { "description" : "When the most recent answer was given.", "format" : "date-time", "type" : "string" }, "revision" : { "description" : "Increases with every change to the survey.", "format" : "int32", "type" : "integer" } }, "required" : [ "answersCompleted", "answersStarted", "createdAt", "revision" ], "type" : "object" }, "SurveyResult" : { "discriminator" : { "mapping" : { "BOOLEAN" : "#/components/schemas/BooleanResult", "CHOICE" : "#/components/schemas/ChoiceResult", "FREE_TEXT" : "#/components/schemas/FreeTextResult", "MEMBER" : "#/components/schemas/MemberResult", "RATING" : "#/components/schemas/RatingResult", "SCHEDULING" : "#/components/schemas/SchedulingResult" }, "propertyName" : "type" }, "oneOf" : [ { "$ref" : "#/components/schemas/BooleanResult" }, { "$ref" : "#/components/schemas/ChoiceResult" }, { "$ref" : "#/components/schemas/FreeTextResult" }, { "$ref" : "#/components/schemas/MemberResult" }, { "$ref" : "#/components/schemas/RatingResult" }, { "$ref" : "#/components/schemas/SchedulingResult" } ] }, "SurveyResults" : { "description" : "The aggregated answers of a survey.", "properties" : { "results" : { "description" : "One entry per question, in the order the questions are answered.", "items" : { "$ref" : "#/components/schemas/QuestionResult" }, "type" : "array" }, "status" : { "$ref" : "#/components/schemas/SurveyStatus", "description" : "Lifecycle state of the survey — it decides which visibility setting applies." }, "surveyId" : { "description" : "Id of the survey.", "format" : "uuid", "type" : "string" } }, "required" : [ "results", "status", "surveyId" ], "type" : "object" }, "SurveySchedule" : { "description" : "When a survey opens and closes. Both ends are optional; a survey without a schedule runs until it is completed.", "properties" : { "end" : { "description" : "When the survey completes automatically. Must be in the future and after `start`.", "format" : "date-time", "type" : "string" }, "start" : { "description" : "When the survey becomes active. Must be in the future while the survey has not started yet.", "format" : "date-time", "type" : "string" } }, "type" : "object" }, "SurveySettings" : { "description" : "How the survey behaves and who may see its data.", "properties" : { "allowChildAnswers" : { "description" : "Whether a member may answer on behalf of their children. Not settable through this API.", "type" : "boolean" }, "allowComments" : { "description" : "Whether members may discuss the survey in a conversation.", "type" : "boolean" }, "allowGuestAnswers" : { "description" : "Whether a member may answer on behalf of a guest. Not settable through this API.", "type" : "boolean" }, "allowPublicAnswers" : { "description" : "Whether people outside the tenant may answer. Not settable through this API.", "type" : "boolean" }, "allowRevisions" : { "description" : "Whether an answer may be changed or withdrawn after it was given.", "type" : "boolean" }, "answerVisibility" : { "$ref" : "#/components/schemas/SurveyVisibility", "description" : "Who may see the individual answers." }, "answererVisibility" : { "$ref" : "#/components/schemas/SurveyVisibility", "description" : "Who may see who gave an individual answer." }, "immutable" : { "description" : "Whether the running survey is frozen: while it is active neither its questions nor its settings change.", "type" : "boolean" }, "liveResultVisibility" : { "$ref" : "#/components/schemas/SurveyVisibility", "description" : "Who may see the aggregated results while the survey is still running." }, "resultVisibility" : { "$ref" : "#/components/schemas/SurveyVisibility", "description" : "Who may see the aggregated results once the survey is complete." } }, "required" : [ "allowChildAnswers", "allowComments", "allowGuestAnswers", "allowPublicAnswers", "allowRevisions", "answerVisibility", "answererVisibility", "immutable", "liveResultVisibility", "resultVisibility" ], "type" : "object" }, "SurveySettingsInput" : { "description" : "How the new survey behaves and who may see its data. Every field is optional; the visibilities default to `NONE` and the flags to `false`.", "properties" : { "allowComments" : { "description" : "Whether members may discuss the survey in a conversation.", "type" : "boolean" }, "allowRevisions" : { "description" : "Whether an answer may be changed or withdrawn after it was given.", "type" : "boolean" }, "answerVisibility" : { "$ref" : "#/components/schemas/SurveyVisibility", "description" : "Who may see the individual answers." }, "answererVisibility" : { "$ref" : "#/components/schemas/SurveyVisibility", "description" : "Who may see who gave an individual answer." }, "liveResultVisibility" : { "$ref" : "#/components/schemas/SurveyVisibility", "description" : "Who may see the aggregated results while the survey is still running." }, "resultVisibility" : { "$ref" : "#/components/schemas/SurveyVisibility", "description" : "Who may see the aggregated results once the survey is complete." } }, "type" : "object" }, "SurveyStatus" : { "enum" : [ "DRAFT", "SCHEDULED", "ACTIVE", "COMPLETE", "ARCHIVED", "DELETED" ], "type" : "string" }, "SurveyType" : { "enum" : [ "SURVEY", "POLL" ], "type" : "string" }, "SurveyVisibility" : { "enum" : [ "NONE", "CREATOR", "COLLABORATORS", "WRITE_ACCESS_USERS", "PARTICIPANTS", "MEMBERS", "PUBLIC" ], "type" : "string" }, "TenantAdminSubject" : { "description" : "Every administrator of the tenant.", "properties" : { "type" : { "description" : "Always `tenantAdmin`.", "enum" : [ "tenantAdmin" ], "type" : "string" } }, "required" : [ "type" ], "type" : "object" }, "TenantMemberSubject" : { "description" : "Every active member of the tenant.", "properties" : { "type" : { "description" : "Always `tenantMember`.", "enum" : [ "tenantMember" ], "type" : "string" } }, "required" : [ "type" ], "type" : "object" }, "TenantRoleSubject" : { "description" : "Everybody carrying a tenant role. The role must belong to this tenant and must not be deleted.", "properties" : { "roleId" : { "description" : "Id of the tenant role.", "format" : "uuid", "type" : "string" }, "type" : { "description" : "Always `tenantRole`.", "enum" : [ "tenantRole" ], "type" : "string" } }, "required" : [ "roleId", "type" ], "type" : "object" }, "TimeChoice" : { "description" : "A single time of day. `type: TIME`.", "properties" : { "choiceId" : { "description" : "Id of the choice — answers reference it.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the time.", "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `TIME`.", "enum" : [ "TIME" ], "type" : "string" }, "value" : { "description" : "The time of day.", "format" : "time", "type" : "string" } }, "required" : [ "choiceId", "type", "value" ], "type" : "object" }, "TimeChoiceInput" : { "description" : "A single time of day. `type: TIME`.", "properties" : { "choiceId" : { "description" : "Id of an existing choice; absent creates a new one.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the time.", "maxLength" : 200, "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "maxLength" : 2000, "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `TIME`.", "enum" : [ "TIME" ], "type" : "string" }, "value" : { "description" : "The time of day.", "format" : "time", "type" : "string" } }, "required" : [ "type", "value" ], "type" : "object" }, "TimeRange" : { "description" : "A range of times of day, both ends inclusive.", "properties" : { "end" : { "description" : "End of the range; must not be before `start`.", "format" : "time", "type" : "string" }, "start" : { "description" : "Start of the range.", "format" : "time", "type" : "string" } }, "required" : [ "end", "start" ], "type" : "object" }, "TimeRangeChoice" : { "description" : "A range of times of day. `type: TIME_RANGE`.", "properties" : { "choiceId" : { "description" : "Id of the choice — answers reference it.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the range.", "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `TIME_RANGE`.", "enum" : [ "TIME_RANGE" ], "type" : "string" }, "value" : { "$ref" : "#/components/schemas/TimeRange", "description" : "The range of times." } }, "required" : [ "choiceId", "type", "value" ], "type" : "object" }, "TimeRangeChoiceInput" : { "description" : "A range of times of day. `type: TIME_RANGE`.", "properties" : { "choiceId" : { "description" : "Id of an existing choice; absent creates a new one.", "format" : "uuid", "type" : "string" }, "choiceText" : { "description" : "Label shown instead of the range.", "maxLength" : 200, "type" : "string" }, "description" : { "description" : "Longer explanation of the choice.", "maxLength" : 2000, "type" : "string" }, "type" : { "description" : "Discriminator of the union; always `TIME_RANGE`.", "enum" : [ "TIME_RANGE" ], "type" : "string" }, "value" : { "$ref" : "#/components/schemas/TimeRange", "description" : "The range of times; `end` must not be before `start`." } }, "required" : [ "type", "value" ], "type" : "object" }, "TimeWindowConfig" : { "description" : "One end of an RSVP time window.", "properties" : { "commitmentTypes" : { "description" : "The RSVP kinds this window applies to.", "items" : { "$ref" : "#/components/schemas/CommitmentType" }, "type" : "array" }, "duration" : { "description" : "ISO-8601 duration relative to the occurrence's start, e.g. `PT48H`. Between `PT0S` and `P366D`.", "type" : "string" } }, "required" : [ "commitmentTypes", "duration" ], "type" : "object" }, "UpdateQuestionRequest" : { "description" : "The new content of a question.", "properties" : { "deleteData" : { "description" : "Throw the answers already given to this question away. Without it the existing answers are kept, which only makes sense while the question's choices and bounds still accept them.", "type" : "boolean" }, "question" : { "$ref" : "#/components/schemas/QuestionInput", "description" : "The question as it should be. Choices that already exist must carry their `choiceId`; a choice without one is created." } }, "required" : [ "question" ], "type" : "object" }, "UserSubject" : { "description" : "One named member. The member must be an active member of the tenant.", "properties" : { "type" : { "description" : "Always `user`.", "enum" : [ "user" ], "type" : "string" }, "userId" : { "description" : "Id of the member.", "format" : "uuid", "type" : "string" } }, "required" : [ "type", "userId" ], "type" : "object" }, "Weekday" : { "enum" : [ "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY" ], "type" : "string" } }, "securitySchemes" : { "personalAccessToken" : { "bearerFormat" : "klubraum_pat_…", "description" : "A personal access token created in the Klubraum app. Bound to one tenant, scoped, expiring, revocable.", "scheme" : "bearer", "type" : "http" } } }, "info" : { "contact" : { "email" : "support@klubraum.com", "name" : "Klubraum", "url" : "https://klubraum.com" }, "description" : "The Klubraum REST API lets you work with the members, calendar events, areas, roles,\nconversations and surveys of your Klubraum from your own scripts, websites and tools. It's plain\nJSON over HTTPS; every endpoint lives below `/v1`.\n\nA Klubraum — the space of one club or group — is called a **tenant** in this API, and `tenantId`\nis its id. Member endpoints are included in the Plus plan, everything else in the Pro plan\n(Pro includes everything in Plus).\n\n## Authentication\n\nEvery request carries a **personal access token** (PAT) as a bearer token:\n\n Authorization: Bearer klubraum_pat_…\n\nYou create tokens in the Klubraum app (tenant administrators only, for now). A token belongs to\n**one tenant**, carries **scopes**, expires (default 90 days, at most 365, or never if you say\nso) and can be revoked at any time — revocation takes effect on the next request. Scopes never\ngrant more than the token's owner may do in the app: every call is also checked against the\nowner's live permissions, so a member's token can't invite people even with `members:write`.\n\n| scope | covers |\n|---|---|\n| `members:read` / `members:write` | members, invitations and the roles assigned to a member |\n| `events:read` / `events:write` | calendar events, their occurrences and ride sharings |\n| `areas:read` / `areas:write` | areas, area groups and the per-area capability configuration |\n| `conversations:read` / `conversations:write` | conversations and their messages |\n| `surveys:read` / `surveys:write` | surveys and polls, their answers and their results |\n\nA **write scope implies the matching read scope**, so `events:write` alone is enough to read and\nwrite events. Tenant **roles** have no scope of their own: they are member metadata and are\ncovered by `members:read` / `members:write`.\n\nCall `GET /v1/token` first — it tells you whose token you hold, which tenant and scopes it has,\nthe tenant's plan and when it expires.\n\n## Plans\n\nMember endpoints need the Plus plan, every other endpoint the Pro plan. If your plan doesn't\ninclude an endpoint, the call fails with `403` and the problem code `plan_required`\n(`requiredPlan` and `currentPlan` tell you which). Only active tenants can use the API\n(`tenant_unavailable` otherwise).\n\n## Rate limits\n\nQuotas apply per token, per tenant (twice the token quota) and, for unauthenticated requests,\nper client IP, over four windows (second, minute, hour, day):\n\n| plan | per second | per minute | per hour | per day |\n|---|---|---|---|---|\n| Plus | 10 | 30 | 50 | 300 |\n| Pro | 20 | 60 | 200 | 1 000 |\n\nRequests are **weighted**: reads cost 1 unit, mutations (invite, remove, patch, cancel, uncancel, delete\nan occurrence) cost 3, fan-out mutations (create event, delete event) cost 5. Every response carries the\nIETF `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers of the tightest window; a\nrejected request is a `429 rate_limited` problem with `Retry-After`. The weight is charged on\nadmission, so a request that is later rejected (wrong scope, no permission) still counts.\n\n## Errors\n\nErrors are RFC 9457 problem documents (`application/problem+json`) with a stable machine-readable\n`code` (see the `Problem` schema) and the `requestId` of the failed request — quote it when you\ncontact us. Validation problems (`400 validation_failed`) list the offending fields in `errors`.\nReads of resources your token may not see answer `404`, writes `403`.\n\n## Calendar events\n\nAn event is visible in exactly one of three ways, decided when it is created and **fixed from then\non**: to the whole tenant (no `areaIds`, not private), in one or more **areas** (`areaIds`), or\n**privately** to the people you list (`isPrivate: true` plus `privateInviteeIds`; the token's owner is\nalways among them). A `PATCH` cannot move an event between these modes — `isPrivate`, `areaIds` and\n`privateInviteeIds` are not part of the patch body. The full matrix is in the description of\n`POST /v1/tenants/{tenantId}/events`.\n\nRecurring events are expanded by the Klubraum app, not by the server, and the app renders only four\nshapes: daily, weekly on given weekdays, monthly on the nth (or last) weekday, and yearly on the same\ndate. The API therefore accepts exactly those — see the create operation for the table — and rejects\neverything else instead of storing a series that would show no occurrences at all. `count`, `byMonth`,\n`byMonthDay`, `byYearDay` and `byWeekNo` are not accepted on write; `count` is reported on read for\nseries that were imported from an ICS file.\n\nEvery size limit is part of the schema (`maxLength`, `maxItems`, `minimum`/`maximum`) and enforced by\nthe server, so you can validate against the spec before you call: titles 500 characters, plain-text\ndescriptions 20 000, `areaIds` 100 entries, `privateInviteeIds` 500, `responsibleUserIds` 100,\nparticipants 0–10 000, a cancellation reason 200 characters. Ids you send must exist in your tenant:\nan area of another tenant or a person who is not an active member is a `400` naming the entry\n(`areaIds[0]`). A request body larger than **256 KB** is rejected with `413 payload_too_large`.\n\n## Areas, roles, conversations and surveys\n\nAreas are the sub-groups a Klubraum is divided into (a team, a department, a committee); area\ngroups bundle areas for the app's navigation. Roles are the labels a tenant administrator\nassigns to members. Conversations carry the messages of a tenant, of areas or of a private\ncircle; surveys and polls collect answers from members. **Every endpoint of these four families\nneeds the Pro plan** — including the read-only ones and including the role endpoints, which are\nreached through the `members:*` scopes but are not part of Plus member management.\n\n## Conventions\n\n* Collections are plural and tenant-scoped: `/v1/tenants/{tenantId}/…`; the tenant in the path must be\n your token's tenant (`403 tenant_mismatch` otherwise).\n* Lists are cursor-paginated: `?limit=&cursor=` → `{ \"items\": […], \"nextCursor\": \"…\" }`; `nextCursor`\n is absent on the last page.\n* Date-times are ISO-8601 with a UTC offset (`2026-09-01T18:00:00+02:00`); calendar events carry an\n IANA `timeZone` in which `start`/`end` are interpreted.\n* Occurrences of recurring events are addressed by `instanceId` = the Unix epoch **seconds** of the\n occurrence's original start.\n* Optional fields are omitted from responses when they have no value (never `null`).\n* Unknown request fields are rejected (`400`).\n* `PATCH` bodies are JSON Merge Patch (RFC 7396, `application/merge-patch+json` or `application/json`):\n absent = unchanged, `null` = clear, value = set. `recurrence`, `location` and `description` are\n replaced as a whole; `commitmentOptions` is merged field by field.\n\nEvery response carries an `X-Request-Id` header assigned by the gateway (a value you send is replaced, not\nechoed — read the id from the response); it also appears as `requestId` in problems. Quote it when you contact us.\n", "termsOfService" : "https://klubraum.com/terms", "title" : "Klubraum Public API", "version" : "1.0.0" }, "openapi" : "3.1.0", "paths" : { "/v1/tenants/{tenantId}/area-groups" : { "get" : { "description" : "Returns the area groups of the tenant, sorted by name. An **archived** group is never listed — archiving removes it from the tenant's overview — but it stays readable by id with `GET …/area-groups/{areaGroupId}`, which reports `archived: true`.\n\n`areaIds` lists the areas in the group as they were added. It is NOT filtered by what the token's owner may see — a group is a navigation folder, and its content is decided per area (`GET …/areas/{areaId}` answers `404` for an area the owner may not read).\n\nRequires plan `PRO` and scope `areas:read`.", "operationId" : "listAreaGroups", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfAreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the area groups of a tenant", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:read" }, "post" : { "description" : "Creates an empty area group; add areas to it with `PUT …/area-groups/{areaGroupId}/areas/{areaId}`. Requires tenant administrator rights.\n\n`icon` is one of the names listed in the description of `POST /v1/tenants/{tenantId}/areas` — the same vocabulary as for an area. An area group is never deleted, only archived (`POST …/archive`), and archiving is **one-way**: every change to an archived group answers `409`.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "createAreaGroup", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateAreaGroupRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Create an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/area-groups/{areaGroupId}" : { "get" : { "description" : "An area group of another tenant is reported as `404`, exactly like one that does not exist.\n\nRequires plan `PRO` and scope `areas:read`.", "operationId" : "getAreaGroup", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Get an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:read" } }, "/v1/tenants/{tenantId}/area-groups/{areaGroupId}/archive" : { "post" : { "description" : "Archiving is **one-way**: there is no un-archive. An archived group keeps its areas but cannot be changed any more, and it is left out of `GET …/area-groups` from then on while staying readable by id. Archiving a group that is already archived changes nothing and answers `200`. Requires tenant administrator rights.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "archiveAreaGroup", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Archive an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/area-groups/{areaGroupId}/areas/{areaId}" : { "delete" : { "description" : "Removes the area from the group; the area itself is untouched. Removing an area that is not in the group changes nothing. Requires tenant administrator rights.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "removeAreaFromGroup", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area group is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Take an area out of an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" }, "put" : { "description" : "The area must belong to this tenant and must not be archived; anything else is a `400` naming `areaId`. An area may sit in several groups, and adding one that is already in the group changes nothing. Requires tenant administrator rights.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "addAreaToGroup", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area group is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Put an area into an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/area-groups/{areaGroupId}/color" : { "delete" : { "description" : "Requires plan `PRO` and scope `areas:write`.", "operationId" : "clearAreaGroupColor", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area group is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove the colour of an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" }, "put" : { "description" : "`DELETE` on the same path removes the colour. Requires tenant administrator rights.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaGroupColor", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaGroupColorRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area group is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Set the colour of an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/area-groups/{areaGroupId}/description" : { "delete" : { "description" : "Requires plan `PRO` and scope `areas:write`.", "operationId" : "clearAreaGroupDescription", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area group is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove the description of an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" }, "put" : { "description" : "Send a non-blank description; `DELETE` on the same path removes it. Requires tenant administrator rights.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaGroupDescription", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaGroupDescriptionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area group is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Set the description of an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/area-groups/{areaGroupId}/icon" : { "delete" : { "description" : "Requires plan `PRO` and scope `areas:write`.", "operationId" : "clearAreaGroupIcon", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area group is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove the icon of an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" }, "put" : { "description" : "`icon` must be one of the names listed in the description of `POST /v1/tenants/{tenantId}/areas`; `DELETE` on the same path removes it. Requires tenant administrator rights.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaGroupIcon", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaGroupIconRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area group is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Set the icon of an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/area-groups/{areaGroupId}/name" : { "put" : { "description" : "Requires tenant administrator rights.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaGroupName", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaGroupId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaGroupNameRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaGroup" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area group is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Rename an area group", "tags" : [ "Area groups" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas" : { "get" : { "description" : "Returns ALL areas of the tenant, sorted by name. An area's existence and its metadata are tenant-wide: a **private** area is listed for every member too — what its privacy protects is its CONTENT (`…/areas/{areaId}/events`, `…/conversations`, `…/surveys`, which answer `404` for somebody who may not read the area). A hidden area IS returned as well (it is only hidden from the app's area list). An **archived** area is never listed — archiving removes it from the tenant's area overview — but it stays readable by id with `GET …/areas/{areaId}`, which reports `archived: true`.\n\nRequires plan `PRO` and scope `areas:read`.", "operationId" : "listAreas", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfAreaSummary" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the areas of a tenant", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:read" }, "post" : { "description" : "Creates an area in the tenant of the path. Requires tenant administrator rights.\n\nThe token's owner becomes the area's **creator**, its first member and its first administrator, and is subscribed to the area's notifications (new conversation, new event, new survey) — exactly what the Klubraum app does when a person creates an area.\n\n### Privacy and what it decides\n\n`isPrivate` is more than a flag on the response: it picks the **default** subject set of all five capabilities of the area (see `GET …/capabilities`). A public area (`isPrivate: false`, the default) defaults every capability to the active members of the tenant; a private area defaults them to the members of the area. Changing `isPrivate` later (`PUT …/private`) moves those defaults with it — but only for the capabilities you have not configured explicitly.\n\n### Icons\n\n`icon` is one of the names the Klubraum app can draw. Anything else is a `400`, because an unknown name would silently render as the fallback glyph:\n\n`area`, `arm_flex`, `baby_carriage`, `badminton`, `baseball`, `basketball`, `beach`, `bike`, `binoculars`, `biohazard`, `bitcoin`, `boxing`, `brain`, `briefcase`, `brightness`, `bugle`, `cake`, `camera`, `car`, `cards_heart`, `cards_playing`, `cart`, `chart_line`, `checkerboard`, `compass_rose`, `crown`, `currency_usd`, `documents`, `dog_side`, `earth`, `emoticon_cool`, `feather`, `fire`, `folder`, `football`, `gift`, `glass_mug`, `glass_wine`, `golf`, `group`, `guitar`, `halloween`, `hammer`, `handball`, `headphones`, `hook`, `horse`, `hours_24`, `ice_pop`, `island`, `karate`, `laptop_windows`, `leaf`, `lightbulb`, `math_compass`, `meditation`, `money`, `mountain`, `music`, `netflix`, `noodles`, `paw`, `phone`, `radioactive`, `rowing`, `run`, `silverware`, `skate`, `ski`, `skull_crossbones`, `snowflake`, `soccer`, `spade`, `star`, `swim`, `table_tennis`, `tennis`, `tram`, `trophy_variant`, `video_vintage`, `volleyball`, `walk`, `weights`, `yin_yang`, `youtube`.\n\n### Archiving\n\nAn area is never deleted, only archived (`POST …/archive`), and archiving is **one-way**: there is no un-archive, here or in the app. An archived area is left out of `GET …/areas` but stays readable by id. Every change to an archived area answers `409` — except removing a member, which stays possible so people can leave.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "createArea", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateAreaRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Create an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}" : { "get" : { "description" : "Areas are visible to every member of the tenant, private ones included — their privacy protects the area's CONTENT, not the fact that it exists or who administrates it. `404` therefore means exactly one thing: there is no such area in this tenant.\n\nRequires plan `PRO` and scope `areas:read`.", "operationId" : "getArea", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Get an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:read" } }, "/v1/tenants/{tenantId}/areas/{areaId}/administrators/{userId}" : { "delete" : { "description" : "The person stays a member of the area; use `DELETE …/members/{userId}` to remove them entirely. Requires an administrator of the tenant; area administrators cannot take the role off each other.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "removeAreaAdministrator", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Take the administrator role of an area away", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" }, "put" : { "description" : "An administrator of an area may change the area, its content and its members. Every administrator is also a member: somebody who is not a member yet is added as one. They are NOT subscribed to the area's notifications by this call — use `PUT …/members/{userId}` for that.\n\nAn administrator of the **tenant** may appoint and remove area administrators; area administrators cannot appoint co-administrators.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "addAreaAdministrator", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Make a member an administrator of an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/archive" : { "post" : { "description" : "Archiving is **one-way**: there is no un-archive, in this API or in the Klubraum app. An archived area is left out of `GET …/areas` from then on, but stays readable by id (`GET …/areas/{areaId}`, `archived: true`) with its conversations and events. Every change to it — including adding or removing members — answers `409`. Archiving an area that is already archived changes nothing and answers `200`.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "archiveArea", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Archive an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/capabilities" : { "get" : { "description" : "Returns all five capabilities of the area, resolved: `subjects` is the set you configured when `isOverride` is `true`, and the default derived from `isPrivate` when it is `false`.\n\nThis is a **rights** endpoint: it says who may do what in the area, so it requires the same permission as changing it — an active administrator of the tenant. Area administrators and anybody else get `403`, never `404`: the area itself is not a secret.\n\nA `tenantRole` subject whose role was deleted after it was configured is left out — the configuration keeps it, but it grants nothing.\n\nRequires plan `PRO` and scope `areas:read`.", "operationId" : "getAreaCapabilities", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaCapabilities" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Read the capability configuration of an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:read" } }, "/v1/tenants/{tenantId}/areas/{areaId}/capabilities/{capability}" : { "put" : { "description" : "Replaces the subject set of ONE capability **completely** — send the full list you want, not a delta. An **empty** `subjects` removes the configuration and lets the capability fall back to its default (the one derived from `isPrivate`); it does not take the capability away from everyone.\n\nRequires an active administrator of the tenant. Neither `AREA_WRITER` nor being an administrator of this area is enough: somebody who may edit an area must not be able to hand out rights in it.\n\nThe five capabilities are `CONVERSATION_CREATOR`, `EVENT_CREATOR` and `SURVEY_CREATOR` (who may start conversations, events and surveys in the area), `AREA_READER` (who sees the area's CONTENT — the area itself is visible to every member) and `AREA_WRITER` (who may change the area, its description, its icon and its members; NOT its administrators or this configuration).\n\n### Subjects\n\nEach entry is one of six kinds, picked by `type`:\n\n| `type` | grants the capability to | further fields |\n|---|---|---|\n| `user` | one named member | `userId` — an active member of this tenant |\n| `tenantRole` | everybody carrying a role | `roleId` — a role of **this** tenant, not deleted |\n| `areaAdmin` | the administrators of this area | – |\n| `areaMember` | the members of this area | – |\n| `tenantMember` | every active member of the tenant | – |\n| `tenantAdmin` | every administrator of the tenant | – |\n\nThe four id-less kinds are resolved against the area and its tenant whenever they are used, so they stay correct while the membership changes. Duplicates are removed; a `userId` that is not an active member and a `roleId` that belongs to another tenant, was deleted or does not exist are a `400` naming the entry (`subjects[0]`).\n\nThe response is the configuration of **all five** capabilities, as `GET …/capabilities` returns it.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaCapability", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "capability", "required" : true, "schema" : { "$ref" : "#/components/schemas/AreaCapability" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaCapabilityRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AreaCapabilities" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Configure one capability of an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/color" : { "delete" : { "description" : "Requires plan `PRO` and scope `areas:write`.", "operationId" : "clearAreaColor", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove the colour of an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" }, "put" : { "description" : "`DELETE` on the same path removes the colour and lets the app fall back to its own palette.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaColor", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaColorRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Set the colour of an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/conversations" : { "get" : { "description" : "Returns the conversations assigned to the area, newest activity first. Private conversations the token's owner does not take part in are never returned, even though they are assigned to the area. Same keyset paging as \"List the tenant-wide conversations\".\n\nServed from a read model that follows writes with a delay of a few seconds; the response of a write always reflects the write.\n\nRequires plan `PRO` and scope `conversations:read`.", "operationId" : "listAreaConversations", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfConversationSummary" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the conversations of an area", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:read" } }, "/v1/tenants/{tenantId}/areas/{areaId}/description" : { "delete" : { "description" : "Requires plan `PRO` and scope `areas:write`.", "operationId" : "clearAreaDescription", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove the description of an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" }, "put" : { "description" : "Send a non-blank description; `DELETE` on the same path removes it.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaDescription", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaDescriptionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Set the description of an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/events" : { "get" : { "description" : "Returns the events assigned to `{areaId}`. Private events are never part of this list, whether or not the token's owner was invited to them.\n\nThe token's owner needs read access to the area; an area of another tenant, an area that does not exist and an area the owner may not read are all a `404`.\n\n`from`, `to`, ordering and paging behave exactly as in \"List the calendar events of a tenant\".\n\nServed from a read model that follows writes with a delay of a few seconds; the response of a write always reflects the write.\n\nRequires plan `PRO` and scope `events:read`.", "operationId" : "listAreaEvents", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Only events whose last occurrence is at or after this instant. ISO-8601 with offset. Defaults to the start of the current day in UTC, and must not be more than 20 years in the past.", "in" : "query", "name" : "from", "required" : false, "schema" : { "format" : "date-time", "type" : "string" } }, { "description" : "Only events that start before this instant. ISO-8601 with offset; must be after `from`.", "in" : "query", "name" : "to", "required" : false, "schema" : { "format" : "date-time", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfEvent" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the calendar events of an area", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:read" } }, "/v1/tenants/{tenantId}/areas/{areaId}/hide" : { "post" : { "description" : "A hidden area is left out of the app's area list; it stays readable and its conversations, events and surveys keep working. Use it for areas that only exist to carry content. `POST …/unhide` reverses it.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "hideArea", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Hide an area from the area list", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/icon" : { "delete" : { "description" : "Requires plan `PRO` and scope `areas:write`.", "operationId" : "clearAreaIcon", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove the icon of an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" }, "put" : { "description" : "`icon` must be one of the names listed in the description of \"Create an area\"; `DELETE` on the same path removes it.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaIcon", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaIconRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Set the icon of an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/members/{userId}" : { "delete" : { "description" : "Removes the membership and the member's subscription to the area's notifications; an administrator of the area loses that role with it. Removing somebody who is not a member changes nothing.\n\nRemoving **yourself** is leaving and needs no rights beyond membership of the tenant. Removing **anybody else** requires the right to modify the area.\n\nIf the membership is removed but the subscription cannot be dropped, the membership is restored and the call answers `503` — the membership is left exactly as it was.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "removeAreaMember", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove a member from an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" }, "put" : { "description" : "Adds an active member of the tenant to the area and, unless you say otherwise, subscribes them to the area's notifications (new conversation, new event, new survey) — what the Klubraum app does. Adding somebody who is already a member changes nothing.\n\nAdding **yourself** (`{userId}` = the token's owner) is joining and is checked against the area's join rule: a private area admits only the people it is meant for. Adding **anybody else** requires the right to modify the area.\n\nThe body is optional: `PUT` with no body behaves like `{\"subscribeToNotifications\": true}`.\n\nIf the membership is written but the notification subscription fails, the membership is rolled back and the call answers `503` — you never end up a member without the notifications you asked for.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "addAreaMember", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AddAreaMemberRequest" } } }, "required" : false }, "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Add a member to an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/name" : { "put" : { "description" : "Requires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaName", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaNameRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Rename an area", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/private" : { "put" : { "description" : "Privacy decides the **default** subject set of the area's five capabilities: a public area defaults them to the active members of the tenant, a private one to the members of the area. Capabilities you configured explicitly (`isOverride: true` in `GET …/capabilities`) are NOT touched — flipping the flag back and forth never loses them.\n\nRequires plan `PRO` and scope `areas:write`.", "operationId" : "setAreaPrivacy", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetAreaPrivacyRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Make an area private or public", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/areas/{areaId}/surveys" : { "get" : { "description" : "Returns the surveys and polls of one area, newest first (by creation). The token's owner must be allowed to read the area — otherwise the area is reported as not found. Drafts and scheduled surveys are only listed for their creator and collaborators.\n\nRequires plan `PRO` and scope `surveys:read`.", "operationId" : "listAreaSurveys", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfSurvey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the surveys of an area", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:read" } }, "/v1/tenants/{tenantId}/areas/{areaId}/unhide" : { "post" : { "description" : "Requires plan `PRO` and scope `areas:write`.", "operationId" : "unhideArea", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "areaId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Area" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The area is archived" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Show a hidden area in the area list again", "tags" : [ "Areas" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "areas:write" } }, "/v1/tenants/{tenantId}/conversations" : { "get" : { "description" : "Returns the conversations that are visible to the whole tenant — neither private nor assigned to areas — newest activity first.\n\nPaging is keyset-based: pass the `nextCursor` of a response as `cursor` to continue below the last item you saw. A page can hold fewer than `limit` items and still carry a `nextCursor`, because conversations the token's owner may not read are dropped after the page was cut; keep following `nextCursor` until it is absent.\n\nServed from a read model that follows writes with a delay of a few seconds; the response of a write always reflects the write.\n\nRequires plan `PRO` and scope `conversations:read`.", "operationId" : "listConversations", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfConversationSummary" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the tenant-wide conversations", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:read" }, "post" : { "description" : "Starts a conversation in the tenant of the path, optionally with a first message.\n\nThe token's owner is the conversation's **creator**: they are reported as `createdBy`, they are always among the `participantIds` (you do not have to list them yourself), and they are the author of the first message.\n\n### Visibility\n\n`isPrivate`, `areaIds` and `participantIds` together pick exactly one of three modes. The choice is **fixed at creation** for `isPrivate` and `participantIds`; the areas of a standalone conversation can be changed later with `PUT /v1/tenants/{tenantId}/conversations/{conversationId}/areas`.\n\n| mode | `isPrivate` | `areaIds` | `participantIds` |\n|---|---|---|---|\n| visible to the whole tenant | absent or `false` | empty or absent | empty or absent |\n| visible in areas | absent or `false` | one or more areas of this tenant | empty or absent |\n| private | `true` | must be empty | the members who take part (may be empty) |\n\nAnything else is a `400`: `areaIds` together with `isPrivate: true`, or `participantIds` without it. Every id in `areaIds` must be an area of this tenant that is not archived, and every id in `participantIds` an active member of it; the offending entry is reported as `areaIds[0]` and so on.\n\n### Permissions\n\nA conversation in areas needs the right to start conversations in **each** of them; a tenant-wide or private conversation needs nothing beyond active membership.\n\n### The first message\n\n`message` is optional — a conversation may start empty and receive its first message through `POST …/conversations/{conversationId}/messages`. When it is given, `message.text` is required and `message.html` is sanitised: only a safe subset of HTML survives.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "createConversation", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateConversationRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Conversation" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Start a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/conversations/mine" : { "get" : { "description" : "Returns every conversation the token's owner started or participates in — private ones and the conversations of calendar events and ride sharings included — newest activity first. Same keyset paging as \"List the tenant-wide conversations\".\n\nServed from a read model that follows writes with a delay of a few seconds; the response of a write always reflects the write.\n\nRequires plan `PRO` and scope `conversations:read`.", "operationId" : "listMyConversations", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfConversationSummary" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the conversations the token's owner takes part in", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:read" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}" : { "delete" : { "description" : "Deletes the conversation with its messages and unlinks it from the areas, calendar-event occurrence or ride sharing it belonged to. A deleted conversation answers `404` everywhere except `POST …/conversations/{conversationId}/undelete`, which restores it together with its links.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "deleteConversation", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Delete a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" }, "get" : { "description" : "Returns the conversation without its messages — read those with `GET /v1/tenants/{tenantId}/conversations/{conversationId}/messages`. Reading a conversation does not mark anything as read: the read progress of the Klubraum app is untouched by this API.\n\nServed from a read model that follows writes with a delay of a few seconds; the response of a write always reflects the write.\n\nRequires plan `PRO` and scope `conversations:read`.", "operationId" : "getConversation", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Conversation" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Get a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:read" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}/areas" : { "put" : { "description" : "Replaces the areas of a **standalone** conversation; an empty list makes it visible to the whole tenant. Only the difference to the current areas is written, and the conversation is linked into the added areas and unlinked from the removed ones.\n\nThe conversation of a calendar-event occurrence or of a ride sharing inherits its areas from that resource and cannot be reassigned (`409`), and a private conversation cannot be assigned to areas at all (`409`).\n\nMoving a conversation into an area is starting one there: every **added** area needs the right to start conversations in it, on top of the right to modify the conversation. Removing an area needs nothing extra.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "setConversationAreas", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetConversationAreasRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Conversation" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The conversation is private or does not have its own areas" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Set the areas a conversation is visible in", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}/lock" : { "post" : { "description" : "A locked conversation accepts no further messages. Locking an already locked conversation changes nothing.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "lockConversation", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Conversation" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Lock a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}/messages" : { "get" : { "description" : "Returns the messages **newest first**, starting with the newest page. Pass the `nextCursor` of a response as `cursor` to walk further back in time; `nextCursor` is absent once the oldest message has been delivered.\n\nA cursor belongs to one conversation and to the page it was handed out with — a cursor from another conversation, or one whose page has meanwhile shifted, is rejected with `400` rather than silently restarting at the newest page.\n\nDeleted messages keep their place in the thread with an empty body and `deleted: true`. Attachments of image, document, audio and location messages are not part of the public API yet; such a message is reported with its `kind` and its text.\n\nRequires plan `PRO` and scope `conversations:read`.", "operationId" : "listMessages", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfMessage" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the messages of a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:read" }, "post" : { "description" : "The token's owner is the author. `html` is sanitised: only a safe subset of HTML survives.\n\nWhoever may READ a conversation may post in it while it is unlocked — posting needs no permission of its own. A locked conversation accepts no messages and answers `409`; a conversation the token's owner may not read answers `404`, exactly as `GET …/conversations/{conversationId}` does, so a `409` never tells somebody outside the conversation that it exists.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "postMessage", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PostMessageRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Message" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The conversation is locked" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Post a message to a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}/messages/{messageId}" : { "delete" : { "description" : "Only the **author** of a message may delete it. The message keeps its place in the thread with an empty body and `deleted: true`.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "deleteMessage", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "messageId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Delete a message", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" }, "put" : { "description" : "Replaces the body of a message. Only its **author** may edit it — there is no moderator override in this API. `html` is sanitised on write, and the message is marked as edited.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "editMessage", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "messageId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/EditMessageRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Message" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Edit a message", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}/messages/{messageId}/like" : { "delete" : { "description" : "Requires plan `PRO` and scope `conversations:write`.", "operationId" : "unlikeMessage", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "messageId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Withdraw the like of a message", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" }, "put" : { "description" : "The token's owner likes the message. Liking twice changes nothing.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "likeMessage", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "messageId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Like a message", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}/participants/{userId}" : { "delete" : { "description" : "The token's owner may always remove themselves; removing somebody else additionally needs the right to modify the conversation.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "removeConversationParticipant", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove a participant from a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" }, "put" : { "description" : "Adding **yourself** (`{userId}` = the token's owner) is joining, and needs no more than the right to read the conversation — whoever may follow a conversation may take part in it. Adding **anybody else** requires the right to add participants, and they must be an active member of this tenant.\n\nAdding a member that already takes part changes nothing.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "addConversationParticipant", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Add a participant to a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}/subject" : { "delete" : { "description" : "Requires plan `PRO` and scope `conversations:write`.", "operationId" : "clearConversationSubject", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Conversation" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove the subject of a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" }, "put" : { "description" : "Requires plan `PRO` and scope `conversations:write`.", "operationId" : "setConversationSubject", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetSubjectRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Conversation" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Set the subject of a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}/undelete" : { "post" : { "description" : "Restores a conversation that was deleted and links it back into the areas, calendar-event occurrence or ride sharing it belonged to. A conversation that is not deleted answers `409`.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "undeleteConversation", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Conversation" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The conversation is not deleted" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Restore a deleted conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/conversations/{conversationId}/unlock" : { "post" : { "description" : "Requires plan `PRO` and scope `conversations:write`.", "operationId" : "unlockConversation", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "conversationId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Conversation" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Unlock a conversation", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/events" : { "get" : { "description" : "Returns the events that are visible to the whole tenant — the ones created without `areaIds` and without `isPrivate`. Events of an area are listed by \"List the calendar events of an area\", the token owner's own ones (private events included) by \"List the calendar events on your own calendar\".\n\n### The time window\n\n`from` selects by the **last** occurrence of an event, so a series that started years ago but is still running is part of the answer; `to` selects by the `start` of the event (the first occurrence of a series). That asymmetry is deliberate: it is what makes \"what is going on now\" a single call, and it is the same window the Klubraum app itself asks for.\n\nEvents are returned in ascending order of `start`, cursor-paginated. The order is stable across pages, so a cursor keeps its meaning; new events created between two pages can still appear.\n\nServed from a read model that follows writes with a delay of a few seconds; the response of a write always reflects the write.\n\nRequires plan `PRO` and scope `events:read`.", "operationId" : "listEvents", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Only events whose last occurrence is at or after this instant. ISO-8601 with offset. Defaults to the start of the current day in UTC, and must not be more than 20 years in the past.", "in" : "query", "name" : "from", "required" : false, "schema" : { "format" : "date-time", "type" : "string" } }, { "description" : "Only events that start before this instant. ISO-8601 with offset; must be after `from`.", "in" : "query", "name" : "to", "required" : false, "schema" : { "format" : "date-time", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfEvent" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the calendar events of a tenant", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:read" }, "post" : { "description" : "Creates an event in the tenant of the path.\n\nThe token's owner is the event's **creator**: they are reported as `createdBy`, the event is added to their own calendar, and for a private event they are always among the invitees (you do not have to list them yourself).\n\n### Visibility\n\n`isPrivate`, `areaIds` and `privateInviteeIds` together pick exactly one of three modes. The choice is **fixed at creation** — `PATCH` cannot change it.\n\n| mode | `isPrivate` | `areaIds` | `privateInviteeIds` |\n|---|---|---|---|\n| visible to the whole tenant | absent or `false` | empty or absent | empty or absent |\n| visible in areas | absent or `false` | one or more areas of this tenant | empty or absent |\n| private | `true` | must be empty | the members who may see it (may be empty) |\n\nAnything else is a `400`: `areaIds` together with `isPrivate: true`, or `privateInviteeIds` without it. Every id in `areaIds` must be an area of this tenant, and every id in `privateInviteeIds` and `responsibleUserIds` an active member of it; the offending entry is reported as `areaIds[0]` and so on.\n\n### Recurrence\n\nOccurrences are expanded by the Klubraum app, which renders exactly the combinations below. Anything else is rejected rather than stored as a series that would show no occurrences at all.\n\n| `frequency` | `interval` | `byWeekday` | `bySetPos` | repeats |\n|---|---|---|---|---|\n| `DAILY` | 1–100 | – | – | every n days |\n| `WEEKLY` | 1–100 | required, 1–7 unique weekdays | – | on those weekdays, every n weeks |\n| `MONTHLY` | exactly `1` | exactly one weekday | exactly one of `1`, `2`, `3`, `4`, `-1` | on that weekday of every month |\n| `YEARLY` | 1–100 | – | – | on the same date, every n years |\n\n`start` defaults to the event's `start`; `until` must be after it and at most 50 years later. `count`, `byMonth`, `byMonthDay`, `byYearDay` and `byWeekNo` are not accepted.\n\nRequires plan `PRO` and scope `events:write`.", "operationId" : "createEvent", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateEventRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Event" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "An event with the same temporary id was already created" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Create a calendar event", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:write" } }, "/v1/tenants/{tenantId}/events/mine" : { "get" : { "description" : "Returns the events on the calendar of the token's **owner** — the ones they created and the ones they were added to. Unlike the two other lists this one includes private events, because the owner is an invitee of every private event on their calendar. There is no way to read another member's calendar through this API.\n\n`from`, `to`, ordering and paging behave exactly as in \"List the calendar events of a tenant\".\n\nServed from a read model that follows writes with a delay of a few seconds; the response of a write always reflects the write.\n\nRequires plan `PRO` and scope `events:read`.", "operationId" : "listMyEvents", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Only events whose last occurrence is at or after this instant. ISO-8601 with offset. Defaults to the start of the current day in UTC, and must not be more than 20 years in the past.", "in" : "query", "name" : "from", "required" : false, "schema" : { "format" : "date-time", "type" : "string" } }, { "description" : "Only events that start before this instant. ISO-8601 with offset; must be after `from`.", "in" : "query", "name" : "to", "required" : false, "schema" : { "format" : "date-time", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfEvent" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the calendar events on your own calendar", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:read" } }, "/v1/tenants/{tenantId}/events/{eventId}" : { "delete" : { "description" : "Requires plan `PRO` and scope `events:write`.", "operationId" : "deleteEvent", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The event is not in a state that allows deletion" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Delete a calendar event", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:write" }, "get" : { "description" : "Served from a read model that follows writes with a delay of a few seconds; the response of a write always reflects the write.\n\nRequires plan `PRO` and scope `events:read`.", "operationId" : "getEvent", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Event" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Get a calendar event", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:read" }, "patch" : { "description" : "Absent fields are left untouched, `null` clears a field, a value sets it. For a recurring event the whole series is updated; use `fromInstanceId` to change only the occurrences from that instance on.\n\nThe visibility of an event is **fixed at creation**: `isPrivate`, `areaIds` and `privateInviteeIds` are not part of this body and sending one is a `400`. A replaced `recurrence` must follow the same grammar as on create (see \"Create a calendar event\"); an omitted `recurrence.start` keeps the series where it is.\n\nRequires plan `PRO` and scope `events:write`.", "operationId" : "patchEvent", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PatchEventRequest" } }, "application/merge-patch+json" : { "schema" : { "$ref" : "#/components/schemas/PatchEventRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Event" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The event is not in a state that allows the change" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Update a calendar event (JSON Merge Patch)", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:write" } }, "/v1/tenants/{tenantId}/events/{eventId}/cancel" : { "post" : { "description" : "Marks the event (all occurrences) as cancelled; it stays visible with the cancellation reason. The body is optional; `reason` is at most 200 characters. Cancelling an event that is already cancelled changes nothing and answers `204`; a deleted event answers `404`.\n\nRequires plan `PRO` and scope `events:write`.", "operationId" : "cancelEvent", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CancelEventRequest" } } }, "required" : false }, "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Cancel a calendar event", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:write" } }, "/v1/tenants/{tenantId}/events/{eventId}/instances/{instanceId}" : { "delete" : { "description" : "Requires plan `PRO` and scope `events:write`.", "operationId" : "deleteEventInstance", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "instanceId", "required" : true, "schema" : { "format" : "int64", "type" : "integer" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The occurrence is not in a state that allows deletion" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Delete one occurrence of a recurring event", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:write" } }, "/v1/tenants/{tenantId}/events/{eventId}/instances/{instanceId}/cancel" : { "post" : { "description" : "`instanceId` is the Unix epoch second of the occurrence's original start (see `instanceOverrides`). The body is optional; `reason` is at most 200 characters. Cancelling an occurrence that is already cancelled changes nothing and answers `204`; a deleted event answers `404`. An occurrence of an event that is cancelled as a whole cannot be cancelled on its own — `409`.\n\nRequires plan `PRO` and scope `events:write`.", "operationId" : "cancelEventInstance", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "instanceId", "required" : true, "schema" : { "format" : "int64", "type" : "integer" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CancelEventRequest" } } }, "required" : false }, "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The event is cancelled as a whole" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Cancel one occurrence of a recurring event", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:write" } }, "/v1/tenants/{tenantId}/events/{eventId}/instances/{instanceId}/messages" : { "post" : { "description" : "Every occurrence of a calendar event has its own conversation, and that conversation is created by its FIRST message — there is no separate endpoint to create it. `conversationCreated` tells you which of the two happened; `conversationId` is the conversation to address from then on.\n\n`instanceId` is the Unix epoch second of the occurrence's original start (see `instanceOverrides` of the event). A conversation created here inherits the event's visibility: for a private event it is private and its participants are the event's invitees plus the token's owner.\n\nPosting into a conversation that already exists needs the right to READ it (`404` otherwise, as everywhere else), and a locked conversation accepts no messages (`409`).\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "postEventInstanceMessage", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "instanceId", "required" : true, "schema" : { "format" : "int64", "type" : "integer" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PostMessageRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PostedMessage" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The conversation of the occurrence is locked" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Post a message to the conversation of an event occurrence", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/events/{eventId}/instances/{instanceId}/ride-sharings" : { "get" : { "description" : "Returns the ride sharings members offer for one occurrence of a calendar event, ordered by departure. Deleted ones are left out, cancelled ones are reported with `cancelled: true`. This is the way to find the `rideSharingId` for `POST /v1/tenants/{tenantId}/ride-sharings/{rideSharingId}/messages`.\n\nRequires plan `PRO` and scope `events:read`.", "operationId" : "listEventInstanceRideSharings", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "instanceId", "required" : true, "schema" : { "format" : "int64", "type" : "integer" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "items" : { "$ref" : "#/components/schemas/RideSharingSummary" }, "type" : "array" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the ride sharings of an event occurrence", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:read" } }, "/v1/tenants/{tenantId}/events/{eventId}/instances/{instanceId}/uncancel" : { "post" : { "description" : "Reverts the cancellation of one occurrence; `instanceId` is the Unix epoch second of its original start (see `instanceOverrides`). No body. Uncancelling an occurrence that is not cancelled changes nothing and answers `204`; a deleted event answers `404`. An occurrence of an event that is cancelled as a whole cannot be uncancelled on its own — uncancel the event instead — `409`.\n\nRequires plan `PRO` and scope `events:write`.", "operationId" : "uncancelEventInstance", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "instanceId", "required" : true, "schema" : { "format" : "int64", "type" : "integer" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The event is cancelled as a whole" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Uncancel one occurrence of a recurring event", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:write" } }, "/v1/tenants/{tenantId}/events/{eventId}/uncancel" : { "post" : { "description" : "Reverts a cancellation: the event and all its occurrences are active again with their previous details, and the cancellation reason is cleared. No body. Uncancelling an event that is not cancelled changes nothing and answers `204`; a deleted event answers `404`.\n\nRequires plan `PRO` and scope `events:write`.", "operationId" : "uncancelEvent", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "eventId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Uncancel a calendar event", "tags" : [ "Events" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "events:write" } }, "/v1/tenants/{tenantId}/invitations" : { "post" : { "description" : "Sends an invitation e-mail. Requires tenant administrator rights.\n\nRequires plan `PLUS` and scope `members:write`.", "operationId" : "inviteMember", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/InviteMemberRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Invitation" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The address is already invited or a member" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Invite a person by e-mail address", "tags" : [ "Members" ], "x-klubraum-plan" : "PLUS", "x-klubraum-scope" : "members:write" } }, "/v1/tenants/{tenantId}/members" : { "get" : { "description" : "Returns active and inactive members (not pending invitations), sorted by last name. E-mail addresses are included only when the token's owner is a tenant administrator.\n\nRequires plan `PLUS` and scope `members:read`.", "operationId" : "listMembers", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfMember" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the members of a tenant", "tags" : [ "Members" ], "x-klubraum-plan" : "PLUS", "x-klubraum-scope" : "members:read" } }, "/v1/tenants/{tenantId}/members/{userId}" : { "delete" : { "description" : "Removes the membership. With `removeData=true` the member's data in this tenant is deleted as well; otherwise the member is kept as inactive. Requires tenant administrator rights.\n\nRequires plan `PLUS` and scope `members:write`.", "operationId" : "removeMember", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Also delete the member's data in this tenant", "in" : "query", "name" : "removeData", "required" : false, "schema" : { "default" : false, "type" : "boolean" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The member cannot be removed in its current state" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Remove a member from the tenant", "tags" : [ "Members" ], "x-klubraum-plan" : "PLUS", "x-klubraum-scope" : "members:write" } }, "/v1/tenants/{tenantId}/members/{userId}/roles" : { "get" : { "description" : "Returns the live roles the member holds, ordered by name. A role that was deleted after it was assigned is not reported (it would name a role nobody can read any more) but is still stored: undeleting the role makes it reappear here.\n\nA user who is not a member of this tenant is a `404`.\n\nServed from a read model that follows writes with a delay of a few seconds; the response of a write always reflects the write.\n\nRequires plan `PRO` and scope `members:read`.", "operationId" : "listMemberRoles", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfRole" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the roles of a member", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:read" }, "put" : { "description" : "Sets the member's roles to exactly `roleIds`: roles that are not listed are taken away, and an empty list removes all of them. Requires tenant administrator rights.\n\n`userId` must be an active member of this tenant (`404` otherwise). Every entry of `roleIds` must be a live role of this tenant; unknown ids, roles of another tenant and deleted roles are reported together as a `400` naming each offending entry (`roleIds[0]`).\n\nRequires plan `PRO` and scope `members:write`.", "operationId" : "setMemberRoles", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetMemberRolesRequest" } } }, "required" : true }, "responses" : { "204" : { "description" : "The roles were replaced" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Replace the roles of a member", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:write" } }, "/v1/tenants/{tenantId}/members/{userId}/roles/{roleId}" : { "delete" : { "description" : "Requires tenant administrator rights. Removing a role the member does not hold is not an error. The same `404` rules as for giving a role apply — to take a DELETED role away from a member, undelete it first or replace the member's role set with `PUT …/roles`.\n\nRequires plan `PRO` and scope `members:write`.", "operationId" : "removeMemberRole", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "roleId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Take a role away from a member", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:write" }, "put" : { "description" : "Requires tenant administrator rights. Assigning a role the member already holds is not an error.\n\n`userId` must be an active member of this tenant and `roleId` a live role of it — a user who is not, and a role that does not exist, belongs to another tenant or is deleted, are all a `404`.\n\nRequires plan `PRO` and scope `members:write`.", "operationId" : "addMemberRole", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "userId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "roleId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Give a role to a member", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:write" } }, "/v1/tenants/{tenantId}/ride-sharings/{rideSharingId}/messages" : { "post" : { "description" : "Like the conversation of an event occurrence, the conversation of a ride sharing is created by its FIRST message; `conversationCreated` tells you which of the two happened.\n\nWho may post is decided by the event the ride sharing belongs to: whoever may read that event may write here. Once the conversation exists, posting into it needs the right to READ it (`404` otherwise) and it must not be locked (`409`). A conversation created here inherits the event's visibility, exactly like the conversation of an event occurrence. Find the ride sharings of an occurrence with `GET /v1/tenants/{tenantId}/events/{eventId}/instances/{instanceId}/ride-sharings`.\n\nRequires plan `PRO` and scope `conversations:write`.", "operationId" : "postRideSharingMessage", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "rideSharingId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PostMessageRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PostedMessage" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The conversation of the ride sharing is locked" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Post a message to the conversation of a ride sharing", "tags" : [ "Conversations" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "conversations:write" } }, "/v1/tenants/{tenantId}/roles" : { "get" : { "description" : "Returns the tenant's live roles, ordered by name. Deleted roles are not part of this list; read one by id to see whether it exists but is deleted.\n\nRequires plan `PRO` and scope `members:read`.", "operationId" : "listRoles", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfRole" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the roles of a tenant", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:read" }, "post" : { "description" : "Creates a role in the tenant of the path; the token's owner is reported as `createdBy`. Requires tenant administrator rights.\n\n`name` is trimmed and must not collide with an existing **live** role of this tenant — the comparison ignores case and surrounding whitespace, and a collision is a `400` naming `name`. The name of a DELETED role is free to take again; if you want the old role back, undelete it instead.\n\nThe check reads the tenant's role list, so it is best-effort: two creates racing each other can both succeed. Roles are a small, administrator-managed set, so that is a trade we make knowingly.\n\nRequires plan `PRO` and scope `members:write`.", "operationId" : "createRole", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateRoleRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Role" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Create a role", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:write" } }, "/v1/tenants/{tenantId}/roles/{roleId}" : { "delete" : { "description" : "Requires tenant administrator rights. The role disappears from every list and can no longer be assigned, but it keeps its id and name so it can be undeleted. Deleting a role that is already deleted is not an error.\n\nMembers who hold the role keep it in their stored profile; `GET …/members/{userId}/roles` stops reporting it, and it comes back for everyone if the role is undeleted.\n\nRequires plan `PRO` and scope `members:write`.", "operationId" : "deleteRole", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "roleId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Delete a role", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:write" }, "get" : { "description" : "Reads one role of the tenant of the path, **including deleted ones** (`deleted: true`) — that is how you find out whether a role can be undeleted. A role of another tenant is a `404`, exactly like an unknown id.\n\nRequires plan `PRO` and scope `members:read`.", "operationId" : "getRole", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "roleId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Role" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Get a role", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:read" } }, "/v1/tenants/{tenantId}/roles/{roleId}/description" : { "delete" : { "description" : "Requires tenant administrator rights. Clearing an absent description is not an error.\n\nRequires plan `PRO` and scope `members:write`.", "operationId" : "clearRoleDescription", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "roleId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Role" } } }, "description" : "The role without its description" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The role is deleted; undelete it before changing it" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Clear the description of a role", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:write" }, "put" : { "description" : "Requires tenant administrator rights. A blank description is a `400` — use `DELETE` to clear it.\n\nRequires plan `PRO` and scope `members:write`.", "operationId" : "setRoleDescription", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "roleId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetRoleDescriptionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Role" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The role is deleted; undelete it before changing it" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Set the description of a role", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:write" } }, "/v1/tenants/{tenantId}/roles/{roleId}/name" : { "put" : { "description" : "Requires tenant administrator rights. The new name follows the same rules as on create; the role's own current name never collides with itself.\n\nRequires plan `PRO` and scope `members:write`.", "operationId" : "setRoleName", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "roleId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SetRoleNameRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Role" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The role is deleted; undelete it before changing it" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Rename a role", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:write" } }, "/v1/tenants/{tenantId}/roles/{roleId}/undelete" : { "post" : { "description" : "Brings a deleted role back, with its name, its description and every assignment it had. Requires tenant administrator rights. Undeleting a role that is not deleted is a `409`.\n\nRequires plan `PRO` and scope `members:write`.", "operationId" : "undeleteRole", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "roleId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Role" } } }, "description" : "The role, no longer deleted" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The role is not deleted" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Undelete a role", "tags" : [ "Roles" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "members:write" } }, "/v1/tenants/{tenantId}/surveys" : { "get" : { "description" : "Returns the surveys and polls of the whole tenant, newest first (by creation).\n\nDrafts and scheduled surveys are only listed for their creator and collaborators, deleted ones never; surveys that belong to a conversation, an event or a ride sharing are not part of this API and are left out. Private surveys never appear here — use `/surveys/mine`.\n\nRequires plan `PRO` and scope `surveys:read`.", "operationId" : "listSurveys", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfSurvey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the surveys of a tenant", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:read" }, "post" : { "description" : "Creates a survey (any number of questions) or a poll (exactly one question) in the tenant of the path. The token's owner is its creator.\n\nA new survey is a **draft** unless `activate` is set. With `activate` and a `schedule.start` in the future it becomes `SCHEDULED` and opens by itself; with `activate` and no future start it becomes `ACTIVE` right away. A survey without questions cannot be published.\n\n### Audience\n\n`context.type` picks who the survey is for, and it is **fixed at creation**.\n\n| `context.type` | who sees it | extra fields | permission |\n|---|---|---|---|\n| `TENANT` | everybody in the tenant | – | active member |\n| `AREAS` | everybody who may read the areas | `areaIds` (1–100) | the right to create surveys in **each** area |\n| `PRIVATE` | only the listed members | `participantIds` (1–500) | active member |\n\nEvery area must belong to `{tenantId}` and must not be archived; every participant must be an active member of it. Offending entries are reported as `context.areaIds[0]` and so on.\n\n### Questions\n\nEach entry of `questions` is tagged by its `type`. Question ids and choice ids are assigned by the server — do not send them.\n\n| `type` | answered with | required fields | rules |\n|---|---|---|---|\n| `BOOLEAN` | yes / no | – | – |\n| `CHOICE` | one or more of `choices` | `choices`, unless `allowCustomChoice` | `singleChoice` excludes `maxChoices` and `allowMultipleCustomChoices` |\n| `FREE_TEXT` | text | – | `maxTextLength` > 0 and ≥ `minTextLength` ≥ 0 |\n| `MEMBER` | one or more members | `memberIds`, unless `allMembers` or `allowCustomMember` | `allMembers` excludes `memberIds`, `allowCustomMember` and `allowMultipleCustomMembers`; `singleChoice` excludes `maxChoices` and `allowMultipleCustomMembers` |\n| `RATING` | a value on a scale | `minValue`, `maxValue` | `maxValue` > `minValue`, `stepSize` > 0, `maxValue - minValue` a multiple of it, `minLabel`/`maxLabel` only together |\n| `SCHEDULING` | one or more dates/times | `choices`, unless `allowCustomChoice` | `allowCustomChoice` needs at least one kind enabled in `customChoiceSettings`; `singleChoice` excludes `maxChoices` and `customChoiceSettings.allowMultiple` |\n\n`required` marks a question that has to be answered before the ones after it may be.\n\n### Visibility\n\n`settings` decides who sees what, on the ladder `NONE` < `CREATOR` < `COLLABORATORS` < `WRITE_ACCESS_USERS` < `PARTICIPANTS` < `MEMBERS` < `PUBLIC`. Narrower data must never be visible to a wider audience, so `liveResultVisibility` and `answerVisibility` must not be wider than `resultVisibility`, and `answererVisibility` must not be wider than `answerVisibility`. Everything defaults to `NONE` — a survey whose results nobody may see.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "createSurvey", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/CreateSurveyRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Create a survey or poll", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" } }, "/v1/tenants/{tenantId}/surveys/mine" : { "get" : { "description" : "Returns the surveys the token's owner created, collaborates on or is a private participant of — including their own drafts and scheduled surveys. Newest first (by creation).\n\nRequires plan `PRO` and scope `surveys:read`.", "operationId" : "listMySurveys", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "description" : "Page size", "in" : "query", "name" : "limit", "required" : false, "schema" : { "default" : 50, "format" : "int32", "maximum" : 200, "minimum" : 1, "type" : "integer" } }, { "description" : "Opaque cursor of the next page (`nextCursor` of the previous response)", "in" : "query", "name" : "cursor", "required" : false, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PageOfSurvey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "List the surveys of the token's owner", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:read" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}" : { "delete" : { "description" : "Deletes the survey with its questions and its answers. A deleted survey is gone from this API — every endpoint, this one included, then reports it as not found.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "deleteSurvey", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Delete a survey or poll", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" }, "get" : { "description" : "Returns the survey with its questions and settings, but never any answers — those are behind `/results` and `/answers`, which apply the visibility ladder.\n\nRequires plan `PRO` and scope `surveys:read`.", "operationId" : "getSurvey", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Get a survey or poll", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:read" }, "patch" : { "description" : "Absent fields are left untouched, `null` clears a field, a value sets it. Only the fields that actually change are written.\n\nThe audience, the type and the questions are not part of this body — the questions have their own endpoints. The visibility ordering (see \"Create a survey or poll\") is re-checked against the values the survey would have AFTER the patch, so lowering `resultVisibility` below a `answerVisibility` that stays untouched is a `400`.\n\nA running survey whose settings are frozen (`settings.immutable`) rejects every change with a `409`, and so do completed, archived and deleted surveys. `schedule.start` cannot be changed once the survey is active.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "patchSurvey", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PatchSurveyRequest" } }, "application/merge-patch+json" : { "schema" : { "$ref" : "#/components/schemas/PatchSurveyRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey is not in a state that allows the change" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Update a survey or poll (JSON Merge Patch)", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/activate" : { "post" : { "description" : "Turns a draft into a running survey — or, when `schedule.start` is still in the future, into a scheduled one that opens by itself. A survey without questions or one whose `schedule.end` has passed cannot be published; an already active survey is left as it is.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "activateSurvey", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey cannot be published in its current state" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Publish a survey or poll", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/answers" : { "get" : { "description" : "Returns the single answers per question, rather than the aggregate.\n\nThe three visibilities nest: the results have to be visible (see \"Get the aggregated results\") AND `settings.answerVisibility` has to be satisfied, or the call is a `403 forbidden`. Each answer carries its `answerer` only when `settings.answererVisibility` is satisfied as well — otherwise the answers are returned without one, which is how an anonymous survey works.\n\nRequires plan `PRO` and scope `surveys:read`.", "operationId" : "getAnswers", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SurveyAnswers" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Get the individual answers", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:read" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/answers/mine" : { "get" : { "description" : "Returns what the token's owner answered, one entry per answered question. Own answers are always visible — the visibility ladder only governs other people's.\n\nRequires plan `PRO` and scope `surveys:read`.", "operationId" : "getMyAnswers", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/MySurveyAnswers" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Get the answers of the token's owner", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:read" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/archive" : { "post" : { "description" : "Moves a completed survey out of the way; its results stay readable. Only a completed survey can be archived; archiving an archived one is accepted as it is.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "archiveSurvey", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey is not completed" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Archive a survey or poll", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/complete" : { "post" : { "description" : "Stops accepting answers and switches the survey to `COMPLETE`, which is when `resultVisibility` takes over from `liveResultVisibility`. Only a running survey can be completed; completing a completed one is accepted as it is.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "completeSurvey", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey is not running" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Close a survey or poll", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/questions" : { "post" : { "description" : "Appends a question. The same per-type rules as on create apply (see \"Create a survey or poll\"); its id and the ids of its choices are assigned by the server. A poll accepts exactly one question, so adding a second one is a `409`, and a running survey whose questions are frozen (`settings.immutable`) rejects the call.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "addQuestion", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AddQuestionRequest" } } }, "required" : true }, "responses" : { "201" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "Created" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey does not accept another question" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Add a question", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/questions/{questionId}" : { "delete" : { "description" : "Removes the question and the answers given to it. Deleting a question that is not there succeeds.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "deleteQuestion", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "questionId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey does not allow its questions to be changed" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Delete a question", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" }, "put" : { "description" : "Replaces the question at `{questionId}` — its type may change. Choices that already exist have to come back with their `choiceId`; a choice without one is created, and one that is left out is removed together with the answers pointing at it. `deleteData` throws the answers of this question away.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "updateQuestion", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "questionId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/UpdateQuestionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey does not allow its questions to be changed" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Replace a question", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/questions/{questionId}/answer" : { "delete" : { "description" : "Removes the answer the token's owner gave to this question. Only a running survey that allows revisions accepts it; withdrawing an answer that is not there succeeds.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "deleteAnswer", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "questionId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "204" : { "description" : "No Content" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey does not allow answers to be withdrawn" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Withdraw an answer", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" }, "put" : { "description" : "Records the answer of the token's owner — there is no way to answer for somebody else. Answering twice replaces the earlier answer, but only when the survey allows revisions; otherwise the second call is a `409`. Only a running survey accepts answers.\n\nThe body's `type` has to match the question's, and the value has to satisfy the question:\n\n| `type` | body | checked against the question |\n|---|---|---|\n| `BOOLEAN` | `value` | – |\n| `CHOICE` | `choiceIds`, `customChoices` | ids are choices of the question; custom choices only when allowed, one only unless several are; `singleChoice` / `maxChoices` |\n| `FREE_TEXT` | `value` | not blank, within `minTextLength` / `maxTextLength` |\n| `MEMBER` | `memberIds`, `customMemberIds` | ids are offered by the question unless it offers all members; custom members only when allowed and never one already offered |\n| `RATING` | `value` | between `minValue` and `maxValue`, on the `stepSize` grid |\n| `SCHEDULING` | `choiceIds`, `customChoices` | ids are choices of the question; custom dates/times only of the enabled kinds and inside the allowed ranges |\n\nQuestions are answered in order: while an earlier `required` question is unanswered the later ones cannot be answered (`409`).\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "putAnswer", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "questionId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AnswerInput" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Answer" } } }, "description" : "The answer as it was recorded" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey does not accept this answer right now" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Answer a question", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/questions/{questionId}/move" : { "post" : { "description" : "Moves the question to `index`, counted from zero. The order matters: a `required` question has to be answered before the ones after it may be.\n\nRequires plan `PRO` and scope `surveys:write`.", "operationId" : "moveQuestion", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "questionId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/MoveQuestionRequest" } } }, "required" : true }, "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Survey" } } }, "description" : "The survey with the question in its new place" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "409" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The survey does not allow its questions to be changed" }, "413" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body exceeds 256 KB (`payload_too_large`)" }, "415" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "The body is not `application/json` (`unsupported_media_type`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Move a question", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:write" } }, "/v1/tenants/{tenantId}/surveys/{surveyId}/results" : { "get" : { "description" : "Returns one aggregate per question — how often each choice was picked, how the ratings are distributed, and so on. The counts are zero while nobody has answered.\n\n### Who may see them\n\nThe survey's state decides WHICH setting applies, and the setting decides who satisfies it. A caller who does not is answered with `403 forbidden` — the survey itself stays readable.\n\n| state | setting that applies |\n|---|---|\n| `DRAFT`, `SCHEDULED`, `DELETED` | nobody |\n| `ACTIVE` | `settings.liveResultVisibility` |\n| `COMPLETE`, `ARCHIVED` | `settings.resultVisibility` |\n\n| setting | who satisfies it |\n|---|---|\n| `NONE` | nobody |\n| `CREATOR` | the creator |\n| `COLLABORATORS` | the creator and the collaborators |\n| `WRITE_ACCESS_USERS` | … and everybody who may edit the survey |\n| `PARTICIPANTS` | … and everybody who answered every `required` question |\n| `MEMBERS`, `PUBLIC` | everybody who may read the survey |\n\nRequires plan `PRO` and scope `surveys:read`.", "operationId" : "getResults", "parameters" : [ { "in" : "path", "name" : "tenantId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } }, { "in" : "path", "name" : "surveyId", "required" : true, "schema" : { "format" : "uuid", "type" : "string" } } ], "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SurveyResults" } } }, "description" : "OK" }, "400" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Invalid parameters or body (`validation_failed`); `errors` names the fields" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Get the aggregated results", "tags" : [ "Surveys" ], "x-klubraum-plan" : "PRO", "x-klubraum-scope" : "surveys:read" } }, "/v1/token" : { "get" : { "description" : "Returns the token's owner, tenant, scopes, the tenant's plan (`PLUS`, `PRO` or `FREE`) and the expiry.", "operationId" : "describeToken", "responses" : { "200" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/PersonalAccessTokenInfo" } } }, "description" : "OK" }, "401" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Missing, invalid, expired or revoked token (`unauthenticated`, `token_expired`, `token_revoked`)" }, "403" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Not allowed (`tenant_mismatch`, `tenant_unavailable`, `plan_required`, `insufficient_scope`, `forbidden`)" }, "404" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "No such endpoint or resource — also for resources the token may not read (`not_found`)" }, "429" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Rate limit exceeded (`rate_limited`); honour `Retry-After` and the `RateLimit-*` headers" }, "500" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "Unexpected error (`internal_error`)" }, "503" : { "content" : { "application/problem+json" : { "schema" : { "$ref" : "#/components/schemas/Problem" } } }, "description" : "A backend is temporarily unavailable (`service_unavailable`); retry after `Retry-After`" } }, "security" : [ { "personalAccessToken" : [ ] } ], "summary" : "Describe the personal access token you're calling with", "tags" : [ "Token" ] } } }, "servers" : [ { "description" : "Production", "url" : "https://api.klubraum.com" }, { "description" : "Development / staging", "url" : "https://api.dev.klubraum.com" } ], "tags" : [ { "description" : "The personal access token you're calling with.", "name" : "Token" }, { "description" : "Members and invitations of a tenant (Plus plan).", "name" : "Members" }, { "description" : "Calendar events and their occurrences (Pro plan).", "name" : "Events" }, { "description" : "Areas of a tenant, their members, administrators and capabilities (Pro plan).", "name" : "Areas" }, { "description" : "Groups that bundle areas for the app's navigation (Pro plan).", "name" : "Area groups" }, { "description" : "Tenant roles and the roles assigned to a member (Pro plan, `members:*` scopes).", "name" : "Roles" }, { "description" : "Conversations of a tenant, an area or a private circle, and their messages (Pro plan).", "name" : "Conversations" }, { "description" : "Surveys and polls, their questions, answers and results (Pro plan).", "name" : "Surveys" } ] }