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

# Create planner item

> Create a new planner item. Can optionally be associated with a company and type.



## OpenAPI

````yaml /openapi.json post /api/public/v1/planner/items
openapi: 3.0.3
info:
  title: MSPortal Public API
  version: 1.0.0
  description: >-
    Public API for MSPortal - provides programmatic access to tenant data.


    ## Authentication


    All endpoints require authentication via API key passed as a Bearer token:


    ```

    Authorization: Bearer <your-api-key>

    ```


    API keys can be created in the MSPortal dashboard under Settings →
    Integrations → API Access.


    **Important:** Do not include cookies in API requests. The public API uses
    stateless authentication only.


    ## Scopes


    API keys are granted specific scopes that determine what operations they can
    perform. Each endpoint documents its required scope(s).


    ## Rate Limiting


    API calls are rate limited per API key. Rate limit information is returned
    in response headers:


    - `X-RateLimit-Limit`: Maximum requests per minute

    - `X-RateLimit-Remaining`: Remaining requests in current window

    - `X-RateLimit-Reset`: When the rate limit resets (ISO 8601)


    ## Request ID


    All responses include an `X-Request-Id` header for debugging and support.
    You can also pass your own `X-Request-Id` header to correlate requests.
  contact:
    name: MSPortal Support
    email: support@msportal.ai
  license:
    name: Proprietary
servers:
  - url: https://app.msportal.ai
    description: Production environment
security:
  - BearerAuth: []
tags:
  - name: Budgets
    description: >-
      Budget management - create, track, and forecast budgets with line items,
      categories, and products
  - name: Calendar
    description: Calendar and meeting management - events, participants, and meeting types
  - name: Companies
    description: Company management endpoints
  - name: Company Users
    description: Company user management - client portal contacts (read-only, paginated)
  - name: Compliance
    description: Compliance check management - runs, assigned checks, and status updates
  - name: Dashboards
    description: Dashboard management - external iframe resources and internal dashboards
  - name: Devices
    description: Device management - inventory, types, and locations
  - name: Goals
    description: Goal management - create, track, and manage goals with tasks and updates
  - name: NPS Surveys
    description: >-
      NPS survey management - Net Promoter Score surveys, responses, and
      analytics
  - name: Reports
    description: >-
      Report management - create, manage, and schedule reports with templates
      and types
  - name: Planner
    description: >-
      Planner item management - tasks, roadmap items, and project planning with
      linked goals, compliance, and projects
  - name: Surveys
    description: >-
      General survey management - multi-question surveys, responses, and
      statistics
  - name: Tickets
    description: Ticket management - view and filter tickets from PSA integrations
  - name: Training
    description: >-
      Training management - courses, enrollments, certificates, and progress
      tracking
  - name: Users
    description: Tenant user management - internal staff and team members (read-only)
  - name: Automation Rules
    description: >-
      Automation rule management - create, configure, and monitor automation
      rules with triggers, conditions, and actions
  - name: Analytics
    description: >-
      Analytics and reporting - company audit data, training analytics, user
      activity, and portfolio metrics
