# Packages

Source: https://ceyo.ai/docs/signal/packages

### Packages

Read and update your workspace and manage immutable project and location packages.

### List packages

`GET /packages`

Returns workspace packages in a fixed ascending order by package type, name, then ID.

#### Query parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `q` | string | Optional | Search package names and descriptions. |
| `package_type` | project \| location | Optional | Return packages of one resource type. |
| `status` | active \| inactive \| archived | Optional | Return packages in one lifecycle status. When omitted, packages in all statuses are returned. |
| `page` | integer | Optional; Default: 1 | The 1-based page number. |
| `per_page` | integer | Optional; Default: 25 | Number of packages per page. Maximum: 100. |

#### Response envelope

`packages`:**Package\[\]**`pagination`:**Pagination**

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `packages` | Package\[\] |  | Packages matching the selected filters. |
| `pagination` | Pagination |  | Pagination metadata. |

#### Package

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Package identifier. |
| `name` | string |  | Package display name. |
| `description` | string \| null |  | Package description. |
| `package_type` | project \| location |  | Resource type that can use this package. |
| `status` | active \| inactive \| archived |  | Current package lifecycle status. Only active packages can be attached to resources or archived. |
| `configuration` | PackageConfiguration |  | Normalized feature and capacity configuration. |
| `created_at` | datetime |  | Package creation time. |
| `updated_at` | datetime |  | Most recent package update time. |

#### PackageConfiguration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility` | object |  | Cadence, prompt limit, selected models, model tiers, citations, and sentiment. |
| `diagnosis` | object |  | Diagnosis feature settings. |
| `agents` | object |  | Content and technical agent settings. |
| `advanced` | object |  | Prompt volume, Google Analytics, and fan-out settings. |
| `pricing` | object |  | Customer access setting. |

#### Visibility configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `cadence` | monthly \| weekly \| daily |  | Tracking schedule. |
| `prompt_limit` | integer |  | Maximum tracked prompts. |
| `model_keys` | string\[\] |  | Selected model keys. |

#### Feature configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `diagnosis.enabled` | boolean |  | Whether Diagnosis, Actions, and Site Audit are enabled. |
| `agents.content_enabled` | boolean |  | Whether the content agent is enabled. |
| `agents.technical_enabled` | boolean |  | Whether the technical agent is enabled. |
| `advanced.prompt_volume_enabled` | boolean |  | Whether prompt-volume analysis is enabled. |
| `advanced.google_analytics_enabled` | boolean |  | Whether Google Analytics integration is enabled. |
| `advanced.fanout_enabled` | boolean |  | Whether fan-out query analysis is enabled. |
| `pricing.frontend_delivery_enabled` | boolean |  | Whether Customer access to hosted Signal UI and redirect login links is enabled. |

#### Pagination

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `page` | integer |  | Current 1-based page. |
| `per_page` | integer |  | Number of records requested per page. |
| `total` | integer |  | Total matching packages. |
| `total_pages` | integer |  | Total available pages. |

#### Request and response

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/packages?q=growth&package_type=project&status=active&page=1&per_page=25' \
  --header 'Authorization: Bearer ceyo_platform_...'
