> ## Documentation Index > Fetch the complete documentation index at: https://docs.incident.io/llms.txt > Use this file to discover all available pages before exploring further. # Update > Update a schedule. ## OpenAPI ````yaml /openapi/tags/schedules-v2.json put /v2/schedules/{id} openapi: 3.0.3 info: description: "This is the API reference for incident.io.\n\nIt documents available API endpoints, provides examples of how to use it, and\ninstructions around things like authentication and error handling.\n\nThe API is hosted at:\n\n- https://api.incident.io/\n\nAnd you will need to create an API key via your [incident.io\ndashboard](https://app.incident.io/settings/api-keys) to make requests.\n\n# Making requests\n\nHere are the key concepts required to make requests to the incident.io API.\n\n## Authentication\n\nFor all requests made to the incident.io API, you'll need an API key.\n\nTo create an API key, head to the incident dashboard and visit [API\nkeys](https://app.incident.io/settings/api-keys). When you create the key, you'll be able to choose what actions it\ncan take for your account: choose carefully, as those roles can only be set\nwhen you first create the key. We'll only show you the token once, so make sure\nyou store it somewhere safe.\n\nAPI keys are global to your incident.io account, and can be managed by anyone\nwho has the right permissions. We display the user that created the API key,\nand the API key will remain valid if that user becomes deactivated.\n\nOnce you have the key, you should make requests to the API that set the\n`Authorization` request header using a \"Bearer\" authentication scheme:\n\n```\nAuthorization: Bearer \n```\n\n## Rate Limits\n\nThe incident.io API enforces rate limits to ensure consistent performance for all users.\n\nThe default rate limit is 1200 requests/minute per API key. This limit applies to most endpoints across the API.\n\nSome endpoints have lower rate limits, particularly those that interact with external third-party systems that impose\ntheir own limitations. These specific limits vary by endpoint, and we recommend relying on the rate-limit error\nresponses to understand usage patterns and implement appropriate retry strategies.\n\nWhen you exceed a rate limit, the API will respond with a `429 Too Many Requests` status code, along with a JSON\nresponse that includes information about the limit and when you can retry:\n\n```json\n{\n \"type\": \"too_many_requests\",\n \"status\": 429,\n \"request_id\": \"b839a403-7704-41c1-bf6a-39a2d68caefa\",\n \"rate_limit\": {\n \"name\": \"api_key_name\",\n \"limit\": 1200,\n \"remaining\": 0,\n \"retry_after\": \"Thu, 17 Apr 2025 11:17:18 UTC\"\n },\n \"errors\": [\n {\n \"code\": \"too_many_requests\",\n \"message\": \"Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.\"\n }\n ]\n}\n```\n\nThe response includes:\n* The name of the API key (`name`)\n* The bucket limit (`limit`)\n* The number of requests remaining (`remaining`)\n* When you can retry requests (`retry_after`)\n\n## Errors\n\nWe use standard HTTP response codes to indicate the status or failure of API\nrequests.\n\nThe API response body will be JSON, and contain more detailed information on the\nnature of the error.\n\nAn example error when a request is made without an API key:\n\n```json\n{\n \"type\": \"authentication_error\",\n \"status\": 401,\n \"request_id\": \"8e3cc412-b49d-4957-9073-2c19d2c61804\",\n \"errors\": [\n {\n \"code\": \"missing_authorization_material\",\n \"message\": \"No authorization material provided in request\"\n }\n ]\n}\n```\n\nNote that the error:\n\n- Contains the HTTP status (`401`)\n- References the type of error (`authentication_error`)\n- Includes a `request_id` that can be provided to incident.io support to help\n\tdebug questions with your API request\n- Provides a list of individual errors, which go into detail about why the error\n\toccurred\n\nThe most common error will be a 422 Validation Error, which is returned when the\nrequest was rejected due to failing validations.\n\nThese errors look like this:\n\n```json\n{\n \"type\": \"validation_error\",\n \"status\": 422,\n \"request_id\": \"631766c4-4afd-4803-997c-cd700928fa4b\",\n \"errors\": [\n {\n \"code\": \"is_required\",\n \"message\": \"A severity is required to open an incident\",\n \"source\": {\n \"field\": \"severity_id\"\n }\n }\n ]\n}\n```\n\nThis error is caused by not providing a severity identifier, which should be at\nthe `severity_id` field of the request payload. Errors like these can be mapped to\nforms, should you be integrating with the API from a user-interface.\n\n## Compatibility\n\nWe won't make breaking changes to existing API services or endpoints, but will\nexpect integrators to upgrade themselves to the latest API endpoints within 3\nmonths of us deprecating the old service.\n\nWe will make changes that are considered backwards compatible, which include:\n\n- Adding new API endpoints and services\n- Adding new properties to responses from existing API endpoints\n- Reordering properties returned from existing API endpoints\n- Adding optional request parameters to existing API endpoints\n- Altering the format or length of IDs\n- Adding new values to enums\n\nIt is important that clients are robust to these changes, to ensure reliable\nintegrations.\n\nAs an example, if you are generating a client using an openapi-generator, ensure\nthe generated client is configured to support unknown enum values, often\nconfigured via the `enumUnknownDefaultCase` parameter.\n\nWhen breaking changes are unavoidable, we'll create a new service version on a\nseparate path, and run them in parallel.\n\nFor example:\n\n- https://api.incident.io/v1/incidents\n- https://api.incident.io/v2/incidents\n\nFor any questions, email support@incident.io.\n" title: incident.io version: 1.0.0 servers: - url: https://api.incident.io security: - BearerAuth: [] tags: - description: > View and manage schedules. Manage your full schedule of on-call rotations, including the users and rotation configuration. name: Schedules V2 paths: /v2/schedules/{id}: put: tags: - Schedules V2 summary: Update description: Update a schedule. operationId: Schedules V2_Update parameters: - description: The schedule ID to update. example: 01G0J1EXE7AXZ2C93K61WBPYEH in: path name: id required: true schema: description: The schedule ID to update. example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string requestBody: content: application/json: example: schedule: annotations: incident.io/terraform/version: version-of-terraform config: rotations: - effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: My Rotation scheduling_mode: fair users: - email: bob@example.com id: 01G0J1EXE7AXZ2C93K61WBPYEH slack_user_id: USER123 working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday holidays_public_config: country_codes: - abc123 name: Primary On-call Schedule team_ids: - 01JPQA75EPNEES4479P16P4XAB timezone: America/Los_Angeles schema: $ref: '#/components/schemas/SchedulesUpdatePayloadV2' required: true responses: '200': content: application/json: example: schedule: annotations: incident.io/terraform/version: 3.0.0 config: rotations: - effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: Primary On-Call Schedule scheduling_mode: fair users: - email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday created_at: '2021-08-17T13:28:57.801578Z' current_shifts: - end_at: '2021-08-17T13:28:57.801578Z' entry_id: 01G0J1EXE7AXZ2C93K61WBPYEH fingerprint: 01G0J1EXE7AXZ2C93K61WBPYEH layer_id: 01G0J1EXE7AXZ2C93K61WBPYNH rotation_id: 01G0J1EXE7AXZ2C93K61WBPYEH start_at: '2021-08-17T13:28:57.801578Z' user: email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM holidays_public_config: country_codes: - GB - FR id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Primary On-Call Schedule next_shifts: - end_at: '2021-08-17T13:28:57.801578Z' entry_id: 01G0J1EXE7AXZ2C93K61WBPYEH fingerprint: 01G0J1EXE7AXZ2C93K61WBPYEH layer_id: 01G0J1EXE7AXZ2C93K61WBPYNH rotation_id: 01G0J1EXE7AXZ2C93K61WBPYEH start_at: '2021-08-17T13:28:57.801578Z' user: email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM team_ids: - 01JPQA75EPNEES4479P16P4XAB timezone: Europe/London updated_at: '2021-08-17T13:28:57.801578Z' schema: $ref: '#/components/schemas/SchedulesUpdateResultV2' description: OK response. components: schemas: SchedulesUpdatePayloadV2: example: schedule: annotations: incident.io/terraform/version: version-of-terraform config: rotations: - effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: My Rotation scheduling_mode: fair users: - email: bob@example.com id: 01G0J1EXE7AXZ2C93K61WBPYEH slack_user_id: USER123 working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday holidays_public_config: country_codes: - abc123 name: Primary On-call Schedule team_ids: - 01JPQA75EPNEES4479P16P4XAB timezone: America/Los_Angeles properties: schedule: $ref: '#/components/schemas/ScheduleUpdatePayloadV2' required: - schedule type: object SchedulesUpdateResultV2: example: schedule: annotations: incident.io/terraform/version: 3.0.0 config: rotations: - effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: Primary On-Call Schedule scheduling_mode: fair users: - email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday created_at: '2021-08-17T13:28:57.801578Z' current_shifts: - end_at: '2021-08-17T13:28:57.801578Z' entry_id: 01G0J1EXE7AXZ2C93K61WBPYEH fingerprint: 01G0J1EXE7AXZ2C93K61WBPYEH layer_id: 01G0J1EXE7AXZ2C93K61WBPYNH rotation_id: 01G0J1EXE7AXZ2C93K61WBPYEH start_at: '2021-08-17T13:28:57.801578Z' user: email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM holidays_public_config: country_codes: - GB - FR id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Primary On-Call Schedule next_shifts: - end_at: '2021-08-17T13:28:57.801578Z' entry_id: 01G0J1EXE7AXZ2C93K61WBPYEH fingerprint: 01G0J1EXE7AXZ2C93K61WBPYEH layer_id: 01G0J1EXE7AXZ2C93K61WBPYNH rotation_id: 01G0J1EXE7AXZ2C93K61WBPYEH start_at: '2021-08-17T13:28:57.801578Z' user: email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM team_ids: - 01JPQA75EPNEES4479P16P4XAB timezone: Europe/London updated_at: '2021-08-17T13:28:57.801578Z' properties: schedule: $ref: '#/components/schemas/ScheduleV2' required: - schedule type: object ScheduleUpdatePayloadV2: example: annotations: incident.io/terraform/version: version-of-terraform config: rotations: - effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: My Rotation scheduling_mode: fair users: - email: bob@example.com id: 01G0J1EXE7AXZ2C93K61WBPYEH slack_user_id: USER123 working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday holidays_public_config: country_codes: - abc123 name: Primary On-call Schedule team_ids: - 01JPQA75EPNEES4479P16P4XAB timezone: America/Los_Angeles properties: annotations: additionalProperties: example: abc123 type: string description: Annotations that can track metadata about the schedule example: incident.io/terraform/version: version-of-terraform type: object config: $ref: '#/components/schemas/ScheduleConfigUpdatePayloadV2' holidays_public_config: $ref: '#/components/schemas/ScheduleHolidaysPublicConfigPayloadV2' name: description: Name of the schedule example: Primary On-call Schedule type: string team_ids: description: IDs of teams that own this schedule example: - 01JPQA75EPNEES4479P16P4XAB items: example: abc123 type: string type: array timezone: description: Timezone of the schedule example: America/Los_Angeles type: string type: object ScheduleV2: properties: annotations: additionalProperties: example: abc123 type: string description: Annotations that track metadata about this resource example: incident.io/terraform/version: 3.0.0 type: object config: $ref: '#/components/schemas/ScheduleConfigV2' created_at: example: '2021-08-17T13:28:57.801578Z' format: date-time type: string current_shifts: description: Shifts that are ongoing for this schedule example: - end_at: '2021-08-17T13:28:57.801578Z' entry_id: 01G0J1EXE7AXZ2C93K61WBPYEH fingerprint: 01G0J1EXE7AXZ2C93K61WBPYEH layer_id: 01G0J1EXE7AXZ2C93K61WBPYNH rotation_id: 01G0J1EXE7AXZ2C93K61WBPYEH start_at: '2021-08-17T13:28:57.801578Z' user: email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM items: $ref: '#/components/schemas/ScheduleEntryV2' type: array holidays_public_config: $ref: '#/components/schemas/ScheduleHolidaysPublicConfigV2' id: description: Unique internal ID of the schedule example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string name: description: Human readable name synced from external provider example: Primary On-Call Schedule type: string next_shifts: description: >- The shifts after the next changeover. Note that on the list schedules endpoint, this will always be empty if the page size requested is greater than 25. example: - end_at: '2021-08-17T13:28:57.801578Z' entry_id: 01G0J1EXE7AXZ2C93K61WBPYEH fingerprint: 01G0J1EXE7AXZ2C93K61WBPYEH layer_id: 01G0J1EXE7AXZ2C93K61WBPYNH rotation_id: 01G0J1EXE7AXZ2C93K61WBPYEH start_at: '2021-08-17T13:28:57.801578Z' user: email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM items: $ref: '#/components/schemas/ScheduleEntryV2' type: array team_ids: description: IDs of teams that own this schedule example: - 01JPQA75EPNEES4479P16P4XAB items: example: abc123 type: string type: array timezone: description: >- Timezone of the schedule, as interpreted at the point of generating the report example: Europe/London type: string updated_at: example: '2021-08-17T13:28:57.801578Z' format: date-time type: string required: - id - name - timezone - team_ids - created_at - updated_at - annotations type: object ScheduleConfigUpdatePayloadV2: example: rotations: - effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: My Rotation scheduling_mode: fair users: - email: bob@example.com id: 01G0J1EXE7AXZ2C93K61WBPYEH slack_user_id: USER123 working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday properties: rotations: example: - effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: My Rotation scheduling_mode: fair users: - email: bob@example.com id: 01G0J1EXE7AXZ2C93K61WBPYEH slack_user_id: USER123 working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday items: $ref: '#/components/schemas/ScheduleRotationUpdatePayloadV2' type: array type: object ScheduleHolidaysPublicConfigPayloadV2: example: country_codes: - abc123 properties: country_codes: description: >- ISO 3166-1 alpha-2 country codes for the countries that this schedule is configured to view holidays for example: - abc123 items: example: abc123 type: string type: array required: - country_codes type: object ScheduleConfigV2: example: rotations: - effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: Primary On-Call Schedule scheduling_mode: fair users: - email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday properties: rotations: description: Rotas in this schedule example: - effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: Primary On-Call Schedule scheduling_mode: fair users: - email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday items: $ref: '#/components/schemas/ScheduleRotationV2' type: array required: - rotations type: object ScheduleEntryV2: description: >- A single shift on a schedule, representing who is on-call between a start and end time. When present, `rotation_id` and `layer_id` tell you which rotation and which layer within that rotation the entry belongs to. A schedule may have multiple rotations (for example, a primary and a secondary rotation) and each rotation can be made up of several layers — entries are returned for every rotation and layer on the schedule. Entries come from two places: they are either generated from a schedule's rotation configuration (the regular pattern of who is on-call) or created by an override (a one-off change that replaces the normal rotation for a period of time). When you call the List schedule entries endpoint we return both kinds separately, along with the merged `final` schedule that reflects what will actually happen. `entry_id` is only populated for entries that correspond to a stored record. Scheduled entries are projections computed from the rotation rules on the fly and don't have a persisted ID, so `entry_id` will be absent for those. Use `fingerprint` if you need a stable identifier to deduplicate or diff a shift across requests. properties: end_at: example: '2021-08-17T13:28:57.801578Z' format: date-time type: string entry_id: description: Unique identifier of the schedule entry example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string fingerprint: description: A unique identifier for this entry, used to determine a unique shift example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string layer_id: description: If present, the layer this entry applies to on the rotation example: 01G0J1EXE7AXZ2C93K61WBPYNH type: string rotation_id: description: If present, the rotation this entry applies to on the schedule example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string start_at: example: '2021-08-17T13:28:57.801578Z' format: date-time type: string user: $ref: '#/components/schemas/UserV2' required: - start_at - end_at type: object ScheduleHolidaysPublicConfigV2: example: country_codes: - GB - FR properties: country_codes: description: >- ISO 3166-1 alpha-2 country codes for the countries that this schedule is configured to view holidays for example: - GB - FR items: example: abc123 type: string type: array required: - country_codes type: object ScheduleRotationUpdatePayloadV2: example: effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: My Rotation scheduling_mode: fair users: - email: bob@example.com id: 01G0J1EXE7AXZ2C93K61WBPYEH slack_user_id: USER123 working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday properties: effective_from: example: '2021-08-17T13:28:57.801578Z' format: date-time type: string handover_start_at: example: '2021-08-17T13:28:57.801578Z' format: date-time type: string handovers: example: - interval: 1 interval_type: hourly items: $ref: '#/components/schemas/ScheduleRotationHandoverV2' type: array id: description: Unique identifier of the rotation example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string layers: example: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 items: $ref: '#/components/schemas/ScheduleLayerUpdatePayloadV2' type: array name: description: Name of the rotation example: My Rotation type: string scheduling_mode: description: >- Scheduling algorithm to use for this rotation. 'fair' balances workload by considering handover duration, while 'sequential' uses simple round-robin rotation through users. Only applies when you have asymmetric handovers (e.g., 2 days then 5 days). enum: - fair - sequential example: fair type: string users: example: - email: bob@example.com id: 01G0J1EXE7AXZ2C93K61WBPYEH slack_user_id: USER123 items: $ref: '#/components/schemas/UserReferencePayloadV2' type: array working_interval: description: 'DEPRECATED: Use working_intervals instead.' example: - end_time: '17:00' start_time: '09:00' weekday: monday items: $ref: '#/components/schemas/ScheduleRotationWorkingIntervalV2' type: array working_intervals: example: - end_time: '17:00' start_time: '09:00' weekday: monday items: $ref: '#/components/schemas/ScheduleRotationWorkingIntervalV2' type: array type: object ScheduleRotationV2: example: effective_from: '2021-08-17T13:28:57.801578Z' handover_start_at: '2021-08-17T13:28:57.801578Z' handovers: - interval: 1 interval_type: hourly id: 01G0J1EXE7AXZ2C93K61WBPYEH layers: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 name: Primary On-Call Schedule scheduling_mode: fair users: - email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM working_interval: - end_time: '17:00' start_time: '09:00' weekday: monday working_intervals: - end_time: '17:00' start_time: '09:00' weekday: monday properties: effective_from: description: When this rotation config will be effective from example: '2021-08-17T13:28:57.801578Z' format: date-time type: string handover_start_at: description: Defines the next moment we'll trigger a handover example: '2021-08-17T13:28:57.801578Z' format: date-time type: string handovers: description: >- Defines the handover intervals for this rota, in order they should apply example: - interval: 1 interval_type: hourly items: $ref: '#/components/schemas/ScheduleRotationHandoverV2' type: array id: description: Unique internal ID of the rotation example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string layers: description: Controls how many people are on-call concurrently example: - id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 items: $ref: '#/components/schemas/ScheduleLayerV2' type: array name: description: Human readable name synced from external provider example: Primary On-Call Schedule type: string scheduling_mode: description: >- Scheduling algorithm to use for this rotation. 'fair' balances workload by considering handover duration, while 'sequential' uses simple round-robin rotation through users. Only applies when you have asymmetric handovers (e.g., 2 days then 5 days). enum: - fair - sequential example: fair type: string users: description: Users who are available to be scheduled on this rota example: - email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM items: $ref: '#/components/schemas/UserV2' type: array working_interval: description: 'DEPRECATED: Use working_intervals instead.' example: - end_time: '17:00' start_time: '09:00' weekday: monday items: $ref: '#/components/schemas/ScheduleRotationWorkingIntervalV2' type: array working_intervals: description: >- Optional restrictions that define when to schedule people for this rota example: - end_time: '17:00' start_time: '09:00' weekday: monday items: $ref: '#/components/schemas/ScheduleRotationWorkingIntervalV2' type: array required: - id - name - layers - users - working_intervals - handover_start_at - handovers type: object UserV2: example: email: lisa@incident.io id: 01FCNDV6P870EA6S7TK1DSYDG0 name: Lisa Karlin Curtis role: owner slack_user_id: U02AYNF2XJM properties: email: description: Email address of the user. example: lisa@incident.io type: string id: description: Unique identifier of the user example: 01FCNDV6P870EA6S7TK1DSYDG0 type: string name: description: Name of the user example: Lisa Karlin Curtis type: string role: description: >- DEPRECATED: Role of the user as of March 9th 2023, this value is no longer updated. enum: - viewer - responder - administrator - owner - unset example: owner type: string slack_user_id: description: Slack ID of the user example: U02AYNF2XJM type: string required: - role - id - name type: object ScheduleRotationHandoverV2: example: interval: 1 interval_type: hourly properties: interval: example: 1 format: int64 type: integer interval_type: description: How often a handover occurs enum: - hourly - daily - weekly example: hourly type: string x-public-api-version: v2 required: - interval_type - interval type: object ScheduleLayerUpdatePayloadV2: example: id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 properties: id: description: Unique identifier of the layer example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string name: description: Name of the layer example: Layer 1 type: string type: object UserReferencePayloadV2: example: email: bob@example.com id: 01G0J1EXE7AXZ2C93K61WBPYEH slack_user_id: USER123 properties: email: description: The user's email address, matching the email on their Slack account example: bob@example.com type: string id: description: The incident.io ID of a user example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string slack_user_id: description: The ID of the user's Slack account. example: USER123 type: string type: object ScheduleRotationWorkingIntervalV2: example: end_time: '17:00' start_time: '09:00' weekday: monday properties: end_time: description: End time of the interval, in 24hr format example: '17:00' type: string start_time: description: Start time of the interval, in 24hr format example: '09:00' type: string weekday: description: Weekdays for use with a schedule enum: - monday - tuesday - wednesday - thursday - friday - saturday - sunday example: monday type: string x-public-api-version: v2 required: - weekday - start_time - end_time type: object ScheduleLayerV2: example: id: 01G0J1EXE7AXZ2C93K61WBPYEH name: Layer 1 properties: id: description: Unique identifier of the layer example: 01G0J1EXE7AXZ2C93K61WBPYEH type: string name: description: Name of the layer example: Layer 1 type: string type: object securitySchemes: BearerAuth: type: http scheme: bearer description: API key from your incident.io dashboard (Settings → API keys) ````