> For the complete documentation index, see [llms.txt](https://help.paintscout.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.paintscout.com/developers/events.md).

# Events

## GET /events

> List Events

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Event":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","nullable":false,"description":"The unique ID of the Event. Ignored when creating new events."},"eventType":{"type":"string","nullable":false,"description":"The type of Event: the key or label of one of the company's event types (see `GET /settings/eventTypes`). A value that matches no type returns a 400 that lists the valid labels. When creating, leaving it out uses the company's first event type. When updating, leaving it out keeps the event's current type."},"dealId":{"type":"string","nullable":false,"description":"The deal ID this event is associated with"},"address":{"type":"string","nullable":true,"description":"The address"},"note":{"type":"string","nullable":true,"description":"A note about this event"},"canceled":{"type":"boolean","nullable":true,"description":"Whether the event has been canceled"},"sendReminderEmails":{"type":"boolean","nullable":true,"description":"Whether the deal contact gets the 1-day and 1-hour reminder emails for this event. Defaults to false when not sent on create, because the API sends no confirmation, reschedule or cancellation email. An update that does not send it keeps the stored value. The company reminder template and the contact email address must also be set for a reminder to send. Setting it never sends a confirmation email."},"progress":{"type":"number","nullable":true,"description":"Percent complete of a production event, 0-100. Omitted when 0."},"production":{"type":"boolean","nullable":true,"description":"Whether this is a production event, which is what makes progress meaningful. Omitted when false."},"owner":{"type":"object","nullable":true,"$ref":"#/components/schemas/Owner"},"crew":{"type":"object","nullable":true,"readOnly":true,"description":"The crew booked on this event. Null when no crew is set. Read-only.","properties":{"id":{"type":"string","description":"The crew ID"},"name":{"type":"string","description":"The crew name"}}},"assignedUsers":{"type":"array","readOnly":true,"description":"The users assigned to work this event. Read-only.","items":{"type":"object","properties":{"id":{"type":"string","description":"The user ID"},"name":{"type":"string","description":"The user name, when the event stores it"}}}},"timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"When this event was created, in epoch milliseconds"},"updated":{"type":"number","description":"When this event was last updated, in epoch milliseconds"},"start":{"type":"number","description":"When this event is scheduled to start, in epoch milliseconds (for example 1768485600000, not 1768485600). The API rounds start to the nearest 30 minutes, the same as the app: 14:14 becomes 14:00 and 14:15 becomes 14:30. An event must be at least 30 minutes long, so end must be at least 30 minutes after start."},"end":{"type":"number","description":"When this event is scheduled to end, in epoch milliseconds (for example 1768491000000, not 1768491000). The API rounds end to the nearest 30 minutes, the same as the app: 15:44 becomes 15:30 and 15:45 becomes 16:00. An event must be at least 30 minutes long, so end must be at least 30 minutes after start."}}}}},"Owner":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/events":{"get":{"summary":"List Events","operationId":"listEvents","tags":["Events"],"parameters":[{"name":"page","in":"query","description":"Page number to fetch, 1-indexed. Defaults to 1.","schema":{"type":"integer","format":"int32","minimum":1}},{"name":"perPage","in":"query","description":"Number of results per page (1-100). Defaults to the API's standard page size if omitted.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":100}},{"name":"query","in":"query","allowReserved":true,"description":"Lucene-style filter query (e.g. `status:active AND createdAt:[2024-01-01 TO *]`). Field names match the Event object's own fields. This syntax is part of an in-flight migration (see `docs/design/lucene-migration-json-filter-spec.md`) and may change.","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Field name to sort by. One of `id`, `eventType`, `dealId`, `address`, `canceled`, `progress`, `production`, `timestamp.created`, `timestamp.updated`, `timestamp.start`, `timestamp.end` (aliases: `createdDate`, `updatedDate`, `startDate`, `endDate`). `createdAt`, `updatedAt` and `start` are accepted for `timestamp.created`, `timestamp.updated` and `timestamp.start`. A `:asc` or `:desc` suffix (e.g. `timestamp.updated:desc`) sets the direction, and a leading `-` (e.g. `-timestamp.updated`) means descending. Either one overrides `sortDir`, and the suffix wins over the prefix. Any other field returns a 400. Defaults to `timestamp.updated`.","schema":{"type":"string"}},{"name":"sortDir","in":"query","description":"Sort direction: `asc` or `desc`. Only takes effect when `sort` is set.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"List of events","content":{"application/json":{"schema":{"type":"object","properties":{"totalRows":{"type":"number"},"page":{"type":"number"},"perPage":{"type":"number"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## POST /events

> Create Event

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Event":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","nullable":false,"description":"The unique ID of the Event. Ignored when creating new events."},"eventType":{"type":"string","nullable":false,"description":"The type of Event: the key or label of one of the company's event types (see `GET /settings/eventTypes`). A value that matches no type returns a 400 that lists the valid labels. When creating, leaving it out uses the company's first event type. When updating, leaving it out keeps the event's current type."},"dealId":{"type":"string","nullable":false,"description":"The deal ID this event is associated with"},"address":{"type":"string","nullable":true,"description":"The address"},"note":{"type":"string","nullable":true,"description":"A note about this event"},"canceled":{"type":"boolean","nullable":true,"description":"Whether the event has been canceled"},"sendReminderEmails":{"type":"boolean","nullable":true,"description":"Whether the deal contact gets the 1-day and 1-hour reminder emails for this event. Defaults to false when not sent on create, because the API sends no confirmation, reschedule or cancellation email. An update that does not send it keeps the stored value. The company reminder template and the contact email address must also be set for a reminder to send. Setting it never sends a confirmation email."},"progress":{"type":"number","nullable":true,"description":"Percent complete of a production event, 0-100. Omitted when 0."},"production":{"type":"boolean","nullable":true,"description":"Whether this is a production event, which is what makes progress meaningful. Omitted when false."},"owner":{"type":"object","nullable":true,"$ref":"#/components/schemas/Owner"},"crew":{"type":"object","nullable":true,"readOnly":true,"description":"The crew booked on this event. Null when no crew is set. Read-only.","properties":{"id":{"type":"string","description":"The crew ID"},"name":{"type":"string","description":"The crew name"}}},"assignedUsers":{"type":"array","readOnly":true,"description":"The users assigned to work this event. Read-only.","items":{"type":"object","properties":{"id":{"type":"string","description":"The user ID"},"name":{"type":"string","description":"The user name, when the event stores it"}}}},"timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"When this event was created, in epoch milliseconds"},"updated":{"type":"number","description":"When this event was last updated, in epoch milliseconds"},"start":{"type":"number","description":"When this event is scheduled to start, in epoch milliseconds (for example 1768485600000, not 1768485600). The API rounds start to the nearest 30 minutes, the same as the app: 14:14 becomes 14:00 and 14:15 becomes 14:30. An event must be at least 30 minutes long, so end must be at least 30 minutes after start."},"end":{"type":"number","description":"When this event is scheduled to end, in epoch milliseconds (for example 1768491000000, not 1768491000). The API rounds end to the nearest 30 minutes, the same as the app: 15:44 becomes 15:30 and 15:45 becomes 16:00. An event must be at least 30 minutes long, so end must be at least 30 minutes after start."}}}}},"Owner":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/events":{"post":{"summary":"Create Event","operationId":"createEvent","tags":["Events"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Details about the new Event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## GET /events/{id}

> Retrieve Event

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Event":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","nullable":false,"description":"The unique ID of the Event. Ignored when creating new events."},"eventType":{"type":"string","nullable":false,"description":"The type of Event: the key or label of one of the company's event types (see `GET /settings/eventTypes`). A value that matches no type returns a 400 that lists the valid labels. When creating, leaving it out uses the company's first event type. When updating, leaving it out keeps the event's current type."},"dealId":{"type":"string","nullable":false,"description":"The deal ID this event is associated with"},"address":{"type":"string","nullable":true,"description":"The address"},"note":{"type":"string","nullable":true,"description":"A note about this event"},"canceled":{"type":"boolean","nullable":true,"description":"Whether the event has been canceled"},"sendReminderEmails":{"type":"boolean","nullable":true,"description":"Whether the deal contact gets the 1-day and 1-hour reminder emails for this event. Defaults to false when not sent on create, because the API sends no confirmation, reschedule or cancellation email. An update that does not send it keeps the stored value. The company reminder template and the contact email address must also be set for a reminder to send. Setting it never sends a confirmation email."},"progress":{"type":"number","nullable":true,"description":"Percent complete of a production event, 0-100. Omitted when 0."},"production":{"type":"boolean","nullable":true,"description":"Whether this is a production event, which is what makes progress meaningful. Omitted when false."},"owner":{"type":"object","nullable":true,"$ref":"#/components/schemas/Owner"},"crew":{"type":"object","nullable":true,"readOnly":true,"description":"The crew booked on this event. Null when no crew is set. Read-only.","properties":{"id":{"type":"string","description":"The crew ID"},"name":{"type":"string","description":"The crew name"}}},"assignedUsers":{"type":"array","readOnly":true,"description":"The users assigned to work this event. Read-only.","items":{"type":"object","properties":{"id":{"type":"string","description":"The user ID"},"name":{"type":"string","description":"The user name, when the event stores it"}}}},"timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"When this event was created, in epoch milliseconds"},"updated":{"type":"number","description":"When this event was last updated, in epoch milliseconds"},"start":{"type":"number","description":"When this event is scheduled to start, in epoch milliseconds (for example 1768485600000, not 1768485600). The API rounds start to the nearest 30 minutes, the same as the app: 14:14 becomes 14:00 and 14:15 becomes 14:30. An event must be at least 30 minutes long, so end must be at least 30 minutes after start."},"end":{"type":"number","description":"When this event is scheduled to end, in epoch milliseconds (for example 1768491000000, not 1768491000). The API rounds end to the nearest 30 minutes, the same as the app: 15:44 becomes 15:30 and 15:45 becomes 16:00. An event must be at least 30 minutes long, so end must be at least 30 minutes after start."}}}}},"Owner":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/events/{id}":{"get":{"summary":"Retrieve Event","operationId":"getEvent","tags":["Events"],"parameters":[{"name":"id","in":"path","description":"ID of the Event","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Details about the event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## PUT /events/{id}

> Update Event

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Event":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","nullable":false,"description":"The unique ID of the Event. Ignored when creating new events."},"eventType":{"type":"string","nullable":false,"description":"The type of Event: the key or label of one of the company's event types (see `GET /settings/eventTypes`). A value that matches no type returns a 400 that lists the valid labels. When creating, leaving it out uses the company's first event type. When updating, leaving it out keeps the event's current type."},"dealId":{"type":"string","nullable":false,"description":"The deal ID this event is associated with"},"address":{"type":"string","nullable":true,"description":"The address"},"note":{"type":"string","nullable":true,"description":"A note about this event"},"canceled":{"type":"boolean","nullable":true,"description":"Whether the event has been canceled"},"sendReminderEmails":{"type":"boolean","nullable":true,"description":"Whether the deal contact gets the 1-day and 1-hour reminder emails for this event. Defaults to false when not sent on create, because the API sends no confirmation, reschedule or cancellation email. An update that does not send it keeps the stored value. The company reminder template and the contact email address must also be set for a reminder to send. Setting it never sends a confirmation email."},"progress":{"type":"number","nullable":true,"description":"Percent complete of a production event, 0-100. Omitted when 0."},"production":{"type":"boolean","nullable":true,"description":"Whether this is a production event, which is what makes progress meaningful. Omitted when false."},"owner":{"type":"object","nullable":true,"$ref":"#/components/schemas/Owner"},"crew":{"type":"object","nullable":true,"readOnly":true,"description":"The crew booked on this event. Null when no crew is set. Read-only.","properties":{"id":{"type":"string","description":"The crew ID"},"name":{"type":"string","description":"The crew name"}}},"assignedUsers":{"type":"array","readOnly":true,"description":"The users assigned to work this event. Read-only.","items":{"type":"object","properties":{"id":{"type":"string","description":"The user ID"},"name":{"type":"string","description":"The user name, when the event stores it"}}}},"timestamp":{"type":"object","additionalProperties":false,"properties":{"created":{"type":"number","description":"When this event was created, in epoch milliseconds"},"updated":{"type":"number","description":"When this event was last updated, in epoch milliseconds"},"start":{"type":"number","description":"When this event is scheduled to start, in epoch milliseconds (for example 1768485600000, not 1768485600). The API rounds start to the nearest 30 minutes, the same as the app: 14:14 becomes 14:00 and 14:15 becomes 14:30. An event must be at least 30 minutes long, so end must be at least 30 minutes after start."},"end":{"type":"number","description":"When this event is scheduled to end, in epoch milliseconds (for example 1768491000000, not 1768491000). The API rounds end to the nearest 30 minutes, the same as the app: 15:44 becomes 15:30 and 15:45 becomes 16:00. An event must be at least 30 minutes long, so end must be at least 30 minutes after start."}}}}},"Owner":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"The unique user ID"},"firstName":{"type":"string","description":"The first name of the user"},"lastName":{"type":"string","description":"The last name of the user"},"title":{"type":"string","description":"The job title of the user"},"email":{"type":"string","description":"The email address of the user"},"phoneNumber":{"type":"string","nullable":true,"description":"The phone number of the user"},"phoneExtension":{"type":"string","nullable":true,"description":"The phone extension of the user"}}},"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/events/{id}":{"put":{"summary":"Update Event","parameters":[{"name":"id","in":"path","description":"ID of the Event","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"operationId":"updateEvent","tags":["Events"],"responses":{"200":{"description":"The updated event","content":{"application/json":{"schema":{"additionalProperties":false,"$ref":"#/components/schemas/Event"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## DELETE /events/{id}

> Delete Event

```json
{"openapi":"3.0.0","info":{"title":"Core API","version":"v2"},"servers":[{"url":"https://openapi.paintscout.com/v2"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","additionalProperties":false,"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Array of error messages"}}}}},"paths":{"/events/{id}":{"delete":{"summary":"Delete Event","parameters":[{"name":"id","in":"path","description":"ID of the Event","required":true,"schema":{"type":"string"}}],"operationId":"deleteEvent","tags":["Events"],"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Not Authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.paintscout.com/developers/events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
