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

# Meetings

Here's how to manage meetings

### The Meeting object

```json
// Meeting
{
    "id": "me_dd3b6aa3",
    "person_id": 40, // Author of the meeting
    "title": "Special Board Meeting",
    "description": "The meeting where budgets are decided and voted on",
    "notes": "The meeting went well",
    "status": "public", // enum: draft | public | archived
    "categories": [3, 15, 29],
    "department_id": 4,
    "starts_at": "2023-02-18T01:50:00.000Z", // Meeting DateTime in UTC
    "metadata": {}, // object that can hold extra data for meetings
    "created_at": "2023-04-20T06:52:10.000Z",
    "updated_at": "2023-04-21T09:34:03.000Z",

    // agenda data
    "agenda_status": "draft", // enum: draft | in_review | public | amended
    "agenda_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/2022-04-19-forestville-annual-town-meeting-agenda.pdf", // public url of agenda file
    "agenda_text": "MORGAN\nCITY COUNCIL\nAGENDA\nJANUARY\n24\n, 2023\n–\n6\n:\n00\nP...", // text extracted from agenda file

    // minutes data
    "minutes_status": "done", // Minutes generated by HeyGov: not-started, generating, done, manual-upload

    // additional files
    "agenda_pack_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/pack.pdf", // agenda pack file url
    "meeting_minutes_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/uploaded-minutes.pdf", // meeting minutes file url
    "additional_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/Additional Doc.docx", // url of uploaded file

    // Meeting media
    "audio_file_url": "https://files.heygov.com/heyville.org/meetings/me_dd3b6aa3/april-19-2022-forestville-wisconsin-town-board-meeting-video-recording.mp3", 
    "audio_public_url": "https://soundcloud.com/the-meeting",
    "video_file_url": "heyville.org/meetings/me_dd3b6aa3/april-19-2022-forestville-wisconsin-town-board-meeting-video-recording.mp4",
    "video_public_url": "https://www.youtube.com/watch?v=2PvkBKUBBj8"
}
```

### Endpoints

## List meetings in a municipality

<mark style="color:blue;">`GET`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings`

#### Path Parameters

| Name                                               | Type   | Description                 |
| -------------------------------------------------- | ------ | --------------------------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String | The ID for the municipality |

#### Query Parameters

| Name               | Type   | Description                                                                                                                |
| ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| date\_start\_local | String | Return meetings from this date (inclusive) onward. Format = YYYY-MM-DD                                                     |
| date\_end\_local   | String | Return meetings until this date (inclusive). Format = YYYY-MM-DD                                                           |
| limit              | Number | A limit on the number of meetings to be returned. Limit can range between 1 and 100, and the default is 10.                |
| page               | Number | Which page of meetings to return. Default is 1                                                                             |
| expand             | String | Expand entities to full object results. Entities that can be expanded for meetings: `department, agenda_items, categories` |
| status             | String | Filter meetings by status. Options: `draft`, `public`, `archived`, `deleted`                                               |
| order\_by          | String | Order meetings by: `title`, `status`, `starts_at`, `created_at`, `updated_at`. Default: `starts_at`                        |
| order              | String | Sort order for the `order_by` field. `asc` or `desc` (default)                                                             |
| q                  | String | Search query for meeting title                                                                                             |

{% tabs %}
{% tab title="200: OK List of meetings" %}

{% endtab %}
{% endtabs %}

## Create a meeting

<mark style="color:green;">`POST`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings`

#### Path Parameters

| Name                                               | Type   | Description                        |
| -------------------------------------------------- | ------ | ---------------------------------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String | The unique ID for the jurisdiction |

#### Request Body

| Name                                                | Type     | Description                                   |
| --------------------------------------------------- | -------- | --------------------------------------------- |
| title<mark style="color:red;">\*</mark>             | String   | Title of the meeting                          |
| description                                         | String   | Meeting description                           |
| starts\_at\_local<mark style="color:red;">\*</mark> | Datetime | Meeting date & time, in jurisdiction timezone |
| department\_id                                      | Number   | ID of the department owning this meeting      |

