# Listar intervalo do calendário

`GET /api/v1/calendar/events`

Retorna itens das fontes solicitadas no intervalo, ordenados pelo início, e o status de cada fonte. Fontes indisponíveis são indicadas em `sources[]` (`not_connected`, `not_authorized`, `error`, `truncated`), sem falhar toda a requisição.

**Visibilidade.** A chave representa o membro que a criou. Quem só vê seus próprios dados recebe sua própria agenda; `memberId` é ignorado. Quem vê todos os dados pode consultar outro membro, exceto um administrador ou o proprietário do workspace. Solicitar explicitamente a agenda desses membros resulta em `403`; sem `memberId`, seus itens são omitidos. O proprietário pode acessar todas as agendas. Reuniões às quais o membro foi convidado são retornadas, independentemente do proprietário da reunião.

**Limitação.** O limite de itens por fonte e o status de `sources[]` são calculados antes do filtro de visibilidade. Assim, eventos invisíveis podem contribuir para um erro de limite (`422`), e uma fonte inteiramente filtrada pode retornar `ok` e uma lista vazia.

**Google Calendar.** A conexão é pessoal. Consultar a agenda de outro membro retorna apenas seus itens nativos, sem os eventos da conexão Google desse membro.

## Autenticação

Envie a chave em `Authorization: Bearer pf_live_…`.

## Parâmetros

| Nome | Local | Obrigatório | Tipo | Descrição |
| --- | --- | --- | --- | --- |
| `timeMin` | query | Sim | `string` | Início da janela de consulta, em ISO 8601 e UTC. |
| `timeMax` | query | Sim | `string` | Fim do intervalo em ISO 8601 UTC. Aceita até 400 dias após timeMin; acima disso, responde `400`. |
| `memberId` | query | Não | `string` | Agenda de outro membro, pelo identificador de membro do workspace. |
| `provider` | query | Não | `array` | Filtro de fontes; pode ser repetido. |
| `kind` | query | Não | `array` | Filtro de tipos de item; pode ser repetido. |

## Respostas

### 200

