openapi: 3.1.0
info:
  title: 7shifts Availability Shifts API
  version: '2.0'
  description: 7shifts is a restaurant employee scheduling, time-tracking, and team management platform. The 7shifts API v2 is a REST API for managing companies, locations, departments, roles, users (employees), schedules, shifts, time punches, wages, time off, availability, sales receipts, forecasts, tasks, tip pools, and webhooks. Authentication uses Bearer access tokens for internal access or OAuth 2.0 client credentials for partner integrations. Endpoints documented here were confirmed from the 7shifts developer reference (developers.7shifts.com) and its llms.txt index. Most resources are scoped to a company via the /v2/company/{company_id} path prefix. Collection endpoints use cursor-based pagination via the cursor and limit query parameters. Date-based API versions are selected with the x-api-version header (YYYY-MM-DD).
  contact:
    name: 7shifts Developer Portal
    url: https://developers.7shifts.com/reference/introduction
  license:
    name: 7shifts API Terms
    url: https://www.7shifts.com/legal/terms-of-service
servers:
- url: https://api.7shifts.com
  description: 7shifts API production base URL
tags:
- name: Shifts
  description: Scheduled shifts assigned to users.
paths:
  /v2/company/{company_id}/shifts:
    get:
      tags:
      - Shifts
      operationId: listShifts
      summary: List Shifts
      parameters:
      - $ref: '#/components/parameters/CompanyIdPath'
      - name: location_id
        in: query
        required: false
        description: Filter by location.
        schema:
          type: integer
          format: int64
      - name: department_id
        in: query
        required: false
        description: Filter by department.
        schema:
          type: integer
          format: int64
      - name: role_id
        in: query
        required: false
        description: Filter by role.
        schema:
          type: integer
          format: int64
      - name: user_id
        in: query
        required: false
        description: Filter by assigned user.
        schema:
          type: integer
          format: int64
      - name: start[gte]
        in: query
        required: false
        description: Filter by shift start time greater than or equal to (ISO8601).
        schema:
          type: string
          format: date-time
      - name: start[lte]
        in: query
        required: false
        description: Filter by shift start time less than or equal to (ISO8601).
        schema:
          type: string
          format: date-time
      - name: modified_since
        in: query
        required: false
        description: Return shifts modified after the specified datetime.
        schema:
          type: string
          format: date-time
      - name: open
        in: query
        required: false
        description: Filter for unassigned (open) shifts.
        schema:
          type: boolean
      - name: include_draft
        in: query
        required: false
        description: Include draft shifts.
        schema:
          type: boolean
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Shift'
                  meta:
                    $ref: '#/components/schemas/CursorMeta'
      security:
      - bearerAuth: []
    post:
      tags:
      - Shifts
      operationId: createShift
      summary: Create Shift
      parameters:
      - $ref: '#/components/parameters/CompanyIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Shift'
      responses:
        '201':
          description: Created
        '400':
          description: Bad request
      security:
      - bearerAuth: []
  /v2/company/{company_id}/shifts/{shift_id}:
    get:
      tags:
      - Shifts
      operationId: retrieveShift
      summary: Retrieve Shift
      parameters:
      - $ref: '#/components/parameters/CompanyIdPath'
      - name: shift_id
        in: path
        required: true
        description: Shift identifier.
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Shift'
        '404':
          description: Not found
      security:
      - bearerAuth: []
    delete:
      tags:
      - Shifts
      operationId: deleteShift
      summary: Delete Shift
      parameters:
      - $ref: '#/components/parameters/CompanyIdPath'
      - name: shift_id
        in: path
        required: true
        description: Shift identifier.
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: Deleted
        '404':
          description: Not found
      security:
      - bearerAuth: []
components:
  parameters:
    Cursor:
      name: cursor
      in: query
      required: false
      description: Pagination cursor for the next or previous page.
      schema:
        type: string
    CompanyIdPath:
      name: company_id
      in: path
      required: true
      description: Company identifier.
      schema:
        type: integer
        format: int64
    Limit:
      name: limit
      in: query
      required: false
      description: Results per page (1-500, default 100; 20 for some collections).
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
  schemas:
    Break:
      title: Break
      type: object
      properties:
        id:
          type: integer
          format: int64
        in:
          type: string
          format: date-time
        out:
          type: string
          format: date-time
          nullable: true
        paid:
          type: boolean
    Shift:
      title: Shift
      type: object
      properties:
        id:
          type: integer
          format: int64
        user_id:
          type: integer
          format: int64
          nullable: true
        location_id:
          type: integer
          format: int64
        department_id:
          type: integer
          format: int64
        role_id:
          type: integer
          format: int64
        start:
          type: string
          format: date-time
          description: Start datetime of the shift. UTC in ISO8601 format.
        end:
          type: string
          format: date-time
          description: End datetime of the shift. UTC in ISO8601 format.
        hourly_wage:
          type: integer
          description: The hourly wage for this shift, in cents.
        draft:
          type: boolean
          description: Publication status indicator.
        open:
          type: boolean
          description: Indicates an unassigned shift available for requests.
        station:
          type: string
          nullable: true
        attendance_status:
          type: string
          enum:
          - none
          - sick
          - no_show
          - late
        breaks:
          type: array
          items:
            $ref: '#/components/schemas/Break'
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    CursorMeta:
      title: Cursor Meta
      type: object
      description: Cursor-based pagination metadata.
      properties:
        cursor:
          type: object
          properties:
            current:
              type: string
            next:
              type: string
              nullable: true
            prev:
              type: string
              nullable: true
        count:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access token obtained from /oauth2/token passed as a Bearer token.
    oauth2:
      type: oauth2
      description: OAuth 2.0 with client_credentials, password, authorization_code, and refresh_token grant types.
      flows:
        clientCredentials:
          tokenUrl: https://api.7shifts.com/oauth2/token
          scopes: {}