{% tabs %}
{% tab title="201: Created Meeting is created & object with ID is returned" %}

{% endtab %}

{% tab title="400: Bad Request Meeting fields are missing or invalid" %}

{% endtab %}
{% endtabs %}

## Create a meeting from an agenda file

<mark style="color:green;">`POST`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/create-from-agenda`

This endpoint extracts the meeting details (title, date, description, agenda items, etc) from the uploaded file

#### Path Parameters

| Name                                               | Type   | Description                 |
| -------------------------------------------------- | ------ | --------------------------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String | ID of the town/city/village |

#### Request Body

| Name                                   | Type | Description                               |
| -------------------------------------- | ---- | ----------------------------------------- |
| file<mark style="color:red;">\*</mark> | File | Meeting Agenda file in PDF or text format |

{% tabs %}
{% tab title="201: Created Meeting is created & object with ID is returned" %}

{% endtab %}
{% endtabs %}

## Retrieve a meeting

<mark style="color:blue;">`GET`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}`

Get full details for a meeting

#### Path Parameters

| Name                                               | Type   | Description                            |
| -------------------------------------------------- | ------ | -------------------------------------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String | ID of the HeyGov account               |
| meeting\_id<mark style="color:red;">\*</mark>      | String | ID of the meeting, starting with `me_` |

#### Query Parameters

| Name   | Type   | Description                                                                                                                |
| ------ | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| expand | String | Expand entities to full object results. Entities that can be expanded for meetings: `department, agenda_items, categories` |

{% tabs %}
{% tab title="200: OK Return meeting object" %}

{% endtab %}

{% tab title="404: Not Found Meeting with specified ID not found" %}

{% endtab %}
{% endtabs %}

## Edit meeting details

<mark style="color:orange;">`PUT`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}`

Modify meeting fields

#### Path Parameters

| Name                                               | Type   | Description                            |
| -------------------------------------------------- | ------ | -------------------------------------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String |                                        |
| meeting\_id<mark style="color:red;">\*</mark>      | String | ID of the meeting, starting with `me_` |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

## Delete meeting

<mark style="color:red;">`DELETE`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}`

Fully and irreversibly delete a meeting, meeting files, agenda items and minutes

#### Path Parameters

| Name                                               | Type   | Description                            |
| -------------------------------------------------- | ------ | -------------------------------------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String | ID for needed jurisdiction             |
| meeting\_id                                        | String | ID of the meeting, starting with `me_` |

{% tabs %}
{% tab title="200: OK Meeting and linked data are deleted" %}

{% endtab %}
{% endtabs %}

#### Files endpoints

Use these endpoints to upload different files needed for a meeting

## Upload meeting agenda file for a meeting

<mark style="color:green;">`POST`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/upload-agenda-file`

Upload an existing agenda for a meeting. Agenda items will be extracted and created automatically

#### Path Parameters

| Name                                               | Type   | Description                            |
| -------------------------------------------------- | ------ | -------------------------------------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String | Town/City ID                           |
| meeting\_id<mark style="color:red;">\*</mark>      | String | ID of the meeting, starting with `me_` |

#### Query Parameters

| Name              | Type    | Description                                                |
| ----------------- | ------- | ---------------------------------------------------------- |
| await\_processing | Boolean | `0` or `1` to await agenda processing or not. Default: `0` |

#### Request Body

| Name                                   | Type | Description                      |
| -------------------------------------- | ---- | -------------------------------- |
| file<mark style="color:red;">\*</mark> | File | Agenda file in PDF or txt format |

## Upload the agenda pack

<mark style="color:green;">`POST`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/upload-agenda-pack-file`

#### Path Parameters

| Name                                               | Type   | Description |
| -------------------------------------------------- | ------ | ----------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String |             |
| meeting\_id<mark style="color:red;">\*</mark>      | String |             |

