Create meeting
create_meetingCreate a meeting in a project with specified start time, duration, and optional participants. Receive validation errors for permission or scheduling problems.
Instructions
Schedule a meeting in a project and optionally invite participants.
Use it for "book a review on Thursday" style requests. The call goes through
POST /meetings/form first, so a missing permission, an impossible time or a
participant who cannot see the project comes back as violations naming the attribute
instead of an opaque rejection.
Returns the created meeting in the same shape as get_meeting (its agenda_items are
empty — add them with add_meeting_agenda_item).
Pitfalls. Check state in the result: current OpenProject versions create meetings as
'draft', which means participants do not see it until it is opened —
update_meeting(meeting_id=..., state='open') publishes it, exactly as the UI does.
Invitation emails are not sent by an API create. start_time needs a timezone — the
server stores an instant, not a wall-clock time. Recurring meetings cannot be created
through this tool — use create_recurring_meeting.
Cross-references: add_meeting_agenda_item(meeting_id=...) to build the agenda;
get_meeting to read it back; list_projects for the project id; search_principals (or
list_project_memberships) for participant ids.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Meeting title, e.g. 'Sprint 12 planning'. | |
| project_id | Yes | Numeric id or identifier of the project the meeting belongs to. It must have the Meetings module enabled and this account needs the 'create meetings' permission in it. | |
| start_time | Yes | Start as ISO 8601 WITH a timezone: '2026-08-03T14:00:00Z' (UTC) or '2026-08-03T16:00:00+02:00'. A time without an offset is rejected locally rather than booked in the wrong hour. | |
| participants | No | User ids to invite, from search_principals or a project's memberships. Every one of them needs 'view meetings' in the project or the create is rejected. Omit to let OpenProject invite only the author. | |
| duration_minutes | Yes | Scheduled length in minutes (90 = one and a half hours). Sent as the API's ISO duration; the result reports it back as duration_hours. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Meeting id — what get_meeting and add_meeting_agenda_item take. | |
| notes | No | Degradation notes: agenda items that could not be read, work packages this account may not see. | |
| state | No | Lifecycle state: 'draft' (not yet opened to participants), 'open', 'in_progress', 'closed' or 'cancelled'. Cancelled meetings are excluded from listings. | |
| title | No | Meeting title. | |
| author | No | User who created the meeting. | |
| project | No | Project the meeting belongs to. | |
| end_time | No | ISO 8601 UTC end timestamp, derived from start plus duration. | |
| location | No | Room name or meeting URL as typed by the organizer. | |
| created_at | No | ISO 8601 UTC timestamp. | |
| start_time | No | ISO 8601 UTC start timestamp; null for an undated meeting. | |
| updated_at | No | ISO 8601 UTC timestamp. | |
| agenda_items | No | The agenda in order; always a list. Empty means either no agenda or an unreadable one — check 'notes' before concluding the meeting had none. | |
| lock_version | No | Optimistic-lock version. Echo it as update_meeting's lock_version so a concurrent edit fails loudly (409) instead of being overwritten. | |
| participants | No | Invited users; always a list. Attendance is not exposed by API v3. | |
| duration_hours | No | Scheduled length in hours (1.5 = 90 minutes); the wire sends an ISO duration, which is converted here. |