openapi: 3.1.1
info:
  title: Business Management
  version: 2.0.0
  termsOfService: https://alteg.io/en/info/terms/
  license:
    name: Altegio API Agreement
    url: /en/api-license-agreement
  description: >
    Next-generation B2B API with improved design and consistency.


    **Base URL:** `https://api.alteg.io/api`


    ## 🚀 Version Status


    **V2 is in active development.** This API version is being actively
    developed and expanded. New features and improvements are released here
    first. We recommend using V2 for all new integrations.


    ## Authentication


    Requires both partner and user authorization:

    ```

    Authorization: Bearer <partner_token>, User <user_token>

    ```


    ## About v2


    V2 endpoints offer improved request/response structures and consistent
    naming.

    This collection is actively growing as we modernize the API.
servers:
  - url: https://api.alteg.io/api/v2
    description: Production
components:
  securitySchemes:
    bearer:
      type: apiKey
      name: Authorization
      in: header
    user:
      type: apiKey
      name: Authorization
      in: header
    BearerPartner:
      type: http
      scheme: bearer
      bearerFormat: Bearer {PartnerToken}
    BearerPartnerUser:
      type: http
      scheme: bearer
      bearerFormat: Bearer {PartnerToken}, User {UserToken}
  schemas:
    tag_v2_attributes:
      type: object
      description: Tag attributes (v2 API JSON:API format)
      properties:
        company_id:
          type: integer
          description: Company (location) ID
          example: 68570
        title:
          type: string
          description: Tag name
          example: VIP client
        color:
          type: string
          description: Tag background color in
          example: '#ff2828'
        font_color:
          type: string
          description: Tag font color in
          example: '#ffffff'
        icon:
          type: string
          description: Icon name
          example: star
        entity_type:
          type: string
          description: Entity type slug
          enum:
            - common
            - client
            - record
            - activity
          example: client
        is_deleted:
          type: boolean
          description: Whether the tag is deleted
          example: false
        is_editable:
          type: boolean
          description: Whether the tag can be edited/deleted
          example: true
        salon_id:
          type: integer
          description: 'Deprecated: Use company_id instead'
          deprecated: true
          example: 68570
        entity:
          type: integer
          description: >-
            Deprecated: Use entity_type instead. Numeric entity type (0-common,
            1-client, 2-record, 3-activity)
          deprecated: true
          example: 1
        entity_slug:
          type: string
          description: 'Deprecated: Use entity_type instead'
          deprecated: true
          example: client
        deleted:
          type: integer
          description: 'Deprecated: Use is_deleted instead. (0 - not deleted, 1 - deleted)'
          deprecated: true
          example: 0
        not_editable:
          type: integer
          description: >-
            Deprecated: Use is_editable instead. (0 - editable, 1 - not
            editable)
          deprecated: true
          example: 0
      required:
        - company_id
        - title
        - color
        - entity_type
        - is_deleted
        - is_editable
x-tagGroups:
  - name: POS & Scheduling
    tags:
      - Team Members
      - Events
  - name: Administrative
    tags:
      - Tags
tags:
  - name: Team Members
    description: Team member and position management.
  - name: Events
    description: Group events (activities) management.
  - name: Tags
    description: Client tagging system.