#### Request Body

| Name                                   | Type | Description          |
| -------------------------------------- | ---- | -------------------- |
| file<mark style="color:red;">\*</mark> | File | The agenda pack file |

{% tabs %}
{% tab title="200: OK File uploaded successfully " %}
Public url will be included in response
{% endtab %}
{% endtabs %}

## Upload the minutes document

<mark style="color:green;">`POST`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/upload-meeting-minutes-file`

#### Path Parameters

| Name                                               | Type   | Description |
| -------------------------------------------------- | ------ | ----------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String |             |
| meeting\_id<mark style="color:red;">\*</mark>      | String |             |

#### Request Body

| Name                                   | Type | Description |
| -------------------------------------- | ---- | ----------- |
| file<mark style="color:red;">\*</mark> | File |             |

## Upload an additional file for the meeting

<mark style="color:green;">`POST`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/upload-additional-file`

#### Path Parameters

| Name                                               | Type   | Description |
| -------------------------------------------------- | ------ | ----------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String |             |
| meeting\_id<mark style="color:red;">\*</mark>      | String |             |

#### Request Body

| Name                                   | Type | Description |
| -------------------------------------- | ---- | ----------- |
| file<mark style="color:red;">\*</mark> | File |             |

## Create a file upload request

<mark style="color:green;">`POST`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/file-upload-link`

Use this endpoint to create a file upload request, that can be used in front-end to upload a large file directly to the cloud storage (bypassing the HeyGov server)

#### Path Parameters

| Name                                               | Type   | Description                            |
| -------------------------------------------------- | ------ | -------------------------------------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String |                                        |
| meeting\_id<mark style="color:red;">\*</mark>      | String | ID of the meeting, starting with `me_` |

#### Request Body

| Name                                       | Type   | Description                                |
| ------------------------------------------ | ------ | ------------------------------------------ |
| filename<mark style="color:red;">\*</mark> | String | The name of the file that will be uploaded |

{% tabs %}
{% tab title="200: OK Returns the upload link" %}

{% endtab %}
{% endtabs %}

#### Agenda items endpoints

## List of agenda items for a meeting

<mark style="color:blue;">`GET`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/agenda-items`

#### Path Parameters

| Name                                               | Type   | Description |
| -------------------------------------------------- | ------ | ----------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String |             |
| meeting\_id<mark style="color:red;">\*</mark>      | String |             |

{% tabs %}
{% tab title="200: OK List of agenda items" %}

{% endtab %}
{% endtabs %}

## Edit an agenda item

<mark style="color:orange;">`PUT`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/agenda-items/{id}`

#### Path Parameters

| Name                                               | Type   | Description           |
| -------------------------------------------------- | ------ | --------------------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String |                       |
| meeting\_id<mark style="color:red;">\*</mark>      | String |                       |
| id<mark style="color:red;">\*</mark>               | String | ID of the agenda item |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

## Delete an agenda item

<mark style="color:red;">`DELETE`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/agenda-items/{id}`

## Generate minutes for a meeting

<mark style="color:green;">`POST`</mark> `https://api.heygov.com/{jurisdiction_id}/meetings/{meeting_id}/generate-minutes`

Based on the agenda items & audio/video transcript, generate full meeting minutes

#### Path Parameters

| Name                                               | Type   | Description |
| -------------------------------------------------- | ------ | ----------- |
| jurisdiction\_id<mark style="color:red;">\*</mark> | String |             |
| meeting\_id<mark style="color:red;">\*</mark>      | String |             |

#### Query Parameters

| Name        | Type   | Description                                     |
| ----------- | ------ | ----------------------------------------------- |
| model       | String | OpenAI model to use. Default is `gpt-4`         |
| temperature | String | OpenAI model temperature to use. Default is `1` |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}


---

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

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.heygov.com/heygov-api/api-endpoints/meetings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.