```

```json
{
  "packages": [
    {
    "id": "92404fd7-f096-49e9-9ab0-5ed73517d9db",
    "name": "Growth Weekly",
    "description": "Weekly visibility and diagnosis for growing brands.",
    "package_type": "project",
    "status": "active",
    "configuration": {
      "visibility": {
        "cadence": "weekly",
        "prompt_limit": 100,
        "model_keys": ["chatgpt", "claude", "perplexity", "gemini"]
      },
      "diagnosis": { "enabled": true },
      "agents": {
        "content_enabled": true,
        "technical_enabled": true
      },
      "advanced": {
        "prompt_volume_enabled": true,
        "google_analytics_enabled": false,
        "fanout_enabled": true
      },
      "pricing": {
        "frontend_delivery_enabled": true
      }
    },
    "created_at": "2026-07-30T15:05:00Z",
    "updated_at": "2026-07-30T15:05:00Z"
  }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | The JSON body or a query parameter is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key was not provided or is invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Validate package configuration

`POST /packages/preview`

Validates and normalizes a proposed package configuration without creating a package.

#### Request body

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `package_type` | project \| location |  | Required resource type. |
| `configuration` | PackageConfigurationInput |  | Required proposed configuration. |

#### PackageConfigurationInput

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility` | object |  | Required visibility tracking configuration. |
| `visibility.cadence` | monthly \| weekly \| daily |  | Tracking schedule. |
| `visibility.prompt_limit` | integer |  | Maximum tracked prompts. Minimum: 20. |
| `visibility.model_keys` | string\[\] |  | Non-empty list containing chatgpt, claude, perplexity, gemini, google\_ai\_mode, google\_ai\_overview, grok, or copilot. |
| `diagnosis.enabled` | boolean |  | Enable Diagnosis, Actions, and Site Audit. Defaults to false. |
| `agents.content_enabled` | boolean |  | Enable the content agent. Defaults to false and is normalized to false unless diagnosis.enabled is true. |
| `agents.technical_enabled` | boolean |  | Enable the technical agent. Defaults to false and is normalized to false unless diagnosis.enabled is true. |
| `listings.enabled` | derived |  | Derived from package\_type: true for location packages and false for project packages. Do not send this field. |
| `advanced.prompt_volume_enabled` | boolean |  | Enable prompt-volume analysis. Defaults to false. |
| `advanced.google_analytics_enabled` | boolean |  | Enable Google Analytics integration. Defaults to false. |
| `advanced.fanout_enabled` | boolean |  | Enable fan-out query analysis. Defaults to false. |
| `pricing.frontend_delivery_enabled` | boolean |  | Enable Customer access, including hosted Signal UI and redirect login links, and apply one 25% uplift. Defaults to false. |

#### Response envelope

`configuration`:**PackageConfiguration**

Normalized public configuration.

#### PackageConfiguration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility` | object |  | Cadence, prompt limit, selected models, model tiers, citations, and sentiment. |
| `diagnosis` | object |  | Diagnosis feature settings. |
| `agents` | object |  | Content and technical agent settings. |
| `advanced` | object |  | Prompt volume, Google Analytics, and fan-out settings. |
| `pricing` | object |  | Customer access setting. |

#### Visibility configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `cadence` | monthly \| weekly \| daily |  | Tracking schedule. |
| `prompt_limit` | integer |  | Maximum tracked prompts. |
| `model_keys` | string\[\] |  | Selected model keys. |

#### Feature configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `diagnosis.enabled` | boolean |  | Whether Diagnosis, Actions, and Site Audit are enabled. |
| `agents.content_enabled` | boolean |  | Whether the content agent is enabled. |
| `agents.technical_enabled` | boolean |  | Whether the technical agent is enabled. |
| `advanced.prompt_volume_enabled` | boolean |  | Whether prompt-volume analysis is enabled. |
| `advanced.google_analytics_enabled` | boolean |  | Whether Google Analytics integration is enabled. |
| `advanced.fanout_enabled` | boolean |  | Whether fan-out query analysis is enabled. |
| `pricing.frontend_delivery_enabled` | boolean |  | Whether Customer access to hosted Signal UI and redirect login links is enabled. |

#### Request and response

```curl
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/packages/preview' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "package_type": "project",
  "configuration": {
    "visibility": {
      "cadence": "weekly",
      "prompt_limit": 100,
      "model_keys": ["chatgpt", "claude", "perplexity", "gemini"]
    },
    "diagnosis": { "enabled": true },
    "agents": {
      "content_enabled": true,
      "technical_enabled": true
    },
    "advanced": {
      "prompt_volume_enabled": true,
      "google_analytics_enabled": false,
      "fanout_enabled": true
    },
    "pricing": {
      "frontend_delivery_enabled": true
    }
  }
}'
```

```json
{
  "configuration": {
      "visibility": {
        "cadence": "weekly",
        "prompt_limit": 100,
        "model_keys": ["chatgpt", "claude", "perplexity", "gemini"]
      },
      "diagnosis": { "enabled": true },
      "agents": {
        "content_enabled": true,
        "technical_enabled": true
      },
      "advanced": {
        "prompt_volume_enabled": true,
        "google_analytics_enabled": false,
        "fanout_enabled": true
      },
      "pricing": {
        "frontend_delivery_enabled": true
      }
    }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | The JSON body or a query parameter is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key was not provided or is invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `422` | validation\_failed |  | One or more request fields are invalid. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Create package

`POST /packages`

Creates an immutable package and returns its public configuration.

#### Request body

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `name` | string |  | Required package name. Maximum: 200 characters. |
| `description` | string \| null |  | Optional description. Maximum: 5,000 characters. |
| `package_type` | project \| location |  | Required resource type. |
| `configuration` | PackageConfigurationInput |  | Required feature and capacity configuration. |

#### PackageConfigurationInput

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility` | object |  | Required visibility tracking configuration. |
| `visibility.cadence` | monthly \| weekly \| daily |  | Tracking schedule. |
| `visibility.prompt_limit` | integer |  | Maximum tracked prompts. Minimum: 20. |
| `visibility.model_keys` | string\[\] |  | Non-empty list containing chatgpt, claude, perplexity, gemini, google\_ai\_mode, google\_ai\_overview, grok, or copilot. |
| `diagnosis.enabled` | boolean |  | Enable Diagnosis, Actions, and Site Audit. Defaults to false. |
| `agents.content_enabled` | boolean |  | Enable the content agent. Defaults to false and is normalized to false unless diagnosis.enabled is true. |
| `agents.technical_enabled` | boolean |  | Enable the technical agent. Defaults to false and is normalized to false unless diagnosis.enabled is true. |
| `listings.enabled` | derived |  | Derived from package\_type: true for location packages and false for project packages. Do not send this field. |
| `advanced.prompt_volume_enabled` | boolean |  | Enable prompt-volume analysis. Defaults to false. |
| `advanced.google_analytics_enabled` | boolean |  | Enable Google Analytics integration. Defaults to false. |
| `advanced.fanout_enabled` | boolean |  | Enable fan-out query analysis. Defaults to false. |
| `pricing.frontend_delivery_enabled` | boolean |  | Enable Customer access, including hosted Signal UI and redirect login links, and apply one 25% uplift. Defaults to false. |

> **Location package example**
>
> Sending `package_type: "location"` derives `configuration.listings.enabled: true`. Listings is derived and must not be included in the request configuration.

#### Response envelope

`package`:**Package**

The requested or resulting package.

#### Package

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Package identifier. |
| `name` | string |  | Package display name. |
| `description` | string \| null |  | Package description. |
| `package_type` | project \| location |  | Resource type that can use this package. |
| `status` | active \| inactive \| archived |  | Current package lifecycle status. Only active packages can be attached to resources or archived. |
| `configuration` | PackageConfiguration |  | Normalized feature and capacity configuration. |
| `created_at` | datetime |  | Package creation time. |
| `updated_at` | datetime |  | Most recent package update time. |

#### PackageConfiguration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility` | object |  | Cadence, prompt limit, selected models, model tiers, citations, and sentiment. |
| `diagnosis` | object |  | Diagnosis feature settings. |
| `agents` | object |  | Content and technical agent settings. |
| `advanced` | object |  | Prompt volume, Google Analytics, and fan-out settings. |
| `pricing` | object |  | Customer access setting. |

#### Visibility configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `cadence` | monthly \| weekly \| daily |  | Tracking schedule. |
| `prompt_limit` | integer |  | Maximum tracked prompts. |
| `model_keys` | string\[\] |  | Selected model keys. |

#### Feature configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `diagnosis.enabled` | boolean |  | Whether Diagnosis, Actions, and Site Audit are enabled. |
| `agents.content_enabled` | boolean |  | Whether the content agent is enabled. |
| `agents.technical_enabled` | boolean |  | Whether the technical agent is enabled. |
| `advanced.prompt_volume_enabled` | boolean |  | Whether prompt-volume analysis is enabled. |
| `advanced.google_analytics_enabled` | boolean |  | Whether Google Analytics integration is enabled. |
| `advanced.fanout_enabled` | boolean |  | Whether fan-out query analysis is enabled. |
| `pricing.frontend_delivery_enabled` | boolean |  | Whether Customer access to hosted Signal UI and redirect login links is enabled. |

> **201 Created**
>
> A successful request returns HTTP `201`. Package names must be unique within their package type.

#### Request and response

```curl
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/packages' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Growth Weekly",
  "description": "Weekly visibility and diagnosis for growing brands.",
  "package_type": "project",
  "configuration": {
    "visibility": {
      "cadence": "weekly",
      "prompt_limit": 100,
      "model_keys": ["chatgpt", "claude", "perplexity", "gemini"]
    },
    "diagnosis": { "enabled": true },
    "agents": {
      "content_enabled": true,
      "technical_enabled": true
    },
    "advanced": {
      "prompt_volume_enabled": true,
      "google_analytics_enabled": false,
      "fanout_enabled": true
    },
    "pricing": {
      "frontend_delivery_enabled": true
    }
  }
}'
```

```json
{
  "package": {
    "id": "92404fd7-f096-49e9-9ab0-5ed73517d9db",
    "name": "Growth Weekly",
    "description": "Weekly visibility and diagnosis for growing brands.",
    "package_type": "project",
    "status": "active",
    "configuration": {
      "visibility": {
        "cadence": "weekly",
        "prompt_limit": 100,
        "model_keys": ["chatgpt", "claude", "perplexity", "gemini"]
      },
      "diagnosis": { "enabled": true },
      "agents": {
        "content_enabled": true,
        "technical_enabled": true
      },
      "advanced": {
        "prompt_volume_enabled": true,
        "google_analytics_enabled": false,
        "fanout_enabled": true
      },
      "pricing": {
        "frontend_delivery_enabled": true
      }
    },
    "created_at": "2026-07-30T15:05:00Z",
    "updated_at": "2026-07-30T15:05:00Z"
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | The JSON body or a query parameter is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key was not provided or is invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `422` | validation\_failed |  | One or more request fields are invalid. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Get package

`GET /packages/{package_id}`

Returns one package from the workspace selected by the Bearer API key.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `package_id` | uuid | Required | Package identifier. |

#### Response envelope

`package`:**Package**

The requested or resulting package.

#### Package

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Package identifier. |
| `name` | string |  | Package display name. |
| `description` | string \| null |  | Package description. |
| `package_type` | project \| location |  | Resource type that can use this package. |
| `status` | active \| inactive \| archived |  | Current package lifecycle status. Only active packages can be attached to resources or archived. |
| `configuration` | PackageConfiguration |  | Normalized feature and capacity configuration. |
| `created_at` | datetime |  | Package creation time. |
| `updated_at` | datetime |  | Most recent package update time. |

#### PackageConfiguration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility` | object |  | Cadence, prompt limit, selected models, model tiers, citations, and sentiment. |
| `diagnosis` | object |  | Diagnosis feature settings. |
| `agents` | object |  | Content and technical agent settings. |
| `advanced` | object |  | Prompt volume, Google Analytics, and fan-out settings. |
| `pricing` | object |  | Customer access setting. |

#### Visibility configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `cadence` | monthly \| weekly \| daily |  | Tracking schedule. |
| `prompt_limit` | integer |  | Maximum tracked prompts. |
| `model_keys` | string\[\] |  | Selected model keys. |

#### Feature configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `diagnosis.enabled` | boolean |  | Whether Diagnosis, Actions, and Site Audit are enabled. |
| `agents.content_enabled` | boolean |  | Whether the content agent is enabled. |
| `agents.technical_enabled` | boolean |  | Whether the technical agent is enabled. |
| `advanced.prompt_volume_enabled` | boolean |  | Whether prompt-volume analysis is enabled. |
| `advanced.google_analytics_enabled` | boolean |  | Whether Google Analytics integration is enabled. |
| `advanced.fanout_enabled` | boolean |  | Whether fan-out query analysis is enabled. |
| `pricing.frontend_delivery_enabled` | boolean |  | Whether Customer access to hosted Signal UI and redirect login links is enabled. |

#### Request and response

```curl
curl --request GET \
  --url 'https://api.signal.ceyo.ai/v1/packages/92404fd7-f096-49e9-9ab0-5ed73517d9db' \
  --header 'Authorization: Bearer ceyo_platform_...'
```

```json
{
  "package": {
    "id": "92404fd7-f096-49e9-9ab0-5ed73517d9db",
    "name": "Growth Weekly",
    "description": "Weekly visibility and diagnosis for growing brands.",
    "package_type": "project",
    "status": "active",
    "configuration": {
      "visibility": {
        "cadence": "weekly",
        "prompt_limit": 100,
        "model_keys": ["chatgpt", "claude", "perplexity", "gemini"]
      },
      "diagnosis": { "enabled": true },
      "agents": {
        "content_enabled": true,
        "technical_enabled": true
      },
      "advanced": {
        "prompt_volume_enabled": true,
        "google_analytics_enabled": false,
        "fanout_enabled": true
      },
      "pricing": {
        "frontend_delivery_enabled": true
      }
    },
    "created_at": "2026-07-30T15:05:00Z",
    "updated_at": "2026-07-30T15:05:00Z"
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `401` | invalid\_api\_key |  | The Bearer API key was not provided or is invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `404` | not\_found |  | The requested package was not found in this workspace. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Clone package

`POST /packages/{package_id}/clone`

Creates a new active package by copying the source package type and configuration.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `package_id` | uuid | Required | Package identifier. |

#### Request body

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `name` | string |  | Required name for the cloned package. Maximum: 200 characters. |
| `description` | string \| null |  | Optional description. Maximum: 5,000 characters. When omitted, the source description is copied. |

> **201 Created**
>
> A successful request returns HTTP `201` with a new package ID and new creation and update timestamps. The clone copies `package_type` and `configuration`. Package type and configuration cannot be overridden in the request.

#### Response envelope

`package`:**Package**

The requested or resulting package.

#### Package

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Package identifier. |
| `name` | string |  | Package display name. |
| `description` | string \| null |  | Package description. |
| `package_type` | project \| location |  | Resource type that can use this package. |
| `status` | active \| inactive \| archived |  | Current package lifecycle status. Only active packages can be attached to resources or archived. |
| `configuration` | PackageConfiguration |  | Normalized feature and capacity configuration. |
| `created_at` | datetime |  | Package creation time. |
| `updated_at` | datetime |  | Most recent package update time. |

#### PackageConfiguration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility` | object |  | Cadence, prompt limit, selected models, model tiers, citations, and sentiment. |
| `diagnosis` | object |  | Diagnosis feature settings. |
| `agents` | object |  | Content and technical agent settings. |
| `advanced` | object |  | Prompt volume, Google Analytics, and fan-out settings. |
| `pricing` | object |  | Customer access setting. |

#### Visibility configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `cadence` | monthly \| weekly \| daily |  | Tracking schedule. |
| `prompt_limit` | integer |  | Maximum tracked prompts. |
| `model_keys` | string\[\] |  | Selected model keys. |

#### Feature configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `diagnosis.enabled` | boolean |  | Whether Diagnosis, Actions, and Site Audit are enabled. |
| `agents.content_enabled` | boolean |  | Whether the content agent is enabled. |
| `agents.technical_enabled` | boolean |  | Whether the technical agent is enabled. |
| `advanced.prompt_volume_enabled` | boolean |  | Whether prompt-volume analysis is enabled. |
| `advanced.google_analytics_enabled` | boolean |  | Whether Google Analytics integration is enabled. |
| `advanced.fanout_enabled` | boolean |  | Whether fan-out query analysis is enabled. |
| `pricing.frontend_delivery_enabled` | boolean |  | Whether Customer access to hosted Signal UI and redirect login links is enabled. |

#### Request and response

```curl
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/packages/92404fd7-f096-49e9-9ab0-5ed73517d9db/clone' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Growth Weekly Plus",
  "description": "A new package based on Growth Weekly."
}'
```

```json
{
  "package": {
    "id": "1fd73876-e220-4962-924b-a74bdb32481d",
    "name": "Growth Weekly Plus",
    "description": "A new package based on Growth Weekly.",
    "package_type": "project",
    "status": "active",
    "configuration": {
      "visibility": {
        "cadence": "weekly",
        "prompt_limit": 100,
        "model_keys": ["chatgpt", "claude", "perplexity", "gemini"]
      },
      "diagnosis": { "enabled": true },
      "agents": {
        "content_enabled": true,
        "technical_enabled": true
      },
      "advanced": {
        "prompt_volume_enabled": true,
        "google_analytics_enabled": false,
        "fanout_enabled": true
      },
      "pricing": {
        "frontend_delivery_enabled": true
      }
    },
    "created_at": "2026-07-31T10:05:00Z",
    "updated_at": "2026-07-31T10:05:00Z"
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | The JSON body or a query parameter is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key was not provided or is invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `404` | not\_found |  | The requested package was not found in this workspace. |
| `422` | validation\_failed |  | One or more request fields are invalid. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |

### Archive package

`POST /packages/{package_id}/archive`

Archives an unattached active package. The request body must be an empty JSON object.

#### Path parameters

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `package_id` | uuid | Required | Package identifier. |

#### Request body

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `{}` | object |  | Required empty JSON request body. |

> **200 OK**
>
> A successful request returns HTTP `200`. Only an unattached active package can be archived. A package that is attached, already archived, or not active returns a conflict. An archived package cannot be restored.

#### Response envelope

`package`:**Package**

The requested or resulting package.

#### Package

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `id` | uuid |  | Package identifier. |
| `name` | string |  | Package display name. |
| `description` | string \| null |  | Package description. |
| `package_type` | project \| location |  | Resource type that can use this package. |
| `status` | active \| inactive \| archived |  | Current package lifecycle status. Only active packages can be attached to resources or archived. |
| `configuration` | PackageConfiguration |  | Normalized feature and capacity configuration. |
| `created_at` | datetime |  | Package creation time. |
| `updated_at` | datetime |  | Most recent package update time. |

#### PackageConfiguration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `visibility` | object |  | Cadence, prompt limit, selected models, model tiers, citations, and sentiment. |
| `diagnosis` | object |  | Diagnosis feature settings. |
| `agents` | object |  | Content and technical agent settings. |
| `advanced` | object |  | Prompt volume, Google Analytics, and fan-out settings. |
| `pricing` | object |  | Customer access setting. |

#### Visibility configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `cadence` | monthly \| weekly \| daily |  | Tracking schedule. |
| `prompt_limit` | integer |  | Maximum tracked prompts. |
| `model_keys` | string\[\] |  | Selected model keys. |

#### Feature configuration

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `diagnosis.enabled` | boolean |  | Whether Diagnosis, Actions, and Site Audit are enabled. |
| `agents.content_enabled` | boolean |  | Whether the content agent is enabled. |
| `agents.technical_enabled` | boolean |  | Whether the technical agent is enabled. |
| `advanced.prompt_volume_enabled` | boolean |  | Whether prompt-volume analysis is enabled. |
| `advanced.google_analytics_enabled` | boolean |  | Whether Google Analytics integration is enabled. |
| `advanced.fanout_enabled` | boolean |  | Whether fan-out query analysis is enabled. |
| `pricing.frontend_delivery_enabled` | boolean |  | Whether Customer access to hosted Signal UI and redirect login links is enabled. |

#### Request and response

```curl
curl --request POST \
  --url 'https://api.signal.ceyo.ai/v1/packages/92404fd7-f096-49e9-9ab0-5ed73517d9db/archive' \
  --header 'Authorization: Bearer ceyo_platform_...' \
  --header 'Content-Type: application/json' \
  --data '{}'
```

```json
{
  "package": {
    "id": "92404fd7-f096-49e9-9ab0-5ed73517d9db",
    "name": "Growth Weekly",
    "description": "Weekly visibility and diagnosis for growing brands.",
    "package_type": "project",
    "status": "archived",
    "configuration": {
      "visibility": {
        "cadence": "weekly",
        "prompt_limit": 100,
        "model_keys": ["chatgpt", "claude", "perplexity", "gemini"]
      },
      "diagnosis": { "enabled": true },
      "agents": {
        "content_enabled": true,
        "technical_enabled": true
      },
      "advanced": {
        "prompt_volume_enabled": true,
        "google_analytics_enabled": false,
        "fanout_enabled": true
      },
      "pricing": {
        "frontend_delivery_enabled": true
      }
    },
    "created_at": "2026-07-30T15:05:00Z",
    "updated_at": "2026-07-31T10:12:00Z"
  }
}
```

#### Errors

#### Error response envelope

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `error` | Error |  | Structured error payload. |

#### Error

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `code` | string |  | Stable snake\_case code suitable for programmatic handling. |
| `message` | string |  | Human-readable explanation of the failure. |
| `details` | object \| array \| null |  | Structured validation or request context when available. |
| `request_id` | string |  | Identifier to provide when requesting support. |

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The Bearer API key is invalid.",
    "details": null,
    "request_id": "req_01K1F8M7QX4R2V9N6Y3Z0A5BCT"
  }
}
```

#### Status codes

| Name | Type | Details | Description |
| --- | --- | --- | --- |
| `400` | invalid\_request |  | The JSON body or a query parameter is malformed. |
| `401` | invalid\_api\_key |  | The Bearer API key was not provided or is invalid. |
| `403` | forbidden |  | The API key cannot perform this operation. |
| `404` | not\_found |  | The requested package was not found in this workspace. |
| `409` | package\_not\_active \| package\_in\_use |  | The package is attached to a resource, is already archived, or is not active. |
| `429` | rate\_limit\_exceeded |  | Too many requests were made. |