---
title: Package Api
description: Package Api protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

# Package API Protocol

REST API endpoint schemas for package lifecycle management.

Base path: /api/v1/packages

@example Endpoints

POST   /api/v1/packages/install              — Install a package

POST   /api/v1/packages/upgrade              — Upgrade a package

POST   /api/v1/packages/resolve-dependencies — Resolve dependencies

POST   /api/v1/packages/upload               — Upload an artifact

GET    /api/v1/packages                      — List installed packages

GET    /api/v1/packages/:packageId           — Get package details

POST   /api/v1/packages/:packageId/rollback  — Rollback a package

DELETE /api/v1/packages/:packageId           — Uninstall a package

<Callout type="info">
**Source:** `packages/spec/src/api/package-api.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { GetInstalledPackageRequest, ListInstalledPackagesRequest, PackageApiErrorCode, PackagePathParams, PackageRollbackRequest, PackageRollbackResponse, PackageUpgradeResponse, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api';
import type { GetInstalledPackageRequest, ListInstalledPackagesRequest, PackageApiErrorCode, PackagePathParams, PackageRollbackRequest, PackageRollbackResponse, PackageUpgradeResponse, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api';

// Validate data
const result = GetInstalledPackageRequest.parse(data);
```

---

## GetInstalledPackageRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **packageId** | `string` | ✅ | Package identifier |


---

## ListInstalledPackagesRequest

List installed packages request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **status** | `Enum<'installed' \| 'disabled' \| 'installing' \| 'upgrading' \| 'uninstalling' \| 'error'>` | optional | Filter by package status |
| **enabled** | `boolean` | optional | Filter by enabled state |
| **limit** | `integer` | ✅ | Maximum number of packages to return |
| **cursor** | `string` | optional | Cursor for pagination |


---

## PackageApiErrorCode

### Allowed Values

* `package_not_found`
* `package_already_installed`
* `version_not_found`
* `dependency_conflict`
* `namespace_conflict`
* `platform_incompatible`
* `artifact_invalid`
* `checksum_mismatch`
* `signature_invalid`
* `upgrade_failed`
* `rollback_failed`
* `snapshot_not_found`
* `upload_failed`


---

## PackagePathParams

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **packageId** | `string` | ✅ | Package identifier |


---

## PackageRollbackRequest

Rollback package request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **packageId** | `string` | ✅ | Package identifier |
| **snapshotId** | `string` | ✅ | Snapshot ID to restore from |
| **rollbackCustomizations** | `boolean` | ✅ | Whether to restore pre-upgrade customizations |


---

## PackageRollbackResponse

Rollback package response

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ |  |


---

## PackageUpgradeResponse

Upgrade package response

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ |  |


---

## ResolveDependenciesResponse

Resolve dependencies response

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ | Dependency resolution result with topological sort |


---

## UninstallPackageApiRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **packageId** | `string` | ✅ | Package identifier |


---

## UninstallPackageApiResponse

Uninstall package response

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ |  |


---

## UploadArtifactRequest

Upload artifact request

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **artifact** | `Object` | ✅ | Package artifact metadata |
| **sha256** | `string` | optional | SHA256 checksum of the uploaded file |
| **token** | `string` | optional | Publisher authentication token |
| **releaseNotes** | `string` | optional | Release notes for this version |


---

## UploadArtifactResponse

Upload artifact response

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object` | ✅ |  |


---

