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

# Create a new stack

> Requires a team-scoped API key with the `write` permission, and consumes stack quota.



## OpenAPI

````yaml /openapi/api-docs.yaml post /v1/stacks
openapi: 3.0.3
info:
  title: StatusStack API
  description: >
    API for managing status monitoring, incidents, stacks, and website
    monitoring.


    You can import this specification directly into Postman, Insomnia or any
    other

    OpenAPI-compatible client.


    Only the operations documented here are part of the supported public API.
    Any other

    endpoint is unstable and may change without a version bump.
  version: 1.4.0
  contact:
    name: StatusStack Support
    url: https://statusstack.com/support
servers:
  - url: https://statusstack.com/api
    description: Production server
security: []
paths:
  /v1/stacks:
    post:
      tags:
        - Stacks
      summary: Create a new stack
      description: >-
        Requires a team-scoped API key with the `write` permission, and consumes
        stack quota.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StackCreateRequest'
      responses:
        '201':
          description: Stack created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stack'
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
        - bearerAuth: []
components:
  schemas:
    StackCreateRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - stack_type
        - visibility
      properties:
        name:
          type: string
          maxLength: 255
        slug:
          type: string
          maxLength: 255
          nullable: true
          description: >-
            Lowercase letters, numbers, dashes and underscores. Generated from
            `name` when null or omitted.
        description:
          type: string
          maxLength: 1000
          nullable: true
        stack_type:
          $ref: '#/components/schemas/StackTypeSelectable'
        visibility:
          $ref: '#/components/schemas/StackVisibility'
        password:
          allOf:
            - $ref: '#/components/schemas/StackAccessPassword'
          description: >-
            Required when `visibility` is `password`. Must not be sent for any
            other visibility.
        parent_stack_id:
          type: string
          format: uuid
          nullable: true
        custom_logo_url:
          type: string
          format: uri
          maxLength: 500
          nullable: true
        theme:
          allOf:
            - $ref: '#/components/schemas/StackTheme'
          nullable: true
        layout:
          allOf:
            - $ref: '#/components/schemas/StackLayout'
          nullable: true
        refresh_interval:
          allOf:
            - $ref: '#/components/schemas/StackRefreshInterval'
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        settings:
          allOf:
            - $ref: '#/components/schemas/StackSettings'
          nullable: true
        sources:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/StackSourceAttachment'
        components:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/StackComponentAttachment'
    Stack:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        description:
          type: string
          nullable: true
        stack_type:
          $ref: '#/components/schemas/StackType'
        visibility:
          $ref: '#/components/schemas/StackVisibility'
        public_url:
          type: string
          format: uri
          nullable: true
        theme:
          $ref: '#/components/schemas/StackTheme'
        layout:
          $ref: '#/components/schemas/StackLayout'
        custom_logo_url:
          type: string
          format: uri
          nullable: true
        refresh_interval:
          $ref: '#/components/schemas/StackRefreshInterval'
        show_timestamps:
          type: boolean
        show_component_names:
          type: boolean
        show_incident_history:
          type: boolean
        incident_history_days:
          type: integer
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        settings:
          type: object
          nullable: true
          additionalProperties: true
        view_count:
          type: integer
        subscriber_count:
          type: integer
        health_percentage:
          type: number
          format: float
          description: >-
            Only present on responses that computed it, such as
            `/v1/stacks/{stack_id}/health`.
        sources_count:
          type: integer
          description: >-
            Present on list responses and on create/update, which load counts
            rather than full relationships.
        components_count:
          type: integer
        active_subscribers_count:
          type: integer
        team_id:
          type: string
          format: uuid
        parent_stack_id:
          type: string
          format: uuid
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          type: string
          format: date-time
          nullable: true
        team:
          type: object
          additionalProperties: true
          description: >
            The owning team. Included only for a viewer who may update the
            stack, so an

            unauthorised viewer never sees it.
        parent_stack:
          $ref: '#/components/schemas/Stack'
        child_stacks:
          type: array
          items:
            $ref: '#/components/schemas/Stack'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/Source'
        components:
          type: array
          items:
            $ref: '#/components/schemas/Component'
        links:
          type: object
          properties:
            self:
              type: string
              format: uri
            public:
              type: string
              format: uri
              nullable: true
    StackTypeSelectable:
      type: string
      enum:
        - application
        - tech
        - business
        - custom
      description: The types a stack may be created as. Excludes the legacy `status_page`.
    StackVisibility:
      type: string
      enum:
        - public
        - private
        - password
        - unlisted
      description: >
        Who may view the stack's public page. `password` requires a `password`
        on the

        create/update request.
    StackAccessPassword:
      type: string
      minLength: 8
      maxLength: 255
      nullable: true
      description: Access password for a `password`-visibility stack.
    StackTheme:
      type: string
      enum:
        - auto
        - light
        - dark
      default: auto
      description: >-
        Colour scheme of the public page. `auto` follows the viewer's system
        preference.
    StackLayout:
      type: string
      enum:
        - grid
        - list
        - compact
      default: grid
      description: How components are arranged on the public page.
    StackRefreshInterval:
      type: integer
      minimum: 10
      maximum: 300
      default: 30
      description: How often the public page auto-refreshes, in seconds.
    StackSettings:
      type: object
      description: >
        Free-form stack settings. The public status page contact methods are
        validated

        keys; anything else is passed through.
      additionalProperties: true
      properties:
        contact_url:
          type: string
          format: uri
          nullable: true
          maxLength: 500
          pattern: ^https?://
        contact_email:
          type: string
          format: email
          nullable: true
          maxLength: 255
        contact_phone:
          type: string
          nullable: true
          maxLength: 30
          description: >-
            7 to 15 digits, optional leading `+`, separated by spaces, dots,
            dashes or parentheses.
          allOf:
            - pattern: ^\+?[0-9][0-9\s().\-]*[0-9]$
            - pattern: ^(?:\D*\d){7,15}\D*$
    StackSourceAttachment:
      allOf:
        - type: object
          required:
            - source_id
          properties:
            source_id:
              type: string
              format: uuid
        - $ref: '#/components/schemas/StackSourcePlacement'
    StackComponentAttachment:
      allOf:
        - type: object
          required:
            - component_id
          properties:
            component_id:
              type: string
              format: uuid
        - $ref: '#/components/schemas/StackComponentPlacement'
    StackType:
      type: string
      enum:
        - application
        - tech
        - business
        - custom
        - status_page
      description: >
        What the stack groups together, as stored. `status_page` is legacy: it
        is never

        selectable on create, and on update it is accepted only when it is
        already the

        stack's current type.
    Source:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          enum:
            - salesforce
            - microsoft365
            - custom
        url:
          type: string
          format: uri
          nullable: true
          description: >
            The source's `service_url`, which is nullable — a source registered
            by status page

            alone has no service URL.
        components:
          type: array
          items:
            $ref: '#/components/schemas/Component'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Component:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        source_id:
          type: string
          format: uuid
        latest_status:
          type: string
          enum:
            - operational
            - degraded
            - degraded_performance
            - partial_outage
            - major_outage
            - maintenance
            - unknown
          description: >
            The component's display status. `degraded_performance` is returned
            as-is; every

            other degraded state maps to `degraded`. A status that cannot be
            classified

            becomes `unknown` rather than being reported as healthy.
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    AuthError:
      type: object
      description: >
        The shape for authentication failures and missing API-key permissions.
        These

        responses use `error`, not `message`.
      required:
        - error
      properties:
        error:
          type: string
    ApiError:
      type: object
      description: >
        The standard failure envelope. `errors` appears only when there is
        field-level detail.
      required:
        - message
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties: true
    ValidationError:
      type: object
      description: The validation failure body.
      required:
        - message
        - errors
      properties:
        message:
          type: string
        errors:
          type: object
          description: Field name to the list of messages for that field.
          additionalProperties:
            type: array
            items:
              type: string
    QuotaExceededError:
      type: object
      description: >
        Quota refusals answer 422, not 402 or 429, so a quota refusal shares a
        status code

        with a validation failure while carrying a different body.
      required:
        - message
        - error
      properties:
        message:
          type: string
        error:
          type: string
          enum:
            - quota_exceeded
        resource:
          type: string
        usage:
          type: object
          additionalProperties: true
    StackSourcePlacement:
      type: object
      description: >-
        Where an attached source sits on the stack. Carried on the stack/source
        pivot.
      properties:
        sort_order:
          type: integer
          minimum: 0
        show_all_components:
          type: boolean
        settings:
          type: object
          additionalProperties: true
    StackComponentPlacement:
      type: object
      description: >-
        Where an attached component sits on the stack. Carried on the
        stack/component pivot.
      properties:
        sort_order:
          type: integer
          minimum: 0
        is_critical:
          type: boolean
        custom_label:
          type: string
          maxLength: 255
        settings:
          type: object
          additionalProperties: true
  responses:
    Unauthenticated:
      description: >
        No bearer credentials, or credentials that do not resolve to a valid API
        key. Every

        v1 operation can return it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthError'
    Forbidden:
      description: >
        The API key lacks the required permission, or access to the resource was
        denied.

        The two cases return different bodies, so this is a union rather than
        one shape.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/AuthError'
              - $ref: '#/components/schemas/ApiError'
    ValidationFailed:
      description: >
        The request body failed validation, or the write would exceed the
        organization's

        quota. Quota refusals also answer 422, with their own body.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ValidationError'
              - $ref: '#/components/schemas/QuotaExceededError'
    TooManyRequests:
      description: >
        The v1 rate limit (120 requests per minute) was exceeded. Applies to
        every

        operation in the v1 group.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the limit resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        StatusStack authenticates requests with API keys, created via the
        dashboard with

        granular permissions (read, write, delete, admin, *).


        API keys support version compatibility:

        - v1 keys: Can only access v1 endpoints

        - v2 keys: Can access both v1 and v2 endpoints


        Available permissions:

        - `read`: View resources (GET requests)

        - `write`: Create and update resources (POST, PUT requests)

        - `delete`: Delete resources (DELETE requests)

        - `admin`: Administrative access to all resources

        - `*`: Wildcard permission (all actions allowed)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.