paths:
  /api/public/v1/planner/items:
    post:
      tags:
        - Planner
      summary: Create planner item
      description: >-
        Create a new planner item. Can optionally be associated with a company
        and type.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlannerItemRequest'
      responses:
        '201':
          description: Planner item created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlannerItemSingleResponse'
        '400':
          description: Validation error or invalid reference ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Missing required scope (planner.write)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    CreatePlannerItemRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 255
          description: Item title (required)
        description:
          type: string
          maxLength: 10000
          description: Item description
        companyId:
          type: string
          format: uuid
          description: Company ID
        typeId:
          type: string
          format: uuid
          description: Planner item type ID
        status:
          allOf:
            - $ref: '#/components/schemas/PlannerStatus'
            - description: 'Status (default: Not Started)'
        businessValue:
          allOf:
            - $ref: '#/components/schemas/BusinessValue'
            - description: 'Business value (default: Medium)'
        hours:
          type: number
          minimum: 0
          description: 'Estimated hours (default: 0)'
        costEstimate:
          type: number
          minimum: 0
          description: 'Cost estimate (default: 0)'
        probability:
          type: number
          minimum: 0
          maximum: 100
          description: 'Completion probability (default: 50)'
        startDate:
          type: string
          format: date-time
          description: Start date (ISO 8601)
        dueDate:
          type: string
          format: date-time
          description: Due date (ISO 8601)
        endDate:
          type: string
          format: date-time
          description: End date (ISO 8601)
        publicNotes:
          type: string
          maxLength: 10000
          description: Public notes
        privateNotes:
          type: string
          maxLength: 10000
          description: Private notes (internal only)
        isArchived:
          type: boolean
          description: 'Whether the item is archived (default: false)'
      required:
        - title
    PlannerItemSingleResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PlannerItemDetail'
      required:
        - data
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        requestId:
          type: string
          description: Request correlation ID
        details:
          nullable: true
          description: Additional error details
        code:
          type: string
          description: Error code
      required:
        - error
    PlannerStatus:
      type: string
      enum:
        - In Progress
        - Not Started
        - Completed
        - On Hold
        - Cancelled
        - Pending Approval
    BusinessValue:
      type: string
      enum:
        - High
        - Medium
        - Low
    PlannerItemDetail:
      allOf:
        - $ref: '#/components/schemas/PlannerItem'
        - type: object
          properties:
            linkedGoals:
              type: array
              items:
                $ref: '#/components/schemas/PlannerLinkedGoal'
              description: Linked goals
            linkedCompliance:
              type: array
              items:
                $ref: '#/components/schemas/PlannerLinkedCompliance'
              description: Linked compliance items
            linkedProjects:
              type: array
              items:
                $ref: '#/components/schemas/PlannerLinkedProject'
              description: Linked projects
            linkedOpportunities:
              type: array
              items:
                $ref: '#/components/schemas/PlannerLinkedOpportunity'
              description: Linked opportunities
            linkedSecureScore:
              type: array
              items:
                $ref: '#/components/schemas/PlannerLinkedSecureScore'
              description: Linked secure score controls
            tags:
              type: array
              items:
                type: string
              description: Tags
          required:
            - linkedGoals
            - linkedCompliance
            - linkedProjects
            - linkedOpportunities
            - linkedSecureScore
            - tags
    PlannerItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Planner item ID
        title:
          type: string
          description: Item title
        description:
          type: string
          nullable: true
          description: Item description
        status:
          $ref: '#/components/schemas/PlannerStatus'
        businessValue:
          $ref: '#/components/schemas/BusinessValue'
        hours:
          type: number
          minimum: 0
          description: Estimated hours
        costEstimate:
          type: number
          minimum: 0
          description: Cost estimate
        probability:
          type: number
          minimum: 0
          maximum: 100
          description: Completion probability (0-100)
        startDate:
          type: string
          nullable: true
          format: date-time
          description: Start date (ISO 8601)
        dueDate:
          type: string
          nullable: true
          format: date-time
          description: Due date (ISO 8601)
        endDate:
          type: string
          nullable: true
          format: date-time
          description: End date (ISO 8601)
        publicNotes:
          type: string
          nullable: true
          description: Public notes (client-visible)
        privateNotes:
          type: string
          nullable: true
          description: Private notes (internal only, not visible to client portal users)
        isArchived:
          type: boolean
          description: Whether the item is archived
        isOverdue:
          type: boolean
          description: Whether the item is overdue
        fiscalYear:
          type: number
          nullable: true
          description: Fiscal year
        fiscalQuarter:
          type: number
          nullable: true
          description: Fiscal quarter (1-4)
        company:
          $ref: '#/components/schemas/PlannerCompanyRef'
        type:
          $ref: '#/components/schemas/PlannerTypeRef'
        linkedGoalsCount:
          type: number
          description: Number of linked goals
        linkedComplianceCount:
          type: number
          description: Number of linked compliance items
        linkedMeetingsCount:
          type: number
          description: Number of linked meetings
        linkedProjectsCount:
          type: number
          description: Number of linked projects
        linkedSecureScoreCount:
          type: number
          description: Number of linked secure score controls
        tagCount:
          type: number
          description: Number of tags
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601)
      required:
        - id
        - title
        - description
        - status
        - businessValue
        - hours
        - costEstimate
        - probability
        - startDate
        - dueDate
        - endDate
        - publicNotes
        - privateNotes
        - isArchived
        - isOverdue
        - fiscalYear
        - fiscalQuarter
        - company
        - type
        - linkedGoalsCount
        - linkedComplianceCount
        - linkedMeetingsCount
        - linkedProjectsCount
        - linkedSecureScoreCount
        - tagCount
        - createdAt
        - updatedAt
    PlannerLinkedGoal:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Goal ID
        title:
          type: string
          description: Goal title
        customTitle:
          type: string
          nullable: true
          description: Custom title override
      required:
        - id
        - title
        - customTitle
    PlannerLinkedCompliance:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Compliance assigned ID
        title:
          type: string
          description: Compliance check title
        customTitle:
          type: string
          nullable: true
          description: Custom title override
      required:
        - id
        - title
        - customTitle
    PlannerLinkedProject:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Integration project ID
        name:
          type: string
          nullable: true
          description: Project name
        externalId:
          type: string
          nullable: true
          description: External project ID
        provider:
          type: string
          nullable: true
          description: PSA provider
      required:
        - id
        - name
        - externalId
        - provider
    PlannerLinkedOpportunity:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Integration opportunity ID
        summary:
          type: string
          nullable: true
          description: Opportunity summary
        externalId:
          type: string
          nullable: true
          description: External opportunity ID
        provider:
          type: string
          nullable: true
          description: PSA provider
      required:
        - id
        - summary
        - externalId
        - provider
    PlannerLinkedSecureScore:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Secure score control ID
        title:
          type: string
          nullable: true
          description: Control title
        customTitle:
          type: string
          nullable: true
          description: Custom title override
        actionUrl:
          type: string
          nullable: true
          description: Action URL
      required:
        - id
        - title
        - customTitle
        - actionUrl
    PlannerCompanyRef:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
          description: Company ID
        name:
          type: string
          description: Company name
      required:
        - id
        - name
    PlannerTypeRef:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
          description: Type ID
        name:
          type: string
          description: Type name
      required:
        - id
        - name
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Use your API key as a Bearer token. API keys can be generated in
        Settings → Integrations → API Access.

````