# marketplace

 15 routes, from the API’s own OpenAPI document.

URL: https://docs.qaldy.com/reference/api/marketplace/

15 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/).

## Routes

| Method | Path | What it does |
|---|---|---|
| [[GET]] | [`/​v1/​apps/​{id}/​marketplace`](#get-v1-apps-id-marketplace) | Is this app listed as a template, and in which state? |
| [[GET]] | [`/​v1/​marketplace/​me`](#get-v1-marketplace-me) | Are you one of the Qaldy staff who review templates? |
| [[GET]] | [`/​v1/​marketplace/​review`](#get-v1-marketplace-review) | Templates waiting for a reviewer, and the latest decisions (staff only) |
| [[GET]] | [`/​v1/​marketplace/​review/​{id}`](#get-v1-marketplace-review-id) | A template as a reviewer reads it: permissions, Trust report and code (staff only) |
| [[POST]] | [`/​v1/​marketplace/​review/​{id}/​decision`](#post-v1-marketplace-review-id-decision) | Approve a template, ask for changes, or refuse it (staff only) |
| [[GET]] | [`/​v1/​marketplace/​templates`](#get-v1-marketplace-templates) | Published partner templates, most installed first |
| [[GET]] | [`/​v1/​marketplace/​templates/​{id}`](#get-v1-marketplace-templates-id) | One template: its words, pictures, permissions and Trust report |
| [[PATCH]] | [`/​v1/​marketplace/​templates/​{id}`](#patch-v1-marketplace-templates-id) | Edit a template you published, or send it for review again |
| [[POST]] | [`/​v1/​marketplace/​templates/​{id}/​withdraw`](#post-v1-marketplace-templates-id-withdraw) | Take a template down; apps already installed keep running |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​marketplace/​earnings`](#get-v1-workspaces-ws-marketplace-earnings) | The revenue-share ledger of this workspace’s templates (Preview: no money moves) |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​marketplace/​listings`](#get-v1-workspaces-ws-marketplace-listings) | This workspace’s templates in every status, with installs and earnings |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​marketplace/​templates`](#post-v1-workspaces-ws-marketplace-templates) | Send an app of this workspace for review as a template |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​marketplace/​templates/​{id}/​fit`](#get-v1-workspaces-ws-marketplace-templates-id-fit) | What installing a published template would mean for this workspace |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​marketplace/​templates/​{id}/​install`](#post-v1-workspaces-ws-marketplace-templates-id-install) | Install a published template as a new, private app |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​marketplace/​templates/​{id}/​rating`](#put-v1-workspaces-ws-marketplace-templates-id-rating) | Rate a template your workspace installed |

## Reference

### [[GET]] `/v1/apps/{id}/marketplace`

Is this app listed as a template, and in which state?.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** `can_edit`

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `listing` | object or null | yes |  |
| `listing.id` | string | yes | at least 1 characters |
| `listing.status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `listing.name` | string | yes | at least 1 characters |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/marketplace/me`

Are you one of the Qaldy staff who review templates?.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** signed in

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `staff` | boolean | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/marketplace/review`

Templates waiting for a reviewer, and the latest decisions (staff only).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** staff (403 `not_staff`)

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `pending` | object[] | yes | up to 200 items |
| `pending[].id` | string | yes | 1 to 64 characters |
| `pending[].slug` | string | yes |  |
| `pending[].name` | string | yes | 1 to 60 characters |
| `pending[].summary` | string | yes | 1 to 140 characters |
| `pending[].archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `pending[].category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `pending[].connectors` | object[] | yes | up to 12 items |
| `pending[].previewServices` | string[] | yes | up to 12 items |
| `pending[].priceCents` | integer | yes | 0 to 200000 |
| `pending[].currency` | "USD" | yes |  |
| `pending[].publisherName` | string | yes | 1 to 60 characters |
| `pending[].installs` | integer | yes | at least 0 |
| `pending[].rating` | object | yes |  |
| `pending[].trustScore` | integer | yes | 0 to 100 |
| `pending[].trustBand` | "pass" · "review" · "fail" | yes |  |
| `pending[].manualMinutesPerRun` | number | yes | 0 to 1440 |
| `pending[].status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `pending[].cover` | string or null | yes | 1 to 400000 characters |
| `pending[].screenshotCount` | integer | yes | 0 to 3 |
| `pending[].publishedAt` | string (date-time) or null | yes |  |
| `pending[].updatedAt` | string (date-time) | yes |  |
| `pending[].workspaceName` | string | yes | at least 1 characters |
| `pending[].submitterName` | string | yes | at least 1 characters |
| `pending[].submitterEmail` | string | yes | 3 to 254 characters |
| `pending[].submittedAt` | string (date-time) | yes |  |
| `pending[].decision` | object or null | yes |  |
| `decided` | object[] | yes | up to 50 items |
| `decided[].id` | string | yes | 1 to 64 characters |
| `decided[].slug` | string | yes |  |

…and 24 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/marketplace/review/{id}`

A template as a reviewer reads it: permissions, Trust report and code (staff only).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** staff

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | 1 to 64 characters |
| `slug` | string | yes |  |
| `name` | string | yes | 1 to 60 characters |
| `summary` | string | yes | 1 to 140 characters |
| `archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `connectors` | object[] | yes | up to 12 items |
| `connectors[].key` | string | yes | 1 to 32 characters |
| `connectors[].name` | string | yes | 1 to 60 characters |
| `connectors[].status` | "available" · "beta" · "preview" · "needs-oauth-app" · "planned" | yes |  |
| `previewServices` | string[] | yes | up to 12 items |
| `priceCents` | integer | yes | 0 to 200000 |
| `currency` | "USD" | yes |  |
| `publisherName` | string | yes | 1 to 60 characters |
| `installs` | integer | yes | at least 0 |
| `rating` | object | yes |  |
| `rating.average` | number or null | yes | 1 to 5 |
| `rating.count` | integer | yes | at least 0 |
| `trustScore` | integer | yes | 0 to 100 |
| `trustBand` | "pass" · "review" · "fail" | yes |  |
| `manualMinutesPerRun` | number | yes | 0 to 1440 |
| `status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `cover` | string or null | yes | 1 to 400000 characters |
| `screenshotCount` | integer | yes | 0 to 3 |
| `publishedAt` | string (date-time) or null | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `description` | string | yes | up to 2000 characters |
| `manifest` | object | yes |  |
| `manifest.name` | string | yes | 2 to 60 characters |
| `manifest.description` | string | yes | 4 to 280 characters |

…and 19 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/marketplace/review/{id}/decision`

Approve a template, ask for changes, or refuse it (staff only).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** staff who does not belong to the publishing workspace

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `decision` | "approve" · "request_changes" · "reject" | yes |  |
| `note` | string |  | up to 600 characters. default "" |
| `seenUpdatedAt` | string (date-time) | yes |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | 1 to 64 characters |
| `slug` | string | yes |  |
| `name` | string | yes | 1 to 60 characters |
| `summary` | string | yes | 1 to 140 characters |
| `archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `connectors` | object[] | yes | up to 12 items |
| `connectors[].key` | string | yes | 1 to 32 characters |
| `connectors[].name` | string | yes | 1 to 60 characters |
| `connectors[].status` | "available" · "beta" · "preview" · "needs-oauth-app" · "planned" | yes |  |
| `previewServices` | string[] | yes | up to 12 items |
| `priceCents` | integer | yes | 0 to 200000 |
| `currency` | "USD" | yes |  |
| `publisherName` | string | yes | 1 to 60 characters |
| `installs` | integer | yes | at least 0 |
| `rating` | object | yes |  |
| `rating.average` | number or null | yes | 1 to 5 |
| `rating.count` | integer | yes | at least 0 |
| `trustScore` | integer | yes | 0 to 100 |
| `trustBand` | "pass" · "review" · "fail" | yes |  |
| `manualMinutesPerRun` | number | yes | 0 to 1440 |
| `status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `cover` | string or null | yes | 1 to 400000 characters |
| `screenshotCount` | integer | yes | 0 to 3 |
| `publishedAt` | string (date-time) or null | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `workspaceName` | string | yes | at least 1 characters |
| `submitterName` | string | yes | at least 1 characters |
| `submitterEmail` | string | yes | 3 to 254 characters |
| `submittedAt` | string (date-time) | yes |  |

…and 1 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/marketplace/templates`

Published partner templates, most installed first.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** signed in

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `items` | object[] | yes | up to 200 items |
| `items[].id` | string | yes | 1 to 64 characters |
| `items[].slug` | string | yes |  |
| `items[].name` | string | yes | 1 to 60 characters |
| `items[].summary` | string | yes | 1 to 140 characters |
| `items[].archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `items[].category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `items[].connectors` | object[] | yes | up to 12 items |
| `items[].previewServices` | string[] | yes | up to 12 items |
| `items[].priceCents` | integer | yes | 0 to 200000 |
| `items[].currency` | "USD" | yes |  |
| `items[].publisherName` | string | yes | 1 to 60 characters |
| `items[].installs` | integer | yes | at least 0 |
| `items[].rating` | object | yes |  |
| `items[].trustScore` | integer | yes | 0 to 100 |
| `items[].trustBand` | "pass" · "review" · "fail" | yes |  |
| `items[].manualMinutesPerRun` | number | yes | 0 to 1440 |
| `items[].status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `items[].cover` | string or null | yes | 1 to 400000 characters |
| `items[].screenshotCount` | integer | yes | 0 to 3 |
| `items[].publishedAt` | string (date-time) or null | yes |  |
| `items[].updatedAt` | string (date-time) | yes |  |
| `terms` | object | yes |  |
| `terms.currency` | "USD" | yes |  |
| `terms.publisherShareBps` | integer | yes | 0 to 10000 |
| `terms.proposal` | boolean | yes |  |
| `terms.billing` | "mock" | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/marketplace/templates/{id}`

One template: its words, pictures, permissions and Trust report.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** signed in; the reviewer's note only for the publisher's people and staff

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | 1 to 64 characters |
| `slug` | string | yes |  |
| `name` | string | yes | 1 to 60 characters |
| `summary` | string | yes | 1 to 140 characters |
| `archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `connectors` | object[] | yes | up to 12 items |
| `connectors[].key` | string | yes | 1 to 32 characters |
| `connectors[].name` | string | yes | 1 to 60 characters |
| `connectors[].status` | "available" · "beta" · "preview" · "needs-oauth-app" · "planned" | yes |  |
| `previewServices` | string[] | yes | up to 12 items |
| `priceCents` | integer | yes | 0 to 200000 |
| `currency` | "USD" | yes |  |
| `publisherName` | string | yes | 1 to 60 characters |
| `installs` | integer | yes | at least 0 |
| `rating` | object | yes |  |
| `rating.average` | number or null | yes | 1 to 5 |
| `rating.count` | integer | yes | at least 0 |
| `trustScore` | integer | yes | 0 to 100 |
| `trustBand` | "pass" · "review" · "fail" | yes |  |
| `manualMinutesPerRun` | number | yes | 0 to 1440 |
| `status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `cover` | string or null | yes | 1 to 400000 characters |
| `screenshotCount` | integer | yes | 0 to 3 |
| `publishedAt` | string (date-time) or null | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `description` | string | yes | up to 2000 characters |
| `manifest` | object | yes |  |
| `manifest.name` | string | yes | 2 to 60 characters |
| `manifest.description` | string | yes | 4 to 280 characters |

…and 12 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PATCH]] `/v1/marketplace/templates/{id}`

Edit a template you published, or send it for review again.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin of the publishing workspace

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string |  | 3 to 60 characters |
| `summary` | string |  | 10 to 140 characters |
| `description` | string |  | up to 2000 characters |
| `publisherName` | string |  | 2 to 60 characters |
| `priceCents` | integer |  |  |
| `screenshots` | string[] |  | up to 3 items |
| `refreshFromApp` | boolean |  |  |
| `resubmit` | boolean |  |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | 1 to 64 characters |
| `slug` | string | yes |  |
| `name` | string | yes | 1 to 60 characters |
| `summary` | string | yes | 1 to 140 characters |
| `archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `connectors` | object[] | yes | up to 12 items |
| `connectors[].key` | string | yes | 1 to 32 characters |
| `connectors[].name` | string | yes | 1 to 60 characters |
| `connectors[].status` | "available" · "beta" · "preview" · "needs-oauth-app" · "planned" | yes |  |
| `previewServices` | string[] | yes | up to 12 items |
| `priceCents` | integer | yes | 0 to 200000 |
| `currency` | "USD" | yes |  |
| `publisherName` | string | yes | 1 to 60 characters |
| `installs` | integer | yes | at least 0 |
| `rating` | object | yes |  |
| `rating.average` | number or null | yes | 1 to 5 |
| `rating.count` | integer | yes | at least 0 |
| `trustScore` | integer | yes | 0 to 100 |
| `trustBand` | "pass" · "review" · "fail" | yes |  |
| `manualMinutesPerRun` | number | yes | 0 to 1440 |
| `status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `cover` | string or null | yes | 1 to 400000 characters |
| `screenshotCount` | integer | yes | 0 to 3 |
| `publishedAt` | string (date-time) or null | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `appId` | string or null | yes | at least 1 characters |
| `appName` | string or null | yes | at least 1 characters |
| `decision` | object or null | yes |  |
| `decision.decision` | "approve" · "request_changes" · "reject" | yes |  |

…and 5 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/marketplace/templates/{id}/withdraw`

Take a template down; apps already installed keep running.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin of the publishing workspace

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | 1 to 64 characters |
| `slug` | string | yes |  |
| `name` | string | yes | 1 to 60 characters |
| `summary` | string | yes | 1 to 140 characters |
| `archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `connectors` | object[] | yes | up to 12 items |
| `connectors[].key` | string | yes | 1 to 32 characters |
| `connectors[].name` | string | yes | 1 to 60 characters |
| `connectors[].status` | "available" · "beta" · "preview" · "needs-oauth-app" · "planned" | yes |  |
| `previewServices` | string[] | yes | up to 12 items |
| `priceCents` | integer | yes | 0 to 200000 |
| `currency` | "USD" | yes |  |
| `publisherName` | string | yes | 1 to 60 characters |
| `installs` | integer | yes | at least 0 |
| `rating` | object | yes |  |
| `rating.average` | number or null | yes | 1 to 5 |
| `rating.count` | integer | yes | at least 0 |
| `trustScore` | integer | yes | 0 to 100 |
| `trustBand` | "pass" · "review" · "fail" | yes |  |
| `manualMinutesPerRun` | number | yes | 0 to 1440 |
| `status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `cover` | string or null | yes | 1 to 400000 characters |
| `screenshotCount` | integer | yes | 0 to 3 |
| `publishedAt` | string (date-time) or null | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `appId` | string or null | yes | at least 1 characters |
| `appName` | string or null | yes | at least 1 characters |
| `decision` | object or null | yes |  |
| `decision.decision` | "approve" · "request_changes" · "reject" | yes |  |

…and 5 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/marketplace/earnings`

The revenue-share ledger of this workspace’s templates (Preview: no money moves).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `terms` | object | yes |  |
| `terms.currency` | "USD" | yes |  |
| `terms.publisherShareBps` | integer | yes | 0 to 10000 |
| `terms.proposal` | boolean | yes |  |
| `terms.billing` | "mock" | yes |  |
| `totals` | object | yes |  |
| `totals.installs` | integer | yes | at least 0 |
| `totals.paidInstalls` | integer | yes | at least 0 |
| `totals.grossCents` | integer | yes | at least 0 |
| `totals.publisherCents` | integer | yes | at least 0 |
| `totals.qaldyCents` | integer | yes | at least 0 |
| `byTemplate` | object[] | yes | up to 20 items |
| `byTemplate[].templateId` | string | yes | at least 1 characters |
| `byTemplate[].name` | string | yes | at least 1 characters |
| `byTemplate[].installs` | integer | yes | at least 0 |
| `byTemplate[].paidInstalls` | integer | yes | at least 0 |
| `byTemplate[].grossCents` | integer | yes | at least 0 |
| `byTemplate[].publisherCents` | integer | yes | at least 0 |
| `months` | object[] | yes | up to 36 items |
| `months[].month` | string | yes |  |
| `months[].paidInstalls` | integer | yes | at least 0 |
| `months[].grossCents` | integer | yes | at least 0 |
| `months[].publisherCents` | integer | yes | at least 0 |
| `entries` | object[] | yes | up to 100 items |
| `entries[].id` | string | yes | at least 1 characters |
| `entries[].at` | string (date-time) | yes |  |
| `entries[].templateId` | string | yes | at least 1 characters |
| `entries[].templateName` | string | yes | at least 1 characters |
| `entries[].grossCents` | integer | yes | at least 0 |
| `entries[].publisherCents` | integer | yes | at least 0 |

…and 3 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/marketplace/listings`

This workspace’s templates in every status, with installs and earnings.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** admin

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `items` | object[] | yes | up to 20 items |
| `items[].id` | string | yes | 1 to 64 characters |
| `items[].slug` | string | yes |  |
| `items[].name` | string | yes | 1 to 60 characters |
| `items[].summary` | string | yes | 1 to 140 characters |
| `items[].archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `items[].category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `items[].connectors` | object[] | yes | up to 12 items |
| `items[].previewServices` | string[] | yes | up to 12 items |
| `items[].priceCents` | integer | yes | 0 to 200000 |
| `items[].currency` | "USD" | yes |  |
| `items[].publisherName` | string | yes | 1 to 60 characters |
| `items[].installs` | integer | yes | at least 0 |
| `items[].rating` | object | yes |  |
| `items[].trustScore` | integer | yes | 0 to 100 |
| `items[].trustBand` | "pass" · "review" · "fail" | yes |  |
| `items[].manualMinutesPerRun` | number | yes | 0 to 1440 |
| `items[].status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `items[].cover` | string or null | yes | 1 to 400000 characters |
| `items[].screenshotCount` | integer | yes | 0 to 3 |
| `items[].publishedAt` | string (date-time) or null | yes |  |
| `items[].updatedAt` | string (date-time) | yes |  |
| `items[].appId` | string or null | yes | at least 1 characters |
| `items[].appName` | string or null | yes | at least 1 characters |
| `items[].decision` | object or null | yes |  |
| `items[].submittedAt` | string (date-time) | yes |  |
| `items[].paidInstalls` | integer | yes | at least 0 |
| `items[].earnedCents` | integer | yes | at least 0 |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/marketplace/templates`

Send an app of this workspace for review as a template.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** workspace admin, and `can_edit` on the app

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `appId` | string | yes | 1 to 128 characters |
| `name` | string | yes | 3 to 60 characters |
| `summary` | string | yes | 10 to 140 characters |
| `description` | string |  | up to 2000 characters. default "" |
| `publisherName` | string | yes | 2 to 60 characters |
| `priceCents` | integer | yes |  |
| `screenshots` | string[] |  | up to 3 items. default |
| `acceptTerms` | true | yes |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | 1 to 64 characters |
| `slug` | string | yes |  |
| `name` | string | yes | 1 to 60 characters |
| `summary` | string | yes | 1 to 140 characters |
| `archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `connectors` | object[] | yes | up to 12 items |
| `connectors[].key` | string | yes | 1 to 32 characters |
| `connectors[].name` | string | yes | 1 to 60 characters |
| `connectors[].status` | "available" · "beta" · "preview" · "needs-oauth-app" · "planned" | yes |  |
| `previewServices` | string[] | yes | up to 12 items |
| `priceCents` | integer | yes | 0 to 200000 |
| `currency` | "USD" | yes |  |
| `publisherName` | string | yes | 1 to 60 characters |
| `installs` | integer | yes | at least 0 |
| `rating` | object | yes |  |
| `rating.average` | number or null | yes | 1 to 5 |
| `rating.count` | integer | yes | at least 0 |
| `trustScore` | integer | yes | 0 to 100 |
| `trustBand` | "pass" · "review" · "fail" | yes |  |
| `manualMinutesPerRun` | number | yes | 0 to 1440 |
| `status` | "pending" · "published" · "changes_requested" · "rejected" · "withdrawn" | yes |  |
| `cover` | string or null | yes | 1 to 400000 characters |
| `screenshotCount` | integer | yes | 0 to 3 |
| `publishedAt` | string (date-time) or null | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `appId` | string or null | yes | at least 1 characters |
| `appName` | string or null | yes | at least 1 characters |
| `decision` | object or null | yes |  |
| `decision.decision` | "approve" · "request_changes" · "reject" | yes |  |

…and 5 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/marketplace/templates/{id}/fit`

What installing a published template would mean for this workspace.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member; a published template only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `id` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `canInstall` | boolean | yes |  |
| `blocker` | "not_builder" · "needs_admin" · "policy" · "connections_missing" · "not_published" · null or null | yes |  |
| `connectors` | object[] | yes | up to 12 items |
| `connectors[].key` | string | yes | 1 to 32 characters |
| `connectors[].name` | string | yes | 1 to 60 characters |
| `connectors[].status` | "available" · "beta" · "preview" · "needs-oauth-app" · "planned" | yes |  |
| `connectors[].state` | "ready" · "missing" · "blocked" | yes |  |
| `installed` | object or null | yes |  |
| `installed.appId` | string | yes | at least 1 characters |
| `installed.name` | string | yes | at least 1 characters |
| `chargeCents` | integer | yes | at least 0 |
| `needsAdmin` | boolean | yes |  |
| `yourRating` | integer or null | yes | 1 to 5 |
| `mayRate` | boolean | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/workspaces/{ws}/marketplace/templates/{id}/install`

Install a published template as a new, private app.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** builder or above; a member cannot approve a template that spends a connection or calls AI

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `id` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `confirmPriceCents` | integer | yes | at least 0 |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `appId` | string | yes | at least 1 characters |
| `chargedCents` | integer | yes | at least 0 |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[PUT]] `/v1/workspaces/{ws}/marketplace/templates/{id}/rating`

Rate a template your workspace installed.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** member of a workspace that installed it

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `id` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `stars` | integer | yes | 1 to 5 |
| `comment` | string |  | up to 500 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `rating` | object | yes |  |
| `rating.average` | number or null | yes | 1 to 5 |
| `rating.count` | integer | yes | at least 0 |
| `yours` | integer | yes | 1 to 5 |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).