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

# Create package

> Creates a new equipment package (onboarding bundle) for the caller's organization. The package defines which SKUs are automatically ordered when a new joiner is onboarded. Gated by a feature flag; returns 403 when the flag is disabled.



## OpenAPI

````yaml /openapi.json post /api/v1/packages
openapi: 3.1.0
info:
  title: Firstbase API Specification
  description: Integration endpoints for Firstbase
  version: 0.1.0
servers:
  - url: http://localhost:8081
    description: Production
security:
  - ApiKey: []
tags:
  - name: Catalog
    description: Browse SKUs, brands, and categories
  - name: Inventory
    description: Query and manage inventory items and assets
  - name: Inventory Levels
    description: Configure inventory levels by SKU and warehouse
  - name: Inventory Orders
    description: Create and manage inventory orders
  - name: ITAD
    description: IT asset disposition requests
  - name: New Joiners
    description: Track and remind new joiners
  - name: Offices
    description: Manage office locations
  - name: Orders
    description: Create and track equipment orders
  - name: Packages
    description: Manage equipment packages
  - name: People
    description: Provision and manage users
  - name: Regions
    description: Query regions
  - name: Replacements
    description: Create and manage equipment replacements
  - name: Returns
    description: Create and manage returns
  - name: Shipment
    description: Look up shipments and carriers
  - name: Shipment Notices
    description: Create and manage shipment notices
  - name: Warehouses
    description: Query warehouses
paths:
  /api/v1/packages:
    post:
      tags:
        - Packages
      summary: Create package
      description: >-
        Creates a new equipment package (onboarding bundle) for the caller's
        organization. The package defines which SKUs are automatically ordered
        when a new joiner is onboarded. Gated by a feature flag; returns 403
        when the flag is disabled.
      operationId: createPackage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePackageRequest'
            example:
              name: Engineering Starter Kit
              approval_required: false
              require_justification: false
              automatic_order: false
              default_office_id: 3a68a467-8733-4c8d-a942-16ed7ec33018
              delivery_setting: PERSON
              note: Standard package for new engineering hires
              sku_ids: []
              rules:
                - category_code: LAPTOP
                  quantity: 1
                  optional: false
        required: true
      responses:
        '201':
          description: Package created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePackageResponse'
        '400':
          description: Invalid request — validation error or missing required field
        '403':
          description: Feature flag disabled or access denied
        '404':
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
        '409':
          description: Conflict
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PublicApiHttpErrors'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl -sS -X POST 'http://localhost:8081/api/v1/packages' \
              -H 'Authorization: ApiKey YOUR_API_KEY' \
              -H 'Accept: application/json' \
              -H 'Content-Type: application/json' \
              -d '{
                "name": "Engineering Starter Kit",
                "approval_required": false,
                "require_justification": false,
                "automatic_order": false,
                "default_office_id": "3a68a467-8733-4c8d-a942-16ed7ec33018",
                "delivery_setting": "PERSON",
                "note": "Standard package for new engineering hires",
                "sku_ids": [],
                "rules": [
                  {
                    "category_code": "LAPTOP",
                    "quantity": 1,
                    "optional": false
                  }
                ]
              }'
