Charthop goal API

swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access goal API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
host: localhost
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: goal
paths:
  /v1/org/{orgId}/goal:
    get:
      tags:
      - goal
      summary: Find goals
      operationId: findGoals
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: personId
        in: query
        description: Person id to filter goals by (owner or support)
        required: false
        type: string
      - name: groupId
        in: query
        description: Group id to filter goals by
        required: false
        type: string
      - name: personFilter
        in: query
        description: Person filter
        required: false
        type: string
      - name: originalGoalId
        in: query
        description: Original goal id to filter by
        required: false
        type: string
      - name: date
        in: query
        description: Date to filter goals as-of
        required: false
        type: string
        format: date
      - name: fromId
        in: query
        description: Starting goal id for pagination
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        type: integer
        format: int32
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsGoal'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    post:
      tags:
      - goal
      summary: Create a new goal
      operationId: createGoal
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Goal data to create
        required: true
        schema:
          $ref: '#/definitions/CreateGoal'
      responses:
        '201':
          description: created
          schema:
            $ref: '#/definitions/Goal'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/goal/export:
    post:
      tags:
      - goal
      summary: Export goals to CSV format
      operationId: exportGoals
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: date
        in: query
        description: Date to filter goals as-of
        required: false
        type: string
        format: date
      - name: personFilter
        in: query
        description: Person filter
        required: false
        type: string
      - name: format
        in: query
        description: Output format (e.g. readable for friendly column headers)
        required: false
        type: string
      responses:
        '201':
          description: process started
          schema:
            $ref: '#/definitions/Process'
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/goal/{goalId}:
    get:
      tags:
      - goal
      summary: Get a goal by id
      operationId: getGoal
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: goalId
        in: path
        description: Goal id
        required: true
        type: string
      responses:
        '200':
          description: ok
          schema:
            $ref: '#/definitions/Goal'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    patch:
      tags:
      - goal
      summary: Update an existing goal
      operationId: updateGoal
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: goalId
        in: path
        description: Goal id
        required: true
        type: string
      - name: body
        in: body
        description: Goal data to update
        required: true
        schema:
          $ref: '#/definitions/UpdateGoal'
      responses:
        '200':
          description: updated
          schema:
            $ref: '#/definitions/Goal'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    delete:
      tags:
      - goal
      summary: Delete a goal
      operationId: deleteGoal
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: goalId
        in: path
        description: Goal id
        required: true
        type: string
      responses:
        '204':
          description: deleted
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/goal/{goalId}/copy:
    post:
      tags:
      - goal
      summary: Copy a goal and its targets into a new goal
      operationId: copyGoal
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: goalId
        in: path
        description: Goal id to copy
        required: true
        type: string
      - name: body
        in: body
        description: Optional property overrides for the copied goal
        required: false
        schema:
          $ref: '#/definitions/UpdateGoal'
      responses:
        '201':
          description: created
          schema:
            $ref: '#/definitions/Goal'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/goal/{goalId}/graph:
    get:
      tags:
      - goal
      summary: Find parent and child goals, from a starting goal id
      operationId: findGoalsGraph
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: goalId
        in: path
        description: Starting goal id to look upwards and downwards from
        required: true
        type: string
      - name: date
        in: query
        description: Date to filter goals as-of
        required: false
        type: string
        format: date
      - name: depth
        in: query
        description: Number of levels down to search child goals (defaults to 1)
        required: false
        type: integer
        format: int32
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsGoal'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
definitions:
  AccessAction:
    type: object
    required:
    - action
    properties:
      action:
        type: string
      fields:
        type: array
        uniqueItems: true
        items:
          type: string
      types:
        type: array
        uniqueItems: true
        items:
          type: string
  Goal:
    type: object
    required:
    - id
    - orgId
    - status
    - goalTypeId
    - label
    - slug
    - startDate
    - endDate
    - sensitive
    - shareAccess
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      orgId:
        type: string
        description: parent organization id
        example: 588f7ee98f138b19220041a7
      status:
        type: string
        description: status
        enum:
        - DRAFT
        - ACTIVE
        - DONE
      goalTypeId:
        type: string
        description: goal type
        example: 588f7ee98f138b19220041a7
      parentGoalId:
        type: string
        description: parent goal id, for cascading goals
        example: 588f7ee98f138b19220041a7
      originalGoalId:
        type: string
        description: original goal id, linking this goal to the goal it was copied from
        example: 588f7ee98f138b19220041a7
      relatedGoalIds:
        type: array
        description: list of other goals that are related to this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      ownerPersonIds:
        type: array
        description: list of persons who are responsible for this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      supportPersonIds:
        type: array
        description: list of persons who help support this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      groupIds:
        type: array
        description: list of groups who are responsible for this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      label:
        type: string
        description: human-readable name of the goal
        example: Increase Revenue at least 10%
      slug:
        type: string
        description: url-safe slug for the goal, auto-generated from label if not provided
      description:
        type: string
        description: human-readable description of the goal
      startDate:
        type: string
        format: date
        description: start date for this goal
      endDate:
        type: string
        format: date
        description: end date for this goal
      sensitive:
        type: string
        description: sensitivity level of goal
        enum:
        - GLOBAL
        - ORG
        - SENSITIVE
        - PERSONAL
        - MANAGER
        - HIGH
        - PRIVATE
      shareAccess:
        type: array
        description: users who are specifically granted permission to view or edit this goal
        items:
          $ref: '#/definitions/ShareAccess'
      progressUpdateConfig:
        description: configuration for automated progress update reminders
        $ref: '#/definitions/GoalProgressUpdateConfig'
      progressSummary:
        description: overall progress summary, denormalized and calculated periodically
        $ref: '#/definitions/GoalProgressSummary'
      createId:
        type: string
        description: created by user id
        example: 588f7ee98f138b19220041a7
      createBehalfId:
        type: string
        description: created on behalf of user id
        example: 588f7ee98f138b19220041a7
      createAttribution:
        $ref: '#/definitions/Attribution'
      createAt:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      updateId:
        type: string
        description: last updated by user id
        example: 588f7ee98f138b19220041a7
      updateBehalfId:
        type: string
        description: last updated on behalf of user id
        example: 588f7ee98f138b19220041a7
      updateAttribution:
        $ref: '#/definitions/Attribution'
      updateAt:
        type: string
        description: last updated timestamp
        example: '2017-01-24T13:57:52Z'
      deleteId:
        type: string
        description: deleted by user id
        example: 588f7ee98f138b19220041a7
      deleteBehalfId:
        type: string
        description: deleted on behalf of user id
        example: 588f7ee98f138b19220041a7
      deleteAttribution:
        $ref: '#/definitions/Attribution'
      deleteAt:
        type: string
        description: deleted timestamp
        example: '2017-01-24T13:57:52Z'
  GoalTargetWithValue:
    type: object
    required:
    - goalTargetId
    - label
    - value
    properties:
      goalTargetId:
        type: string
        example: 588f7ee98f138b19220041a7
      label:
        type: string
      value:
        anyOf:
        - type: string
        - type: number
        - type: boolean
      color:
        type: string
  ResultsAccess:
    type: object
    required:
    - allowed
    properties:
      ids:
        type: array
        uniqueItems: true
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      allowed:
        type: array
        uniqueItems: true
        items:
          $ref: '#/definitions/AccessAction'
  GoalTargetActual:
    type: object
    required:
    - goalTargetId
    properties:
      goalTargetId:
        type: string
        example: 588f7ee98f138b19220041a7
      value:
        anyOf:
        - type: string
        - type: number
        - type: boolean
  Process:
    type: object
    required:
    - id
    - orgId
    - label
    - type
    - status
    - runUserId
    - createId
    - createAt
    - options
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      orgId:
        type: string
        description: parent org id
        example: 588f7ee98f138b19220041a7
      label:
        type: string
        description: human-readable label that identifies this process
      type:
        type: string
        description: process type
      status:
        type: string
        description: current status of process
        enum:
        - PENDING
        - RUNNING
        - DONE
        - ERROR
      filePath:
        type: string
        description: data file path
      logPath:
        type: string
        description: data log path
      runUserId:
        type: string
        description: user id who is running the process
        example: 588f7ee98f138b19220041a7
      parentProcessId:
        type: string
        description: process id of parent process
        example: 588f7ee98f138b19220041a7
      createId:
        type: string
        description: created by user id (user who requested the process run)
        example: 588f7ee98f138b19220041a7
      createBehalfId:
        type: string
        description: created on behalf of user id
        example: 588f7ee98f138b19220041a7
      createAttribution:
        $ref: '#/definitions/Attribution'
      createAt:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      updateId:
        type: string
        description: last updated by user id
        example: 588f7ee98f138b19220041a7
      updateBehalfId:
        type: string
        description: last updated on behalf of user id
        example: 588f7ee98f138b19220041a7
      updateAttribution:
        $ref: '#/definitions/Attribution'
      updateAt:
        type: string
        description: last updated timestamp
        example: '2017-01-24T13:57:52Z'
      startAt:
        type: string
        description: started at timestamp
        example: '2017-01-24T13:57:52Z'
      endAt:
        type: string
        description: ended at timestamp
        example: '2017-01-24T13:57:52Z'
      message:
        type: string
        description: status or error message
      progress:
        type: number
        format: double
        description: percent progress so far
      internalError:
        type: string
        description: internal-only error message
      options:
        type: object
        description: options passed to the process
      results:
        type: object
        description: results summary for the process
        additionalProperties:
          type: object
      logDataList:
        type: array
        description: list of log data that occurred during running of this process
        items:
          $ref: '#/definitions/LogData'
      state:
        type: object
        description: process-specific state data
      summary:
        type: string
        description: human-readable, searchable summary of what this process did
      appId:
        type: string
        description: app id of the process
        example: 588f7ee98f138b19220041a7
      uuid:
        type: string
        description: unique ID of the process at queue time
        example: 84db3c6e-0877-4436-8af1-768c06b29586
  LogData:
    type: object
    required:
    - level
    - at
    - data
    properties:
      level:
        type: string
        enum:
        - INFO
        - WARN
        - ERROR
      at:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      message:
        type: string
      data:
        type: object
        additionalProperties:
          type: object
  ResultsGoal:
    type: object
    required:
    - data
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Goal'
      next:
        type: string
      access:
        type: array
        items:
          $ref: '#/definitions/ResultsAccess'
  GoalProgressForecast:
    type: object
    required:
    - goalTargetId
    - type
    - value
    properties:
      goalTargetId:
        type: string
        example: 588f7ee98f138b19220041a7
      type:
        type: string
        enum:
        - WORST
        - COMMIT
        - CALL
        - LIKELY
        - BEST
      label:
        type: string
      value:
        anyOf:
        - type: string
        - type: number
        - type: boolean
  MessageChannelConfig:
    type: object
    required:
    - channels
    - alwaysEmail
    properties:
      channels:
        type: array
        items:
          type: string
          enum:
          - EMAIL
          - CHAT
          - CHAT_SLACK
          - CHAT_TEAMS
      alwaysEmail:
        type: boolean
  CreateGoal:
    type: object
    required:
    - goalTypeId
    - label
    - startDate
    - endDate
    - sensitive
    properties:
      goalTypeId:
        type: string
        description: goal type
        example: 588f7ee98f138b19220041a7
      parentGoalId:
        type: string
        description: parent goal id, for cascading goals
        example: 588f7ee98f138b19220041a7
      originalGoalId:
        type: string
        description: original goal id, linking this goal to the goal it was copied from
        example: 588f7ee98f138b19220041a7
      relatedGoalIds:
        type: array
        description: list of other goals that are related to this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      ownerPersonIds:
        type: array
        description: list of persons who are responsible for this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      supportPersonIds:
        type: array
        description: list of persons who help support this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      groupIds:
        type: array
        description: list of groups who are responsible for this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      label:
        type: string
        description: human-readable name of the goal
        example: Increase Revenue at least 10%
      slug:
        type: string
        description: url-safe slug for the goal, auto-generated from label if not provided
      description:
        type: string
        description: human-readable description of the goal
      startDate:
        type: string
        format: date
        description: start date for this goal
      endDate:
        type: string
        format: date
        description: end date for this goal
      sensitive:
        type: string
        description: sensitivity level of goal
        enum:
        - GLOBAL
        - ORG
        - SENSITIVE
        - PERSONAL
        - MANAGER
        - HIGH
        - PRIVATE
      shareAccess:
        type: array
        description: users who are specifically granted permission to view or edit this goal
        items:
          $ref: '#/definitions/ShareAccess'
      progressUpdateConfig:
        description: configuration for automated progress update reminders
        $ref: '#/definitions/GoalProgressUpdateConfig'
  ShareAccess:
    type: object
    required:
    - access
    properties:
      access:
        type: string
        description: access permission level
        enum:
        - NONE
        - LIMITED_READ
        - LIMITED_WRITE
        - STANDARD_READ
        - STANDARD_WRITE
        - COMPENSATION_READ
        - FULL_READ
        - COMP_PLANNING_PARTICIPANT
        - COMPENSATION_WRITE
        - WRITE
        - COMPENSATION_OWNER
        - OWNER
      userId:
        type: string
        description: user id
        example: 5887a7718f138b6a2a0041a7
      groupId:
        type: string
        description: group id
        example: 5887a7718f138b6a2a0041a7
      fields:
        type: string
        description: fields
        example: name,image,title
  Attribution:
    type: object
    properties:
      principalUserId:
        type: string
        example: 588f7ee98f138b19220041a7
      agentUserIds:
        type: array
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      eventId:
        type: string
        example: 588f7ee98f138b19220041a7
      aiChatId:
        type: string
        example: 588f7ee98f138b19220041a7
      aiToolUseId:
        type: string
      channel:
        type: string
        enum:
        - WEB
        - MOBILE
        - SLACK
        - TEAMS
        - MCP
  GoalProgressSummary:
    type: object
    properties:
      id:
        type: string
        example: 588f7ee98f138b19220041a7
      percent:
        type: number
      confidence:
        type: integer
        format: int32
      done:
        type: integer
        format: int32
      progressAt:
        type: string
      at:
        type: string
      actuals:
        type: array
        items:
          $ref: '#/definitions/GoalTargetActual'
      forecasts:
        type: array
        items:
          $ref: '#/definitions/GoalProgressForecast'
      targetValues:
        type: array
        items:
          $ref: '#/definitions/GoalTargetWithValue'
      comment:
        type: string
  GoalProgressUpdateConfig:
    type: object
    required:
    - schedule
    properties:
      schedule:
        type: string
        description: schedule to send progress reminders, in crontab format
        example: 5 4 * * *
      messageChannel:
        description: the channel to send progress reminders to
        $ref: '#/definitions/MessageChannelConfig'
      message:
        type: string
        description: custom message, if any, to include with progress reminders
  UpdateGoal:
    type: object
    properties:
      goalTypeId:
        type: string
        description: goal type
        example: 588f7ee98f138b19220041a7
      parentGoalId:
        type: string
        description: parent goal id, for cascading goals
        example: 588f7ee98f138b19220041a7
      originalGoalId:
        type: string
        description: original goal id, linking this goal to the goal it was copied from
        example: 588f7ee98f138b19220041a7
      relatedGoalIds:
        type: array
        description: list of other goals that are related to this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      ownerPersonIds:
        type: array
        description: list of persons who are responsible for this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      supportPersonIds:
        type: array
        description: list of persons who help support this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      groupIds:
        type: array
        description: list of groups who are responsible for this goal
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      label:
        type: string
        description: human-readable name of the goal
        example: Increase Revenue at least 10%
      slug:
        type: string
        description: url-safe slug for the goal, auto-generated from label if not provided
      description:
        type: string
        description: human-readable description of the goal
      startDate:
        type: string
        format: date
        description: start date for this goal
      endDate:
        type: string
        format: date
        description: end date for this goal
      sensitive:
        type: string
        description: sensitivity level of goal
        enum:
        - GLOBAL
        - ORG
        - SENSITIVE
        - PERSONAL
        - MANAGER
        - HIGH
        - PRIVATE
      shareAccess:
        type: array
        description: users who are specifically granted permission to view or edit this goal
        items:
          $ref: '#/definitions/ShareAccess'
      progressUpdateConfig:
        description: configuration for automated progress update reminders
        $ref: '#/definitions/GoalProgressUpdateConfig'