How to Manage Asset Statuses in Snipe-IT: Complete Guide to Status Labels

Snipe-IT manages asset lifecycle states through status labels stored in the status_labels table, using three boolean flags—deployable, pending, and archived—to categorize assets as Ready-to-Deploy, Pending, Archived, or Undeployable.

Managing asset statuses in Snipe-IT is essential for tracking hardware throughout its lifecycle. The application uses status labels defined in the App\Models\Statuslabel model to represent whether an asset is available for checkout, awaiting configuration, or retired. Understanding how these labels work in the database and API enables administrators to build accurate asset reports and automate deployment workflows.

Understanding Status Label Types and Database Flags

Snipe-IT defines asset states using three boolean columns in the status_labels table: deployable, pending, and archived. These flags combine to create four distinct status types that drive business logic throughout the application:

Type	deployable	pending	archived
Ready-to-Deploy	1	0	0
Pending	0	1	0
Archived	0	0	1
Undeployable	0	0	0

When creating or updating labels via the API, you pass a textual type parameter rather than setting booleans directly. The model helper Statuslabel::getStatuslabelTypesForDB() in app/Models/Statuslabel.php (lines 215-235) converts these strings into the appropriate database flag combinations.

Core Model Features and Performance Optimization

The Statuslabel model in app/Models/Statuslabel.php implements several performance and convenience features to handle large asset inventories efficiently.

Intelligent Caching to Prevent N+1 Queries

To avoid expensive N+1 queries when checking asset statuses, the model caches ID lists for each status type using the idsFor() method. The booted() method registers a clearIdCache() callback that automatically flushes these caches whenever a status label is created, updated, or deleted. This ensures the application can quickly resolve queries like "find all deployable status IDs" without hitting the database repeatedly.

Database Relations and Query Scopes

The model defines a one-to-many relationship to assets via the assets() method (lines 26-30), allowing eager loading of assets grouped by their status. Additionally, query scopes filter collections by type:

• Deployable() – Returns labels where deployable = 1
• Pending() – Returns labels where pending = 1
• Archived() – Returns labels where archived = 1
• Undeployable() – Returns labels where all three flags are 0

These scopes are defined in app/Models/Statuslabel.php (lines 58-104) and enable clean, readable queries such as Statuslabel::Deployable()->get().

API Endpoints and Controller Logic

The StatuslabelsController in app/Http/Controllers/Api/StatuslabelsController.php exposes RESTful endpoints for status label management.

Standard CRUD Operations

The controller supports:

• GET /api/v1/statuslabels – Lists all status labels, optionally filtered by status_type (deployable, pending, archived, undeployable) using the model scopes mentioned above (lines 52-62)
• POST /api/v1/statuslabels – Creates new labels with automatic flag mapping
• PATCH /api/v1/statuslabels/{id} – Updates existing labels
• DELETE /api/v1/statuslabels/{id} – Deletes labels only when assets()->count() == 0 to prevent orphaned records

UI Integration with Select2

The selectlist method (lines 36-50) generates JSON responses formatted for Select2 dropdowns used throughout the Snipe-IT interface. This endpoint accepts optional parameters to limit results to specific types (e.g., only deployable labels during asset checkout).

Deployment Eligibility Checks

The specialized endpoint checkIfDeployable($id) (lines 12-20) returns 1 if a status label is either pending or deployable, and 0 otherwise. The frontend uses this to show or hide checkout fields dynamically based on whether an asset can actually be assigned to users.

Querying Assets by Status

The Asset model in app/Models/Asset.php leverages cached status IDs to provide high-performance filtering scopes:

• RTD() – Ready-to-Deploy assets
• Deployed() – Currently checked-out assets
• Pending() – Assets awaiting configuration
• Archived() – Retired assets
• Undeployable() – Assets that cannot be checked out

These scopes use Statuslabel::idsFor() to retrieve cached ID lists, enabling efficient counting and filtering without complex joins.

Practical Implementation: Creating and Managing Status Labels

Here are concrete examples for managing asset statuses programmatically:

Create a Ready-to-Deploy status label via the API:

$response = Http::post('/api/v1/statuslabels', [
    'name' => 'Ready-to-Deploy',
    'type' => 'deployable',   // Sets deployable=1, pending=0, archived=0
    'color' => '#28a745',
    'show_in_nav' => true,
    'default_label' => false,
]);

Retrieve deployable labels for dropdown menus:

$deployableLabels = Statuslabel::Deployable()
    ->orderBy('name')
    ->get(['id', 'name', 'color']);

Count assets currently in Pending status:

$pendingCount = Asset::Pending()->count();

Change an asset's status to Archived:

$asset = Asset::find($assetId);
$archivedStatus = Statuslabel::where('archived', 1)->first();
$asset->status_id = $archivedStatus->id;
$asset->save();

Verify if a status allows checkout before displaying UI elements:

$isDeployable = (new StatuslabelsController)->checkIfDeployable($statusId); // Returns '1' or '0'

Summary

• Status labels in Snipe-IT use three boolean flags (deployable, pending, archived) to define four distinct lifecycle states.
• The Statuslabel model in app/Models/Statuslabel.php implements automatic caching via idsFor() and clearIdCache() to optimize queries.
• Query scopes (Deployable(), Pending(), Archived(), Undeployable()) and the assets() relation simplify database interactions.
• The API controller in app/Http/Controllers/Api/StatuslabelsController.php provides full CRUD operations, Select2-compatible selectlist endpoints, and deployment eligibility checks.
• The Asset model includes corresponding scopes that leverage cached status IDs for efficient filtering and counting.

Frequently Asked Questions

What happens if I try to delete a status label that is assigned to assets?

The API controller prevents deletion of status labels that have associated assets. When you send a DELETE request to /api/v1/statuslabels/{id}, the controller checks $statuslabel->assets()->count() and returns an error if the count is greater than zero, ensuring data integrity by preventing orphaned asset records.

Can I create custom status labels beyond the four default types?

No, Snipe-IT restricts status labels to the four predefined behavioral types: deployable, pending, archived, and undeployable. However, you can create multiple labels of the same type with different names and colors. For example, you might create "New Inventory" and "Refurbished" as separate deployable labels to distinguish asset sources while maintaining checkout eligibility.

How do I programmatically check if an asset can be checked out?

Use the checkIfDeployable method in the StatuslabelsController or check the asset's status label directly. An asset is considered available for checkout when its status label has either deployable = 1 or pending = 1. The API endpoint returns 1 for eligible statuses and 0 for archived or undeployable states, which corresponds to showing or hiding checkout buttons in the user interface.

Where does Snipe-IT define the default status labels for new installations?

Default status labels are seeded via database/seeders/StatuslabelSeeder.php, which runs during the initial installation. This seeder creates standard entries like "Ready to Deploy," "Pending," and "Archived" with appropriate color codes and flag combinations, ensuring new instances have functional status workflows immediately after setup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}