paths:
  /companies/{company_id}/positions:
    get:
      tags:
        - Team Members
      security:
        - BearerPartnerUser: []
      summary: List Positions (v2)
      description: >
        Returns all staff positions for the specified company.


        Response uses [JSON:API](https://jsonapi.org/) format where `type:
        "position"` is the resource type.


        **Positions** define organizational roles and can be assigned to staff
        members.

        Positions are stored at the salon group level but accessed via company.
      operationId: list_positions_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
          description: API version header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
          description: Maximum number of results to return
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Number of results to skip for pagination
      responses:
        '200':
          description: Positions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: position
                        id:
                          type: string
                          example: '42'
                        attributes:
                          type: object
                          properties:
                            chain_id:
                              type: integer
                              description: Salon group (chain) ID
                              example: 5
                            title:
                              type: string
                              description: Position name
                              example: Senior Stylist
                            description:
                              type: string
                              description: Position description
                              example: Senior hair stylist with color specialization
                            services_binding_type:
                              type: string
                              enum:
                                - none
                                - optional
                                - required
                              example: none
                            rules_required_fields:
                              type: array
                              items:
                                type: string
                              example:
                                - phone
                                - email
                            only_chain_appointment:
                              type: boolean
                              example: false
                            salon_ids:
                              type: array
                              items:
                                type: integer
                              example:
                                - 1
                                - 2
                                - 3
                  meta:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          limit:
                            type: integer
                          offset:
                            type: integer
              example:
                data:
                  - type: position
                    id: '42'
                    attributes:
                      chain_id: 5
                      title: Senior Stylist
                      description: Senior hair stylist with color specialization
                      services_binding_type: none
                      rules_required_fields: []
                      only_chain_appointment: false
                      salon_ids:
                        - 1
                        - 2
                        - 3
                meta:
                  pagination:
                    total: 1
                    limit: 100
                    offset: 0
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '403':
          description: Forbidden - No permission to read positions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
    post:
      tags:
        - Team Members
      security:
        - BearerPartnerUser: []
      summary: Create Position (v2)
      description: |
        Creates a new staff position for the specified company.
        At least one salon ID must be provided.
      operationId: create_position_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - title
                - salon_ids
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Position name
                  example: Senior Stylist
                description:
                  type: string
                  maxLength: 1000
                  description: Position description (optional)
                  example: Senior hair stylist with color specialization
                salon_ids:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                    minimum: 1
                  description: IDs of salons where this position is available
                  example:
                    - 1
                    - 2
                    - 3
      responses:
        '201':
          description: Position created successfully
          headers:
            Location:
              schema:
                type: string
              description: URL of the created resource
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        example: position
                      id:
                        type: string
                        example: '42'
                      attributes:
                        type: object
                        properties:
                          chain_id:
                            type: integer
                          title:
                            type: string
                          description:
                            type: string
                          services_binding_type:
                            type: string
                          rules_required_fields:
                            type: array
                            items:
                              type: string
                          only_chain_appointment:
                            type: boolean
                          salon_ids:
                            type: array
                            items:
                              type: integer
                  meta:
                    type: object
              example:
                data:
                  type: position
                  id: '42'
                  attributes:
                    chain_id: 5
                    title: Senior Stylist
                    description: Senior hair stylist with color specialization
                    services_binding_type: none
                    rules_required_fields: []
                    only_chain_appointment: false
                    salon_ids:
                      - 1
                      - 2
                      - 3
                meta: {}
        '400':
          description: Bad Request - Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden - No permission to create positions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '422':
          description: Validation Error - Missing or invalid required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    example:
                      title:
                        - Title is required
                      salon_ids:
                        - At least one salon must be selected
  /companies/{company_id}/positions/{position_id}:
    get:
      tags:
        - Team Members
      security:
        - BearerPartnerUser: []
      summary: Get Position (v2)
      description: >
        Retrieve details of a specific position by ID.


        Response uses [JSON:API](https://jsonapi.org/) format where `type:
        "position"` is the resource type.
      operationId: get_position_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
          description: API version header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
        - name: position_id
          in: path
          required: true
          schema:
            type: integer
          description: Position ID
      responses:
        '200':
          description: Position retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        example: position
                      id:
                        type: string
                        example: '42'
                      attributes:
                        type: object
                        properties:
                          chain_id:
                            type: integer
                          title:
                            type: string
                          description:
                            type: string
                          services_binding_type:
                            type: string
                          rules_required_fields:
                            type: array
                            items:
                              type: string
                          only_chain_appointment:
                            type: boolean
                          salon_ids:
                            type: array
                            items:
                              type: integer
                  meta:
                    type: object
              example:
                data:
                  type: position
                  id: '42'
                  attributes:
                    chain_id: 5
                    title: Senior Stylist
                    description: Senior hair stylist with color specialization
                    services_binding_type: none
                    rules_required_fields: []
                    only_chain_appointment: false
                    salon_ids:
                      - 1
                      - 2
                      - 3
                meta: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden - No permission to read this position
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Position not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
    put:
      tags:
        - Team Members
      security:
        - BearerPartnerUser: []
      summary: Update Position (v2)
      description: |
        Update an existing staff position.
        Title and salon_ids are required in the request body.
      operationId: update_position_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
        - name: position_id
          in: path
          required: true
          schema:
            type: integer
          description: Position ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - position_id
                - title
                - salon_ids
              type: object
              properties:
                position_id:
                  type: integer
                  description: Position ID (must match path parameter)
                  example: 42
                title:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Position name
                  example: Senior Stylist Updated
                description:
                  type: string
                  maxLength: 1000
                  description: Position description (optional)
                  example: Updated description
                salon_ids:
                  type: array
                  minItems: 1
                  items:
                    type: integer
                    minimum: 1
                  description: IDs of salons where this position is available
                  example:
                    - 1
                    - 2
                    - 3
                    - 4
      responses:
        '204':
          description: Position updated successfully (no content)
        '400':
          description: Bad Request - Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden - No permission to update positions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Position not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '422':
          description: Validation Error - Missing or invalid required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    example:
                      title:
                        - Title is required
                      salon_ids:
                        - At least one salon must be selected
    delete:
      tags:
        - Team Members
      security:
        - BearerPartnerUser: []
      summary: Delete Position (v2)
      description: |
        Delete a staff position.
      operationId: delete_position_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
        - name: position_id
          in: path
          required: true
          schema:
            type: integer
          description: Position ID
      responses:
        '204':
          description: Position deleted successfully (no content)
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden - No permission to delete positions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Position not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
  /companies/{location_id}/activities:
    get:
      tags:
        - Events
      security:
        - BearerPartnerUser: []
      summary: List Activities (v2)
      description: >
        Retrieve activities for a company within a date range, optionally
        filtered by search, staff, or services.


        **Required Parameters:**

        - `filter[from]` - start date/time (format: YYYY-MM-DD HH:MM:SS)

        - `filter[to]` - end date/time (format: YYYY-MM-DD HH:MM:SS)


        **Optional Filters:**

        - `filter[master_ids][]` - filter by staff IDs (array)

        - `filter[service_ids][]` - filter by service IDs (array)

        - `filter[capacity]` - filter by capacity (number)

        - `search` - search by activity name or description (string)

        - `limit` - results per page (default: 100)

        - `offset` - pagination offset (default: 0)
      operationId: list_activities_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
          description: API version header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: location_id
          in: path
          required: true
          schema:
            type: integer
          description: Location (business) ID
        - name: filter[from]
          in: query
          required: true
          schema:
            type: string
            format: date-time
            example: '2026-01-02 10:00:00'
          description: Start date/time
        - name: filter[to]
          in: query
          required: true
          schema:
            type: string
            format: date-time
            example: '2026-01-05 18:00:00'
          description: End date/time
        - name: filter[master_ids][]
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          description: Filter by staff IDs
          example:
            - 5
            - 10
        - name: filter[service_ids][]
          in: query
          required: false
          schema:
            type: array
            items:
              type: integer
          description: Filter by service IDs
          example:
            - 20
            - 25
        - name: filter[capacity]
          in: query
          required: false
          schema:
            type: integer
          description: Filter by capacity
          example: 3
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search by activity name or description
          example: yoga
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
          description: Maximum number of results to return
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Number of results to skip
      responses:
        '200':
          description: List of activities
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        company_id:
                          type: integer
                        name:
                          type: string
                          example: Yoga Class
                        description:
                          type: string
                        datetime:
                          type: string
                          format: date-time
                        staff_id:
                          type: integer
                        service_id:
                          type: integer
                        comment:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
                  meta:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          total:
                            type: integer
                          limit:
                            type: integer
                          offset:
                            type: integer
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
    post:
      tags:
        - Events
      security:
        - BearerPartnerUser: []
      summary: Create Event (v2)
      description: >
        Creates an Event using the v2 API.


        **Note:** This is the v2 version of the Events API with enhanced
        features.
      operationId: create_event_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
          description: API version header
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: location_id
          in: path
          required: true
          schema:
            type: integer
          description: Location (business) ID
          example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - staff_id
                - service_id
                - resource_instance_ids
                - label_ids
                - date
                - length
                - capacity
              type: object
              properties:
                staff_id:
                  type: integer
                  description: Team member ID who will conduct the event.
                  example: 1
                service_id:
                  type: integer
                  description: Service ID for this event.
                  example: 500
                resource_instance_ids:
                  type: array
                  description: >-
                    List of resource instance IDs (required, can be empty
                    array).
                  items:
                    type: integer
                  example:
                    - 123
                    - 432
                label_ids:
                  type: array
                  description: List of category/tag IDs (required, can be empty array).
                  items:
                    type: integer
                  example:
                    - 123
                    - 432
                date:
                  type: string
                  description: Event date and time.
                  example: '2026-11-22 14:00:00'
                  format: date-time
                length:
                  type: integer
                  description: Event duration in seconds.
                  example: 3600
                technical_break_duration:
                  oneOf:
                    - type: integer
                    - type: 'null'
                  description: >
                    Technical break duration in seconds.

                    - If not provided: defaults to null

                    - Value null: uses location's default setting (Settings →
                    Timetable → Technical breaks) or keeps current value when
                    updating

                    - If value > 0: break duration must be included in the
                    length parameter (length = services + break)

                    - Accepts only multiples of 300 (5-minute intervals)

                    - Maximum value: 3600 (1 hour)
                  example: 300
                capacity:
                  type: integer
                  description: Number of available slots for this event.
                  example: 4
                comment:
                  type: string
                  description: Event comment or description.
                  example: Beginner group session
                color:
                  type: string
                  description: Event color (hex format).
                  example: '#9c27b0'
                instructions:
                  type: string
                  description: Instructions for the event.
                  example: Bring two balls
                stream_link:
                  type: string
                  description: Stream link for online events.
                  example: https://stream.com/some_link
                force:
                  type: boolean
                  description: >-
                    Skip resource availability check (true - skip check, false -
                    validate).
                  example: false
                  default: false
      responses:
        '201':
          description: Event created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Created event details (JSON:API format)
                    properties:
                      type:
                        type: string
                        example: activity
                      id:
                        type: string
                        example: '10126531'
                      attributes:
                        type: object
                        properties:
                          master_id:
                            type: integer
                          staff_id:
                            type: integer
                          service_id:
                            type: integer
                          timestamp:
                            type: integer
                          length:
                            type: integer
                          capacity:
                            type: integer
                          clients_count:
                            type: integer
                          color:
                            type: string
                          instructions:
                            type: string
                          stream_link:
                            type: string
                          font_color:
                            type: string
                          notified:
                            type: boolean
                          comment:
                            type:
                              - string
                              - 'null'
                          schedule_id:
                            type:
                              - integer
                              - 'null'
                          schedule_till:
                            type:
                              - string
                              - 'null'
                          schedule_event_modified:
                            type:
                              - string
                              - 'null'
                          date:
                            type: string
                            format: date-time
                  meta:
                    type: array
                    items:
                      type: object
        '400':
          description: >-
            Bad Request - invalid parameters or service not available for group
            event booking
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: The service is not available for group event booking
        '401':
          description: Unauthorized - invalid or missing authentication
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '404':
          description: Not Found - location, service, or team member not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '422':
          description: Unprocessable Entity - validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: An error has occurred
                      errors:
                        type: object
                        description: Validation errors by field
                        example:
                          '[resource_instance_ids]':
                            - This field is missing.
                          '[label_ids]':
                            - This field is missing.
  /companies/{location_id}/activities/{event_id}:
    get:
      tags:
        - Events
      security:
        - BearerPartnerUser: []
      summary: Get Event (v2)
      description: |
        Returns detailed information about a specific Event using v2 API.
      operationId: get_event_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
          description: API version header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: location_id
          in: path
          required: true
          schema:
            type: integer
          description: Location (business) ID
        - name: event_id
          in: path
          required: true
          schema:
            type: integer
          description: Event ID
      responses:
        '200':
          description: Event details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Event details (JSON:API format)
                    properties:
                      type:
                        type: string
                        example: activity
                      id:
                        type: string
                        example: '10126531'
                      attributes:
                        type: object
                        properties:
                          master_id:
                            type: integer
                          staff_id:
                            type: integer
                          service_id:
                            type: integer
                          timestamp:
                            type: integer
                          length:
                            type: integer
                          capacity:
                            type: integer
                          clients_count:
                            type: integer
                          color:
                            type: string
                          instructions:
                            type: string
                          stream_link:
                            type: string
                          font_color:
                            type: string
                          notified:
                            type: boolean
                          comment:
                            type:
                              - string
                              - 'null'
                          schedule_id:
                            type:
                              - integer
                              - 'null'
                          schedule_till:
                            type:
                              - string
                              - 'null'
                          schedule_event_modified:
                            type:
                              - string
                              - 'null'
                          date:
                            type: string
                            format: date-time
                  meta:
                    type: array
                    items:
                      type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Not found
    put:
      tags:
        - Events
      security:
        - BearerPartnerUser: []
      summary: Update Event (v2)
      description: |
        Updates an existing Event using v2 API.
      operationId: update_event_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: location_id
          in: path
          required: true
          schema:
            type: integer
          description: Location (business) ID
        - name: event_id
          in: path
          required: true
          schema:
            type: integer
          description: Event ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - staff_id
                - service_id
                - resource_instance_ids
                - label_ids
                - date
                - length
                - capacity
              type: object
              properties:
                staff_id:
                  type: integer
                  description: Team member ID
                service_id:
                  type: integer
                  description: Service ID
                resource_instance_ids:
                  type: array
                  description: List of resource instance IDs (required, can be empty)
                  items:
                    type: integer
                label_ids:
                  type: array
                  description: List of category/tag IDs (required, can be empty)
                  items:
                    type: integer
                date:
                  type: string
                  format: date-time
                  description: Event date and time
                length:
                  type: integer
                  description: Event duration in seconds
                technical_break_duration:
                  oneOf:
                    - type: integer
                    - type: 'null'
                  description: Technical break duration (multiples of 300, max 3600)
                capacity:
                  type: integer
                  description: Number of available slots
                comment:
                  type: string
                  description: Event comment
                color:
                  type: string
                  description: Event color (hex format)
                instructions:
                  type: string
                  description: Instructions for the event
                stream_link:
                  type: string
                  description: Stream link for online events
                force:
                  type: boolean
                  description: Skip resource availability check
                  default: false
      responses:
        '200':
          description: Event updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Updated event details (JSON:API format)
                    properties:
                      type:
                        type: string
                        example: activity
                      id:
                        type: string
                        example: '10126531'
                      attributes:
                        type: object
                        properties:
                          master_id:
                            type: integer
                          staff_id:
                            type: integer
                          service_id:
                            type: integer
                          timestamp:
                            type: integer
                          length:
                            type: integer
                          capacity:
                            type: integer
                          clients_count:
                            type: integer
                          color:
                            type: string
                          instructions:
                            type: string
                          stream_link:
                            type: string
                          font_color:
                            type: string
                          notified:
                            type: boolean
                          comment:
                            type:
                              - string
                              - 'null'
                          schedule_id:
                            type:
                              - integer
                              - 'null'
                          schedule_till:
                            type:
                              - string
                              - 'null'
                          schedule_event_modified:
                            type:
                              - string
                              - 'null'
                          date:
                            type: string
                            format: date-time
                  meta:
                    type: array
                    items:
                      type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '422':
          description: Validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                      errors:
                        type: object
    delete:
      tags:
        - Events
      security:
        - BearerPartnerUser: []
      summary: Delete Event (v2)
      description: |
        Deletes an Event using v2 API.
      operationId: delete_event_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: location_id
          in: path
          required: true
          schema:
            type: integer
          description: Location (business) ID
        - name: event_id
          in: path
          required: true
          schema:
            type: integer
          description: Event ID
      responses:
        '204':
          description: Event deleted successfully
          content:
            application/json: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Not found
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
  /companies/{location_id}/activities/{event_id}/records:
    post:
      tags:
        - Events
      security:
        - BearerPartnerUser: []
      summary: Create Event Appointment (v2)
      description: >
        Creates an Appointment for a Client in an Event using v2 API.


        **Note:** All client fields are required even when using existing client
        ID.
      operationId: create_event_appointment_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: location_id
          in: path
          required: true
          schema:
            type: integer
          description: Location (business) ID
        - name: event_id
          in: path
          required: true
          schema:
            type: integer
          description: Event ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - client
                - clients_count
              type: object
              properties:
                client_id:
                  type: integer
                  description: Existing client ID (deprecated, use client.id instead)
                  example: 123456
                client:
                  type: object
                  required:
                    - name
                    - phone
                    - email
                    - surname
                    - gender
                  description: Client information
                  properties:
                    id:
                      type: integer
                      description: Client ID for existing client
                      example: 123456
                    name:
                      type: string
                      description: First name
                      example: John
                    phone:
                      type: string
                      description: Phone number
                      example: '+13155550175'
                    email:
                      type: string
                      description: Email address
                      example: john@example.com
                    surname:
                      type: string
                      description: Last name
                      example: Smith
                    patronymic:
                      oneOf:
                        - type: string
                        - type: 'null'
                      description: Middle name (legacy field name)
                      example: null
                    gender:
                      type: integer
                      enum:
                        - 0
                        - 1
                        - 2
                      description: 'Gender: 0 - unknown, 1 - male, 2 - female'
                      example: 0
                    birthday:
                      oneOf:
                        - type: string
                          format: date
                        - type: 'null'
                      description: Birth date
                      example: '1990-01-01'
                    custom_field_values:
                      oneOf:
                        - type: array
                          items:
                            type: object
                            properties:
                              code:
                                type: string
                                description: Custom field name
                              value:
                                type: string
                                description: Custom field value
                        - type: 'null'
                      description: Custom field values
                    agreements:
                      oneOf:
                        - type: array
                          items:
                            type: object
                            properties:
                              is_newsletter_allowed:
                                type: boolean
                                description: Newsletter consent
                              is_personal_data_processing_allowed:
                                type: boolean
                                description: Personal data processing consent
                        - type: 'null'
                      description: User agreements/consents
                comer_id:
                  type: integer
                  description: Visitor ID (alternative to client)
                  example: 500
                comer:
                  type: object
                  description: Visitor information (alternative to client)
                  properties:
                    name:
                      type: string
                      description: Visitor name
                      example: Guest User
                labels:
                  type: array
                  description: Tag IDs for this appointment
                  items:
                    type: integer
                  example:
                    - 1
                    - 2
                clients_count:
                  type: integer
                  description: Number of participants/slots to reserve
                  example: 1
      responses:
        '201':
          description: Appointment created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Created appointment details (JSON:API format)
                    properties:
                      type:
                        type: string
                        example: record
                      id:
                        type: string
                        example: '624798251'
                      attributes:
                        type: object
                        properties:
                          company_id:
                            type: integer
                          external_id:
                            type: string
                          visit_id:
                            type: integer
                          booking_user_id:
                            type: integer
                          bookform_id:
                            type: integer
                          master_id:
                            type: integer
                          staff_id:
                            type: integer
                          client_id:
                            type: integer
                          comer_id:
                            type:
                              - integer
                              - 'null'
                          source:
                            type: integer
                          attendance:
                            type: integer
                          attendance_status:
                            type: integer
                          attendance_status_slug:
                            type: string
                          client_fictive_name:
                            type:
                              - string
                              - 'null'
                          client_fictive_phone:
                            type:
                              - string
                              - 'null'
                          client_fictive_email:
                            type:
                              - string
                              - 'null'
                          clients_count:
                            type: integer
                          activity_id:
                            type: integer
                          custom_color:
                            type: string
                          custom_font_color:
                            type: string
                          length:
                            type: integer
                          duration:
                            type: integer
                          paid_full:
                            type: integer
                          is_paid:
                            type: boolean
                          is_overpaid:
                            type: boolean
                          timestamp:
                            type: integer
                          date:
                            type: string
                            format: date-time
                          created_datetime:
                            type: string
                            format: date-time
                          from_url:
                            type: string
                          is_mobile:
                            type: integer
                          comment:
                            type: string
                          prepaid_status:
                            type: integer
                          record_from:
                            type: string
                          payment_status:
                            type: integer
                          is_sale_bill_printed:
                            type: boolean
                          is_client_notification_sent:
                            type: boolean
                  meta:
                    type: array
                    items:
                      type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Not found
        '422':
          description: Validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: An error has occurred
                      errors:
                        type: object
                        description: Field-level validation errors
  /companies/{location_id}/activities/{event_id}/records/{record_id}:
    patch:
      tags:
        - Events
      security:
        - BearerPartnerUser: []
      summary: Update Event Appointment (v2)
      description: |
        Updates an existing Appointment in an Event using v2 API.

        **Note:** This endpoint uses PATCH (not POST as in some documentation).
      operationId: update_event_appointment_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: location_id
          in: path
          required: true
          schema:
            type: integer
          description: Location (business) ID
        - name: event_id
          in: path
          required: true
          schema:
            type: integer
          description: Event ID
        - name: record_id
          in: path
          required: true
          schema:
            type: integer
          description: Appointment ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - reschedule_activity_id
              type: object
              properties:
                reschedule_activity_id:
                  type: integer
                  description: Event ID to reschedule this Appointment to (required field)
                  example: 12345
                attendance_service_item:
                  type: object
                  description: Service pricing information
                  required:
                    - cost_per_unit
                    - discount_percent
                    - manual_cost
                  properties:
                    cost_per_unit:
                      type: number
                      description: Original cost per unit
                      example: 100
                    discount_percent:
                      type: number
                      description: Discount percentage
                      example: 10
                    manual_cost:
                      type: number
                      description: Final cost with discount applied
                      example: 90
                attendance_good_items:
                  type: array
                  description: Products associated with this appointment
                  items:
                    type: object
                    required:
                      - id
                      - good_id
                      - unit_id
                      - storage_id
                      - staff_id
                      - operation_unit_type
                      - quantity
                      - cost_per_unit
                      - manual_cost
                      - discount_percent
                    properties:
                      id:
                        type: integer
                        description: Product ID
                      good_id:
                        type: integer
                        description: Product ID
                      unit_id:
                        type: integer
                        description: Unit of measurement ID
                      storage_id:
                        type: integer
                        description: Inventory ID
                      staff_id:
                        type: integer
                        description: Team member ID
                      operation_unit_type:
                        type: string
                        enum:
                          - sale
                          - consumable
                          - unknown
                        description: Operation type
                      number:
                        oneOf:
                          - type: integer
                          - type: 'null'
                        description: Number if applicable
                      planned_activation_date:
                        oneOf:
                          - type: string
                            format: date-time
                          - type: 'null'
                        description: Planned activation date
                      marks:
                        type: array
                        items:
                          type: string
                        description: Marking values
                      quantity:
                        type: integer
                        description: Quantity
                      cost_per_unit:
                        type: number
                        description: Cost per unit
                      manual_cost:
                        type: number
                        description: Total cost
                      discount_percent:
                        type: number
                        description: Discount percentage
                comment:
                  type: string
                  description: Appointment comment
                  example: Updated appointment comment
                label_ids:
                  type: array
                  description: Tag IDs
                  items:
                    type: integer
                  example:
                    - 123
                    - 456
                color:
                  type: string
                  description: Appointment color (hex without
                  example: f44336
                clients_count:
                  type: integer
                  description: Number of participants
                  example: 2
      responses:
        '200':
          description: Appointment updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                  meta:
                    type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Appointment or Event not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Not found
        '422':
          description: Validation errors
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                      errors:
                        type: object
  /companies/{company_id}/tags:
    get:
      tags:
        - Tags
      security:
        - BearerPartnerUser: []
      summary: List Tags (v2)
      description: >
        Returns all tags for the specified company, optionally filtered by
        entity type.


        Response uses [JSON:API](https://jsonapi.org/) format where `type:
        "tag"` is the resource type name (not to be confused with `entity_type`
        attribute).


        **Entity types:**

        - `common` (0) - General tags

        - `client` (1) - Client tags

        - `record` (2) - Appointment/record tags

        - `activity` (3) - Activity/event tags


        Use the `entity` query parameter to filter by type. Accepts both string
        aliases and numeric values.
      operationId: list_tags_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
          description: API version header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
        - name: entity
          in: query
          required: false
          schema:
            type: string
            enum:
              - common
              - client
              - record
              - activity
              - '0'
              - '1'
              - '2'
              - '3'
          description: Filter by entity type (alias or numeric code)
          example: client
      responses:
        '200':
          description: Tags retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          example: tag
                        id:
                          type: string
                          example: '241625'
                        attributes:
                          $ref: '#/components/schemas/tag_v2_attributes'
                  meta:
                    type: array
                    items:
                      type: object
              example:
                data:
                  - type: tag
                    id: '241625'
                    attributes:
                      company_id: 68570
                      title: VIP client
                      color: '#ff2828'
                      font_color: '#ffffff'
                      icon: star
                      entity_type: client
                      is_deleted: false
                      is_editable: true
                  - type: tag
                    id: '241626'
                    attributes:
                      company_id: 68570
                      title: Regular client
                      color: '#009800'
                      font_color: '#ffffff'
                      icon: user
                      entity_type: client
                      is_deleted: false
                      is_editable: true
                meta: []
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '403':
          description: Forbidden - No permission to manage this company
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Not found
    post:
      tags:
        - Tags
      security:
        - BearerPartnerUser: []
      summary: Create Tag (v2)
      description: |
        Creates a new tag for the specified company.
      operationId: create_tag_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - title
                - color
              type: object
              properties:
                title:
                  type: string
                  description: Tag name
                  example: VIP Client
                color:
                  type: string
                  description: Tag color in
                  example: '#ff2828'
                entity:
                  type: integer
                  description: >-
                    Entity type (0 - general, 1 - client, 2 - appointment, 3 -
                    activity)
                  enum:
                    - 0
                    - 1
                    - 2
                    - 3
                  default: 0
                icon:
                  type: string
                  description: Icon name
                  example: star
      responses:
        '200':
          description: Tag created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        example: tag
                      id:
                        type: string
                        example: '241627'
                      attributes:
                        $ref: '#/components/schemas/tag_v2_attributes'
                  meta:
                    type: array
                    items:
                      type: object
              example:
                data:
                  type: tag
                  id: '241627'
                  attributes:
                    company_id: 68570
                    title: VIP Client
                    color: '#ff2828'
                    font_color: '#ffffff'
                    icon: star
                    entity_type: client
                    is_deleted: false
                    is_editable: true
                meta: []
        '400':
          description: Bad Request - Invalid entity type
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Endpoint not found (not yet deployed)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '422':
          description: Validation Error - Missing required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: >-
                          Required parameter title was not passed. Enter a
                          category name
  /companies/{company_id}/tags/{tag_id}:
    get:
      tags:
        - Tags
      security:
        - BearerPartnerUser: []
      summary: Get Tag (v2)
      description: >
        Returns detailed information about a specific tag.


        Response uses [JSON:API](https://jsonapi.org/) format where `type:
        "tag"` is the resource type name.
      operationId: get_tag_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
          description: API version header
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
        - name: tag_id
          in: path
          required: true
          schema:
            type: integer
          description: Tag ID
      responses:
        '200':
          description: Tag details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        example: tag
                      id:
                        type: string
                        example: '241625'
                      attributes:
                        $ref: '#/components/schemas/tag_v2_attributes'
                  meta:
                    type: array
                    items:
                      type: object
              example:
                data:
                  type: tag
                  id: '241625'
                  attributes:
                    company_id: 68570
                    title: VIP client
                    color: '#ff2828'
                    font_color: '#ffffff'
                    icon: star
                    entity_type: client
                    is_deleted: false
                    is_editable: true
                meta: []
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
        '404':
          description: Tag not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Not found
    put:
      tags:
        - Tags
      security:
        - BearerPartnerUser: []
      summary: Update Tag (v2)
      description: |
        Updates an existing tag.
      operationId: update_tag_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            default: application/json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
        - name: tag_id
          in: path
          required: true
          schema:
            type: integer
          description: Tag ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Tag name
                  example: VIP Client
                color:
                  type: string
                  description: Tag color in
                  example: '#ff2828'
                entity:
                  type: integer
                  description: >-
                    Entity type (0 - general, 1 - client, 2 - appointment, 3 -
                    activity)
                  enum:
                    - 0
                    - 1
                    - 2
                    - 3
                icon:
                  type: string
                  description: Icon name
                  example: star
      responses:
        '204':
          description: Tag updated successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden - Tag is not editable or belongs to another company
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Category cannot be changed
        '404':
          description: Tag not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
    delete:
      tags:
        - Tags
      security:
        - BearerPartnerUser: []
      summary: Delete Tag (v2)
      description: |
        Deletes a tag (soft delete - marks as deleted).
      operationId: delete_tag_v2
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            default: application/vnd.api.v2+json
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          description: Bearer {partner_token}, User {user_token}
        - name: company_id
          in: path
          required: true
          schema:
            type: integer
          description: Company (location) ID
        - name: tag_id
          in: path
          required: true
          schema:
            type: integer
          description: Tag ID
      responses:
        '204':
          description: Tag deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '403':
          description: Forbidden - Tag is not editable or belongs to another company
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
        '404':
          description: Tag not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  data:
                    type: 'null'
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Not found