components:
  schemas:
    CreatePackageRequest:
      type: object
      description: Request body for creating a package
      properties:
        name:
          type: string
          description: Display name of the package.
          example: Engineering Starter Kit
          minLength: 1
        approval_required:
          type: boolean
          description: >-
            When true, orders created from this package require admin approval
            before fulfillment.
          example: false
        require_justification:
          type: boolean
          description: >-
            When true, requesters must provide a justification when ordering
            from this package.
          example: false
        automatic_order:
          type: boolean
          description: >-
            When true, assigning this package to a person can trigger automatic
            equipment ordering.
          example: false
        default_office_id:
          type: string
          format: uuid
          description: >-
            Default office UUID used when the package delivery setting targets
            an office.
          example: 3a68a467-8733-4c8d-a942-16ed7ec33018
        delivery_setting:
          type: string
          description: >-
            Where package equipment should be delivered (for example PERSON or
            OFFICE).
          enum:
            - PERSON
            - OFFICE
            - FLEXIBLE
          example: PERSON
        note:
          type: string
          description: Optional note shown with the package.
          example: Standard package for new engineering hires
        sku_ids:
          type: array
          description: SKU UUIDs included in this package.
          items:
            type: string
            format: uuid
        rules:
          type: array
          description: Category quantity rules for the package.
          items:
            $ref: '#/components/schemas/PackageRuleRequest'
      required:
        - approval_required
        - automatic_order
        - delivery_setting
        - name
        - require_justification
    CreatePackageResponse:
      type: object
      description: Response body after creating a package
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the package
          example: 3a68a467-8733-4c8d-a942-16ed7ec33018
        name:
          type: string
          description: Display name of the package.
          example: Engineering Starter Kit
        slug:
          type: string
          description: URL-safe unique identifier for the package
          example: engineering-starter-kit
        active:
          type: boolean
          description: Whether the package is active
          example: true
        approval_required:
          type: boolean
          description: >-
            When true, orders created from this package require admin approval
            before fulfillment.
          example: false
        require_justification:
          type: boolean
          description: >-
            When true, requesters must provide a justification when ordering
            from this package.
          example: false
        automatic_order:
          type: boolean
          description: >-
            When true, assigning this package can trigger automatic equipment
            ordering.
          example: false
        it_closet:
          type: boolean
          description: When true, the package is intended for IT closet / office stock.
          example: false
        delivery_setting:
          type: string
          description: Where package equipment should be delivered
          enum:
            - PERSON
            - OFFICE
            - FLEXIBLE
          example: PERSON
        note:
          type: string
          description: Optional note shown with the package
          example: Standard package for new engineering hires
        default_office_id:
          type: string
          format: uuid
          description: Default office UUID when delivery targets an office
          example: 3a68a467-8733-4c8d-a942-16ed7ec33018
        sku_ids:
          type: array
          description: SKU UUIDs included in this package
          items:
            type: string
            format: uuid
        rules:
          type: array
          description: Category quantity rules for the package
          items:
            $ref: '#/components/schemas/PackageRuleResponse'
        number_ordered:
          type: integer
          format: int32
          description: Count of orders placed against this package
          example: 0
        number_deployed:
          type: integer
          format: int32
          description: Count of package assignments that have been deployed
          example: 0
        created_at:
          type: string
          format: date-time
          description: Timestamp when the package was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the package was last updated
      required:
        - active
        - approval_required
        - automatic_order
        - id
        - it_closet
        - name
        - number_deployed
        - number_ordered
        - require_justification
        - slug
    PublicApiHttpErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiError'
          description: List of error details.
      required:
        - errors
    PackageRuleRequest:
      type: object
      description: A rule for a package
      properties:
        category_code:
          type: string
          description: Product category code this rule applies to.
          example: LAPTOP
          minLength: 1
        quantity:
          type: integer
          format: int32
          description: Number of items allowed or required for this category.
          example: 1
        optional:
          type: boolean
          description: When true, this category rule is optional for people on the package.
          example: false
      required:
        - category_code
        - optional
        - quantity
    PackageRuleResponse:
      type: object
      description: A rule within a package
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the rule
          example: 3a68a467-8733-4c8d-a942-16ed7ec33018
        category_code:
          type: string
          description: Product category code this rule applies to
          example: LAPTOP
        quantity:
          type: integer
          format: int32
          description: Number of items allowed or required for this category
          example: 1
        optional:
          type: boolean
          description: When true, this category rule is optional
          example: false
        allowed_product_ids:
          type: array
          description: >-
            Product UUIDs allowed by this rule; empty means no product
            restriction
          items:
            type: string
            format: uuid
      required:
        - category_code
        - id
        - optional
        - quantity
    PublicApiError:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable description of the error
          example: Invalid request
        source:
          type: string
          description: >-
            Entity or field path that caused the error (for example order,
            shipmentNotice, or person:email)
          example: request
      required:
        - detail
        - source
  securitySchemes:
    ApiKey:
      type: apiKey
      description: Prefix the value with "ApiKey" to indicate the custom authorization type
      name: Authorization
      in: header

````