# `event_create`

**Create calendar event.** Creates a calendar event.

**Who can use it:** Owners and managers with a role in the community. Not yet a management company's owners and managers.

| Scope | Effect | Hints |
|---|---|---|
| `community:write` | send (write when `visibility` is `staff_only`) | changes data, destructive |

## Description shown to assistants

> Use this when an owner or manager asks to create or schedule a PorchQ calendar event.

## Arguments

| Argument | Type | Required | About |
|---|---|---|---|
| `property_id` | string | No | The community's public id (`prop_web…`). Pass it on every call. |
| `title` | string | Yes | The event's name. |
| `description` | string | No | What the event is about. |
| `location` | string | No | Where it happens. |
| `starts_at` | string | No | ISO8601 event start time. Include a timezone offset when possible. |
| `starts_at_text` | string | No | Original natural-language start time when the user used relative wording. |
| `ends_at` | string | No | ISO8601 event end time. Include a timezone offset when possible. |
| `ends_at_text` | string | No | Original natural-language end time when the user used relative wording. |
| `all_day` | boolean | No | The event lasts all day. |
| `event_type` | string | No | One of `meeting`, `community_event`, `maintenance`, `voting_deadline`, `other`. |
| `visibility` | string | No | One of `public`, `members_only`, `staff_only`. |
| `reminder_offsets_minutes` | array of integer | No | Minutes before the start at which members who can see the event get a reminder. Each from 1 to 43200. |
| `idempotency_key` | string | No | Optional. A unique value for this change; sending the same value again does nothing twice. At most 200 characters. |

## What it returns

Every result has `content` (one short sentence for the person) and `structuredContent` (the data below). A tool that could not run answers with `isError: true` and a sentence saying why; see [Errors and limits](/developers/mcp/errors-and-limits).

- `property`: the community.
- `status`: `done` when the change was made at once (a staff-only event), or `awaiting_confirmation`.
- `event`: the event, when `status` is `done`, with the same fields as in `events_list`.
- `confirmation`: when `status` is `awaiting_confirmation`, the `url` of the PorchQ page where the person confirms and when it `expires_at`.

`structuredContent` follows this JSON Schema, also in `tools/list` as `outputSchema`:

```json
{
  "type": "object",
  "properties": {
    "property": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "addressLine1": { "type": ["string", "null"] },
        "addressLine2": { "type": ["string", "null"] },
        "city": { "type": ["string", "null"] },
        "state": { "type": ["string", "null"] },
        "postalCode": { "type": ["string", "null"] },
        "timezone": { "type": ["string", "null"] },
        "billingFrequency": { "type": ["string", "null"] },
        "demoClone": { "type": "boolean" },
        "demoPersona": { "type": ["string", "null"] },
        "demoExpiresAt": { "type": ["string", "null"] }
      },
      "required": ["id", "name"]
    },
    "status": { "enum": ["done", "awaiting_confirmation"] },
    "event": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "title": { "type": "string" },
        "description": { "type": ["string", "null"] },
        "location": { "type": ["string", "null"] },
        "starts_at": { "type": ["string", "null"] },
        "ends_at": { "type": ["string", "null"] },
        "all_day": { "type": ["boolean", "null"] },
        "event_type": { "type": ["string", "null"] },
        "visibility": { "type": ["string", "null"] },
        "reminder_offsets_minutes": { "type": ["array", "null"], "items": { "type": "integer" } },
        "created_via": { "type": ["string", "null"] }
      },
      "required": ["id", "title"],
      "description": "The event, when it was created or changed at once."
    },
    "confirmation": {
      "type": "object",
      "description": "When the change waits for the person to confirm it in PorchQ.",
      "properties": { "url": { "type": "string" }, "expires_at": { "type": "string" } },
      "required": ["url", "expires_at"]
    }
  },
  "required": ["property", "status"]
}
```

## Notes

- `visibility` decides who sees it: `public` (members and the community's public website), `members_only` or `staff_only`.
- **An event residents can see waits for the person to confirm it in PorchQ.** It reaches members (reminders by email and in the PorchQ app, and a public event on the community's website), so nothing happens until the person who asked opens the link and confirms. Pass the tool's sentence on to them as it is. See [Confirming changes](/developers/mcp/permissions#confirming-changes). Such a call is recorded as **send**.
- A staff-only event is created at once and recorded as **write**.
- Give `starts_at` (and `ends_at`) as ISO 8601 with a time-zone offset. When the person used words like "next Tuesday at 7", also pass them as `starts_at_text`; PorchQ reads them in the community's time zone. A time without an offset is read in the community's time zone too.
- Without them, `event_type` is `community_event` and `visibility` is `members_only`.

## Example

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "event_create",
    "arguments": {
      "property_id": "prop_web4k2m9q7x1v8c3n5b6z0a2s4d",
      "title": "Annual meeting",
      "starts_at": "2026-11-12T19:00:00-08:00",
      "ends_at": "2026-11-12T20:30:00-08:00",
      "location": "Clubhouse",
      "event_type": "meeting",
      "visibility": "members_only",
      "reminder_offsets_minutes": [
        1440,
        60
      ],
      "idempotency_key": "0b9e5a51-4f4a-4b8c-8a4e-3f0d2f5c7e19"
    }
  }
}
```