# Create component

Add a new component to the organization.

Source: https://statusdashboard.com/docs/api/status-dashboards/components/create

`POST /app/components`

Creates a new component. Requires the **admin** role.

If the organization has reached its component quota (`enabledFeatures.components`), this endpoint returns `403`.

***

## Request
See [API Basics](/docs/api) for required headers.

### Request body
| Field         | Type   | Required | Description                                                                                                       |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | Display name for the component. Maximum 50 characters. Must be unique within the organization (case-insensitive). |
| `description` | string | No       | Short description of the component. Maximum 150 characters.                                                       |

***

## Sample request
```bash
curl -X POST https://api.statusdashboard.com/app/components \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Gateway",
    "description": "Stripe payment processing"
  }'
```

## Sample response
**Status: `201 Created`**

```json
{
  "component": {
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "name": "Payment Gateway",
    "description": "Stripe payment processing",
    "currentStatus": "Operational",
    "currentStatusSnapshot": {
      "label": "Operational",
      "color": "#10b981",
      "icon": "check-circle"
    },
    "statusUpdatedAt": "2026-04-24T15:00:00.000Z",
    "createdAt": "2026-04-24T15:00:00.000Z"
  }
}
```

New components always start with a status of **Operational**.

***

## Error responses
| Status | When                                                                                                        |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| `400`  | Validation failure — `name` is missing, too long, malformed JSON, or the request body is not a JSON object. |
| `403`  | Insufficient permissions or the component quota is reached.                                                 |
| `409`  | A component with the same name already exists in the organization.                                          |