Sucesso

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `data` | `object` | Não |  |
| `data.items` | `array` | Não |  |
| `data.items[].id` | `string` | Não | provider:kind:id, por exemplo, native:meeting:5f2c… |
| `data.items[].provider` | `string` | Não | Valores: native, google. |
| `data.items[].kind` | `string` | Não | Valores: meeting, task, cadence_task. |
| `data.items[].readOnly` | `boolean` | Não | Não pode ser alterado por esta API; somente reuniões nativas permitem escrita. |
| `data.items[].status` | `string` | Não | confirmed, tentative, cancelled. |
| `data.items[].summary` | `string` | Não |  |
| `data.items[].description` | `string` | Não | Aceita null. |
| `data.items[].location` | `string` | Não | Aceita null. |
| `data.items[].start` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. |
| `data.items[].start.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. |
| `data.items[].start.dateTime` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].start.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. |
| `data.items[].end` | `EventDateTime` | Não | Mesmo formato do Google Calendar: `date` para dia inteiro ou `dateTime` para instante ISO 8601. Nunca envie ambos. |
| `data.items[].end.date` | `string` | Não | Data no formato YYYY-MM-DD para eventos de dia inteiro. Formato: date. Aceita null. |
| `data.items[].end.dateTime` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].end.timeZone` | `string` | Não | Fuso IANA. Padrão: fuso do workspace. Aceita null. |
| `data.items[].attendees` | `array` | Não |  |
| `data.items[].attendees[].type` | `string` | Não | Valores: member, contact. |
| `data.items[].attendees[].member` | `object` | Não | Aceita null. |
| `data.items[].attendees[].member.id` | `string` | Não |  |
| `data.items[].attendees[].member.userId` | `string` | Não |  |
| `data.items[].attendees[].member.name` | `string` | Não |  |
| `data.items[].attendees[].member.email` | `string` | Não |  |
| `data.items[].attendees[].member.image` | `string` | Não | Aceita null. |
| `data.items[].attendees[].member.role` | `string` | Não |  |
| `data.items[].attendees[].contact` | `object` | Não | Aceita null. |
| `data.items[].attendees[].contact.id` | `string` | Não |  |
| `data.items[].attendees[].contact.displayName` | `string` | Não |  |
| `data.items[].attendees[].contact.email` | `string` | Não | Aceita null. |
| `data.items[].attendees[].contact.phone` | `string` | Não | Aceita null. |
| `data.items[].attendees[].removed` | `boolean` | Não | A identidade não existe mais; o convidado continua no histórico. |
| `data.items[].attendees[].responseStatus` | `string` | Não | Valores: needs_action, accepted, declined, tentative. |
| `data.items[].attendees[].organizer` | `boolean` | Não |  |
| `data.items[].attendees[].optional` | `boolean` | Não |  |
| `data.items[].owner` | `object` | Não | Nulo quando o membro proprietário saiu do workspace. Aceita null. |
| `data.items[].owner.userId` | `string` | Não |  |
| `data.items[].owner.name` | `string` | Não |  |
| `data.items[].owner.email` | `string` | Não |  |
| `data.items[].owner.image` | `string` | Não | Aceita null. |
| `data.items[].owner.role` | `string` | Não | Papel do membro no workspace, por exemplo owner. |
| `data.items[].owner.id` | `string` | Não | ID do vínculo de membro no workspace. userId identifica o usuário. |
| `data.items[].extendedProperties` | `object` | Não | Aceita null. |
| `data.items[].conferenceUrl` | `string` | Não | Link da reunião, independentemente de sua origem. Aceita null. |
| `data.items[].botEnabled` | `boolean` | Não | O bot de gravação está configurado para esta reunião. |
| `data.items[].botStatus` | `string` | Não | Último estado informado pelo bot. Aceita null. |
| `data.items[].created` | `string` | Não | Formato: date-time. Aceita null. |
| `data.items[].updated` | `string` | Não | Formato: date-time. Aceita null. |
| `data.sources` | `array` | Não |  |
| `data.sources[].provider` | `string` | Não | Valores: native, google. |
| `data.sources[].kind` | `string` | Não | Valores: meeting, task, cadence_task. |
| `data.sources[].status` | `string` | Não | Valores: ok, not_connected, not_authorized, truncated, error. |
| `data.sources[].message` | `string` | Não | Aceita null. |
| `message` | `string` | Não | Aceita null. |

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/CalendarEvent"
          }
        },
        "sources": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/CalendarSourceStatus"
          }
        }
      }
    },
    "message": {
      "type": "string",
      "nullable": true
    }
  }
}
```

### 400

Falha de validação dos campos; `fieldErrors` contém os erros.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
```

### 401

Chave ausente, malformada, desconhecida, revogada ou expirada, ou membro emissor inativo.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
```

### 403

Autenticado, mas sem acesso: falta de permissão (`FORBIDDEN`), recurso desligado no workspace (`FEATURE_DISABLED`) ou tentativa de acessar uma agenda não permitida.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
```

### 404

Recurso não encontrado ou fora da visibilidade do membro.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
```

### 429

Limite de requisições excedido por workspace ou IP.

| Campo | Tipo | Obrigatório no objeto | Descrição |
| --- | --- | --- | --- |
| `error` | `string` | Sim |  |
| `code` | `string` | Sim | Valores: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, FEATURE_DISABLED, NOT_FOUND, CONFLICT, QUOTA_EXCEEDED, UNPROCESSABLE_ENTITY, INTERNAL_ERROR, SERVICE_UNAVAILABLE. |
| `requestId` | `string` | Sim |  |
| `details` | `string` | Não | Aceita null. |
| `fieldErrors` | `array` | Não | Aceita null. |
| `fieldErrors[].field` | `string` | Não |  |
| `fieldErrors[].message` | `string` | Não |  |

```json
{
  "type": "object",
  "description": "Formato padrão de erro. `details` e `fieldErrors` são omitidos quando ausentes.",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "FORBIDDEN",
        "FEATURE_DISABLED",
        "NOT_FOUND",
        "CONFLICT",
        "QUOTA_EXCEEDED",
        "UNPROCESSABLE_ENTITY",
        "INTERNAL_ERROR",
        "SERVICE_UNAVAILABLE"
      ]
    },
    "requestId": {
      "type": "string"
    },
    "details": {
      "type": "string",
      "nullable": true
    },
    "fieldErrors": {
      "type": "array",
      "nullable": true,
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "error",
    "code",
    "requestId"
  ]
}
```