> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ontime.hosai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Deterministically draft a week (preview, not persisted)

> Deterministically draft a week (preview, not persisted)



## OpenAPI

````yaml /api-reference/openapi.json post /api/rosters/auto-generate
openapi: 3.1.0
info:
  title: ontime API
  description: APIs for ontime.v2
  version: 1.0.0
servers:
  - url: https://app.ontime.hosai.app
    description: Production
security:
  - apiKey: []
paths:
  /api/rosters/auto-generate:
    post:
      tags:
        - Rosters
      summary: Deterministically draft a week (preview, not persisted)
      description: Deterministically draft a week (preview, not persisted)
      operationId: postApiRostersAutoGenerate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                weekStart:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                locationId:
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                departmentId:
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                coverageTargets:
                  default: []
                  type: array
                  items:
                    type: object
                    properties:
                      category:
                        type: string
                        enum:
                          - G
                          - M
                          - E
                          - 'N'
                          - F
                          - FL
                      min:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      need:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      max:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                    required:
                      - category
                      - min
                      - need
                      - max
                options:
                  type: object
                  properties:
                    fairnessOtSpread:
                      default: 0.85
                      type: number
                      minimum: 0
                      maximum: 1
                    minimiseWeekend:
                      default: 0.6
                      type: number
                      minimum: 0
                      maximum: 1
              required:
                - weekStart
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  weekStart:
                    type: string
                  days:
                    type: array
                    items:
                      type: string
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        employeeId:
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        name:
                          type: string
                        code:
                          type: string
                        cells:
                          type: array
                          items:
                            type: object
                            properties:
                              date:
                                type: string
                              state:
                                type: string
                                enum:
                                  - Working
                                  - 'Off'
                                  - Leave
                              shiftTemplateId:
                                anyOf:
                                  - type: string
                                    format: uuid
                                    pattern: >-
                                      ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  - type: 'null'
                              category:
                                anyOf:
                                  - type: string
                                    enum:
                                      - G
                                      - M
                                      - E
                                      - 'N'
                                      - F
                                      - FL
                                  - type: 'null'
                            required:
                              - date
                              - state
                              - shiftTemplateId
                              - category
                      required:
                        - employeeId
                        - name
                        - code
                        - cells
                  scores:
                    type: object
                    properties:
                      fairness:
                        type: number
                      coverage:
                        type: number
                      preferenceFit:
                        type: number
                      vsLastWeek:
                        type: number
                    required:
                      - fairness
                      - coverage
                      - preferenceFit
                      - vsLastWeek
                  relaxedConstraints:
                    type: array
                    items:
                      type: string
                  summary:
                    type: object
                    properties:
                      employees:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      cellsAssigned:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      conflicts:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      generatedMs:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                    required:
                      - employees
                      - cellsAssigned
                      - conflicts
                      - generatedMs
                  holidays:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        name:
                          type: string
                        type:
                          type: string
                      required:
                        - date
                        - name
                        - type
                required:
                  - weekStart
                  - days
                  - rows
                  - scores
                  - relaxedConstraints
                  - summary
                  - holidays
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: ont_ API key
      description: >-
        Issue keys in Settings → API. Send them as `Authorization: Bearer ont_…`
        (an `X-Api-Key: ont_…` header is also accepted). Session-cookie routes
        are used by the OnTime web apps and are shown for completeness.

````