# Create a draft item sold by the workspace

Needs workspace:selling:manage.

> **Note:**

**Not fully described yet.** The API description has no described successful answer for this operation yet. The method, path, sign-in, rate limits and request fields on this page are read from the server's code and are accurate; what a successful call returns is not written down here yet. Until it is, search engines and the agent index leave this page out.

`POST /api/v1/public/workspaces/workspaceId/items`

- Sign-in: A signed-in user's session: send the session id in the x-session-id header.
- Rate limit: Up to 500 requests every 3 seconds per IP address; up to 1,000 requests a minute per API key (some requests are not counted).

Needs `workspace:selling:manage`. The item type must be published and sold by workspaces (422 `ITEM_TYPE_NOT_SELLABLE`); invalid content answers 422 `ITEM_INVALID`, a taken slug 409 `ITEM_SLUG_TAKEN`, and a seller that can no longer sell 409 `SELLER_TERMINAL`.

## Request

| Field         | Type   | Required | Constraints | Description |
| ------------- | ------ | -------- | ----------- | ----------- |
| `workspaceId` | string | Yes      | -           | -           |

Send the body as `application/json`.

| Field                                            | Type                                | Required | Constraints                                                                                                               | Description |
| ------------------------------------------------ | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `typeKey`                                        | string                              | Yes      | at most 48 characters                                                                                                     | -           |
| `title`                                          | string                              | Yes      | at most 100 characters                                                                                                    | -           |
| `slug`                                           | string                              | Yes      | at most 100 characters                                                                                                    | -           |
| `summary`                                        | string                              | No       | at most 200 characters                                                                                                    | -           |
| `description`                                    | string                              | No       | at most 20000 characters                                                                                                  | -           |
| `media`                                          | array of string                     | No       | at most 8 items                                                                                                           | -           |
| `ctaText`                                        | string                              | No       | at most 40 characters                                                                                                     | -           |
| `variants`                                       | array of object                     | Yes      | at least 1 items, at most 250 items                                                                                       | -           |
| `variants[].id`                                  | string                              | Yes      | 1 to 64 characters                                                                                                        | -           |
| `variants[].label`                               | string                              | No       | at most 126 characters                                                                                                    | -           |
| `variants[].optionValues`                        | object                              | No       | -                                                                                                                         | -           |
| `variants[].rank`                                | integer                             | No       | at least 0, at most 1000                                                                                                  | -           |
| `variants[].prices`                              | array of object                     | Yes      | at most 40 items                                                                                                          | -           |
| `variants[].prices[].id`                         | string                              | Yes      | 1 to 64 characters                                                                                                        | -           |
| `variants[].prices[].currency`                   | string                              | Yes      | matches `^[a-z]{3}$`                                                                                                      | -           |
| `variants[].prices[].mode`                       | string                              | Yes      | one of `"fixed"`, `"free"`, `"pwyw"`                                                                                      | -           |
| `variants[].prices[].amount`                     | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `variants[].prices[].compareAtAmount`            | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `variants[].prices[].minimum`                    | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `variants[].prices[].suggested`                  | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `variants[].prices[].maximum`                    | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `variants[].prices[].recurring`                  | object                              | No       | -                                                                                                                         | -           |
| `variants[].prices[].recurring.interval`         | string                              | No       | one of `"day"`, `"week"`, `"month"`, `"year"`                                                                             | -           |
| `variants[].prices[].recurring.intervalCount`    | integer                             | No       | at least 1, at most 365                                                                                                   | -           |
| `variants[].prices[].recurring.trialDays`        | integer                             | No       | at least 0, at most 730                                                                                                   | -           |
| `variants[].prices[].recurring.endAfterPayments` | integer                             | No       | at least 1, at most 1000                                                                                                  | -           |
| `variants[].prices[].recurring.intro`            | object                              | No       | -                                                                                                                         | -           |
| `variants[].prices[].recurring.intro.amount`     | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `variants[].prices[].recurring.intro.periods`    | integer                             | No       | at least 1, at most 100                                                                                                   | -           |
| `variants[].prices[].deposit`                    | object                              | No       | -                                                                                                                         | -           |
| `variants[].prices[].deposit.percentBps`         | integer                             | No       | at least 0, at most 10000                                                                                                 | -           |
| `variants[].prices[].milestones`                 | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `variants[].prices[].milestones[].label`         | string                              | No       | at most 60 characters                                                                                                     | -           |
| `variants[].prices[].milestones[].percentBps`    | integer                             | No       | at least 0, at most 10000                                                                                                 | -           |
| `variants[].prices[].installments`               | object                              | No       | -                                                                                                                         | -           |
| `variants[].prices[].installments.count`         | integer                             | No       | at least 2, at most 60                                                                                                    | -           |
| `variants[].prices[].installments.interval`      | string                              | No       | one of `"week"`, `"month"`, `"year"`                                                                                      | -           |
| `variants[].prices[].installments.intervalCount` | integer                             | No       | at least 1, at most 12                                                                                                    | -           |
| `variants[].prices[].retired`                    | boolean                             | No       | -                                                                                                                         | -           |
| `variants[].stock`                               | object                              | Yes      | -                                                                                                                         | -           |
| `variants[].stock.mode`                          | string                              | Yes      | one of `"none"`, `"single"`, `"counted"`                                                                                  | -           |
| `variants[].stock.available`                     | integer                             | No       | at least 0, at most 1000000                                                                                               | -           |
| `variants[].stock.perBuyerLimit`                 | integer                             | No       | at least 1, at most 1000000                                                                                               | -           |
| `variants[].benefitIds`                          | array of string                     | No       | at most 50 items                                                                                                          | -           |
| `variants[].data`                                | object                              | No       | -                                                                                                                         | -           |
| `variants[].terms`                               | string                              | No       | at most 5000 characters                                                                                                   | -           |
| `variants[].salesWindow`                         | object                              | No       | -                                                                                                                         | -           |
| `variants[].salesWindow.startsAt`                | string                              | No       | at most 40 characters                                                                                                     | -           |
| `variants[].salesWindow.endsAt`                  | string                              | No       | at most 40 characters                                                                                                     | -           |
| `variants[].quantity`                            | object                              | No       | -                                                                                                                         | -           |
| `variants[].quantity.min`                        | integer                             | No       | at least 1, at most 1000000                                                                                               | -           |
| `variants[].quantity.max`                        | integer                             | No       | at least 1, at most 1000000                                                                                               | -           |
| `variants[].grantsPerUnit`                       | integer                             | No       | at least 1, at most 100                                                                                                   | -           |
| `variants[].releasesAt`                          | string                              | No       | at most 40 characters                                                                                                     | -           |
| `variants[].bookingSlots`                        | integer                             | No       | at least 0, at most 100                                                                                                   | -           |
| `variants[].weightGrams`                         | integer                             | No       | at least 1, at most 1000000                                                                                               | -           |
| `variants[].dimsMm`                              | object                              | No       | -                                                                                                                         | -           |
| `variants[].dimsMm.length`                       | integer                             | No       | at least 1, at most 5000                                                                                                  | -           |
| `variants[].dimsMm.width`                        | integer                             | No       | at least 1, at most 5000                                                                                                  | -           |
| `variants[].dimsMm.height`                       | integer                             | No       | at least 1, at most 5000                                                                                                  | -           |
| `variants[].customs`                             | object                              | No       | -                                                                                                                         | -           |
| `variants[].customs.hsCode`                      | string or null                      | No       | at most 20 characters                                                                                                     | -           |
| `variants[].customs.originCountry`               | string or null                      | No       | at most 2 characters                                                                                                      | -           |
| `variants[].customs.description`                 | string or null                      | No       | at most 50 characters                                                                                                     | -           |
| `data`                                           | object                              | No       | -                                                                                                                         | -           |
| `benefits`                                       | array of object                     | No       | at most 50 items                                                                                                          | -           |
| `benefits[].id`                                  | string                              | No       | 1 to 64 characters                                                                                                        | -           |
| `benefits[].kind`                                | string                              | No       | one of `"file"`, `"link"`, `"message"`, `"license_key"`, `"access"`, `"manual"`, `"webhook_only"`, `"transfer"`, `"item"` | -           |
| `benefits[].title`                               | string                              | No       | at most 120 characters                                                                                                    | -           |
| `benefits[].afterDays`                           | integer                             | No       | at least 0, at most 3650                                                                                                  | -           |
| `benefits[].availableAt`                         | string                              | No       | at most 40 characters                                                                                                     | -           |
| `benefits[].uses`                                | integer                             | No       | at least 1, at most 10000                                                                                                 | -           |
| `benefits[].seriesId`                            | string                              | No       | at most 64 characters                                                                                                     | -           |
| `benefits[].updatePolicy`                        | string                              | No       | one of `"latest"`, `"purchased"`, `"until"`                                                                               | -           |
| `benefits[].updateMonths`                        | integer                             | No       | at least 1, at most 120                                                                                                   | -           |
| `benefits[].downloadLimit`                       | integer                             | No       | at least 1, at most 10000                                                                                                 | -           |
| `benefits[].url`                                 | string                              | No       | at most 2000 characters                                                                                                   | -           |
| `benefits[].durationDays`                        | integer                             | No       | at least 1, at most 36500                                                                                                 | -           |
| `benefits[].text`                                | string                              | No       | at most 5000 characters                                                                                                   | -           |
| `benefits[].activationLimit`                     | integer                             | No       | at least 1, at most 10000                                                                                                 | -           |
| `benefits[].expiresInDays`                       | integer                             | No       | at least 1, at most 36500                                                                                                 | -           |
| `benefits[].source`                              | string                              | No       | one of `"generated"`, `"seller_list"`                                                                                     | -           |
| `benefits[].resourceType`                        | string                              | No       | at most 64 characters                                                                                                     | -           |
| `benefits[].resourceId`                          | string                              | No       | at most 128 characters                                                                                                    | -           |
| `benefits[].instructions`                        | string                              | No       | at most 2000 characters                                                                                                   | -           |
| `benefits[].itemId`                              | string                              | No       | at most 64 characters                                                                                                     | -           |
| `benefits[].variantId`                           | string                              | No       | at most 64 characters                                                                                                     | -           |
| `benefits[].quantity`                            | integer                             | No       | at least 1, at most 100                                                                                                   | -           |
| `resourceRef`                                    | string                              | No       | at most 128 characters                                                                                                    | -           |
| `refundPolicy`                                   | string                              | No       | at most 2000 characters                                                                                                   | -           |
| `addOns`                                         | array of object                     | No       | at most 20 items                                                                                                          | -           |
| `addOns[].id`                                    | string                              | No       | 1 to 64 characters                                                                                                        | -           |
| `addOns[].label`                                 | string                              | No       | at most 60 characters                                                                                                     | -           |
| `addOns[].prices`                                | array of object                     | No       | at most 40 items                                                                                                          | -           |
| `addOns[].prices[].id`                           | string                              | No       | 1 to 64 characters                                                                                                        | -           |
| `addOns[].prices[].currency`                     | string                              | No       | matches `^[a-z]{3}$`                                                                                                      | -           |
| `addOns[].prices[].mode`                         | string                              | No       | one of `"fixed"`, `"free"`, `"pwyw"`                                                                                      | -           |
| `addOns[].prices[].amount`                       | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `addOns[].prices[].compareAtAmount`              | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `addOns[].prices[].minimum`                      | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `addOns[].prices[].suggested`                    | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `addOns[].prices[].maximum`                      | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `addOns[].prices[].recurring`                    | object                              | No       | -                                                                                                                         | -           |
| `addOns[].prices[].recurring.interval`           | string                              | No       | one of `"day"`, `"week"`, `"month"`, `"year"`                                                                             | -           |
| `addOns[].prices[].recurring.intervalCount`      | integer                             | No       | at least 1, at most 365                                                                                                   | -           |
| `addOns[].prices[].recurring.trialDays`          | integer                             | No       | at least 0, at most 730                                                                                                   | -           |
| `addOns[].prices[].recurring.endAfterPayments`   | integer                             | No       | at least 1, at most 1000                                                                                                  | -           |
| `addOns[].prices[].recurring.intro`              | object                              | No       | -                                                                                                                         | -           |
| `addOns[].prices[].recurring.intro.amount`       | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `addOns[].prices[].recurring.intro.periods`      | integer                             | No       | at least 1, at most 100                                                                                                   | -           |
| `addOns[].prices[].deposit`                      | object                              | No       | -                                                                                                                         | -           |
| `addOns[].prices[].deposit.percentBps`           | integer                             | No       | at least 0, at most 10000                                                                                                 | -           |
| `addOns[].prices[].milestones`                   | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `addOns[].prices[].milestones[].label`           | string                              | No       | at most 60 characters                                                                                                     | -           |
| `addOns[].prices[].milestones[].percentBps`      | integer                             | No       | at least 0, at most 10000                                                                                                 | -           |
| `addOns[].prices[].installments`                 | object                              | No       | -                                                                                                                         | -           |
| `addOns[].prices[].installments.count`           | integer                             | No       | at least 2, at most 60                                                                                                    | -           |
| `addOns[].prices[].installments.interval`        | string                              | No       | one of `"week"`, `"month"`, `"year"`                                                                                      | -           |
| `addOns[].prices[].installments.intervalCount`   | integer                             | No       | at least 1, at most 12                                                                                                    | -           |
| `addOns[].prices[].retired`                      | boolean                             | No       | -                                                                                                                         | -           |
| `addOns[].maxQuantity`                           | integer                             | No       | at least 1, at most 1000                                                                                                  | -           |
| `addOns[].benefitIds`                            | array of string                     | No       | at most 50 items                                                                                                          | -           |
| `payees`                                         | array of object                     | No       | at most 10 items                                                                                                          | -           |
| `payees[].sellerId`                              | string                              | No       | at most 64 characters                                                                                                     | -           |
| `payees[].shareBps`                              | integer                             | No       | at least 0, at most 10000                                                                                                 | -           |
| `eligibility`                                    | object                              | No       | -                                                                                                                         | -           |
| `eligibility.requiresItemId`                     | string                              | No       | at most 64 characters                                                                                                     | -           |
| `eligibility.minRank`                            | integer                             | No       | at least 0, at most 1000                                                                                                  | -           |
| `eligibility.buyerIds`                           | array of string                     | No       | at most 100 items                                                                                                         | -           |
| `capacity`                                       | integer                             | No       | at least 0, at most 1000000                                                                                               | -           |
| `questions`                                      | array of object                     | No       | at most 20 items                                                                                                          | -           |
| `questions[].slug`                               | string                              | No       | at most 64 characters                                                                                                     | -           |
| `questions[].title`                              | string                              | No       | at most 120 characters                                                                                                    | -           |
| `questions[].helpText`                           | string                              | No       | at most 500 characters                                                                                                    | -           |
| `questions[].type`                               | string                              | No       | at most 20 characters                                                                                                     | -           |
| `questions[].required`                           | boolean                             | No       | -                                                                                                                         | -           |
| `questions[].defaultValue`                       | string or number or boolean or null | No       | at most 1000 characters                                                                                                   | -           |
| `questions[].options`                            | array of object                     | No       | at most 200 items                                                                                                         | -           |
| `questions[].options[].value`                    | string                              | No       | at most 120 characters                                                                                                    | -           |
| `questions[].options[].label`                    | string                              | No       | at most 120 characters                                                                                                    | -           |
| `questions[].min`                                | number                              | No       | -                                                                                                                         | -           |
| `questions[].max`                                | number                              | No       | -                                                                                                                         | -           |
| `questions[].pattern`                            | string                              | No       | at most 200 characters                                                                                                    | -           |
| `questions[].currency`                           | string                              | No       | matches `^[a-z]{3}$`                                                                                                      | -           |
| `questions[].visibility`                         | string                              | No       | one of `"public"`, `"after_purchase"`, `"seller_only"`, `"app_only"`                                                      | -           |
| `questions[].filterable`                         | boolean                             | No       | -                                                                                                                         | -           |
| `questions[].sortable`                           | boolean                             | No       | -                                                                                                                         | -           |
| `questions[].uniquePerOwner`                     | boolean                             | No       | -                                                                                                                         | -           |
| `questions[].maxMb`                              | number                              | No       | at least 0.1, at most 100                                                                                                 | -           |
| `questions[].maxFiles`                           | integer                             | No       | at least 1, at most 10                                                                                                    | -           |
| `questions[].per`                                | string                              | No       | one of `"order"`, `"unit"`                                                                                                | -           |
| `questions[].variantIds`                         | array of string                     | No       | at most 250 items                                                                                                         | -           |
| `shipping`                                       | object                              | No       | -                                                                                                                         | -           |
| `shipping.countries`                             | array of string                     | No       | at most 250 items                                                                                                         | -           |
| `shipping.regions`                               | array of string                     | No       | at most 500 items                                                                                                         | -           |
| `shipping.flatRate`                              | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `shipping.additionalRate`                        | integer                             | No       | at least 0, at most 10000000000                                                                                           | -           |
| `shipping.packagingGrams`                        | integer                             | No       | at least 0, at most 1000000                                                                                               | -           |
| `shipping.pickup`                                | boolean                             | No       | -                                                                                                                         | -           |
| `taxCode`                                        | string                              | No       | at most 20 characters                                                                                                     | -           |
| `buyerCountries`                                 | array of string                     | No       | at most 250 items                                                                                                         | -           |
| `customs`                                        | object                              | No       | -                                                                                                                         | -           |
| `customs.hsCode`                                 | string or null                      | No       | at most 20 characters                                                                                                     | -           |
| `customs.originCountry`                          | string or null                      | No       | at most 2 characters                                                                                                      | -           |
| `customs.description`                            | string or null                      | No       | at most 50 characters                                                                                                     | -           |
| `options`                                        | array of object                     | No       | at most 3 items                                                                                                           | -           |
| `options[].id`                                   | string                              | No       | 1 to 16 characters                                                                                                        | -           |
| `options[].name`                                 | string                              | No       | at most 40 characters                                                                                                     | -           |
| `options[].values`                               | array of object                     | No       | at most 20 items                                                                                                          | -           |
| `options[].values[].id`                          | string                              | No       | 1 to 16 characters                                                                                                        | -           |
| `options[].values[].label`                       | string                              | No       | at most 40 characters                                                                                                     | -           |
| `options[].values[].retired`                     | boolean                             | No       | -                                                                                                                         | -           |
| `booking`                                        | object                              | No       | -                                                                                                                         | -           |
| `booking.calendarId`                             | string                              | No       | matches `^[a-f0-9]{24}$`                                                                                                  | -           |
| `booking.timeZone`                               | string                              | No       | at most 64 characters                                                                                                     | -           |
| `booking.slotMinutes`                            | integer                             | No       | at least 0, at most 720                                                                                                   | -           |
| `booking.bufferMinutes`                          | integer                             | No       | at least 0, at most 240                                                                                                   | -           |
| `booking.bufferBeforeMinutes`                    | integer                             | No       | at least 0, at most 240                                                                                                   | -           |
| `booking.seatsPerSlot`                           | integer                             | No       | at least 0, at most 1000                                                                                                  | -           |
| `booking.weekly`                                 | object                              | No       | -                                                                                                                         | -           |
| `booking.weekly.mon`                             | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `booking.weekly.mon[].from`                      | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.mon[].to`                        | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.tue`                             | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `booking.weekly.tue[].from`                      | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.tue[].to`                        | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.wed`                             | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `booking.weekly.wed[].from`                      | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.wed[].to`                        | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.thu`                             | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `booking.weekly.thu[].from`                      | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.thu[].to`                        | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.fri`                             | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `booking.weekly.fri[].from`                      | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.fri[].to`                        | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.sat`                             | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `booking.weekly.sat[].from`                      | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.sat[].to`                        | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.sun`                             | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `booking.weekly.sun[].from`                      | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.weekly.sun[].to`                        | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.exceptions`                             | array of object                     | No       | at most 200 items                                                                                                         | -           |
| `booking.exceptions[].date`                      | string                              | No       | at most 10 characters                                                                                                     | -           |
| `booking.exceptions[].windows`                   | array of object                     | No       | at most 6 items                                                                                                           | -           |
| `booking.exceptions[].windows[].from`            | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.exceptions[].windows[].to`              | string                              | No       | at most 5 characters                                                                                                      | -           |
| `booking.minNoticeMinutes`                       | integer                             | No       | at least 0, at most 43200                                                                                                 | -           |
| `booking.maxDaysAhead`                           | integer                             | No       | at least 0, at most 365                                                                                                   | -           |
| `booking.buyerCancel`                            | object or null                      | No       | -                                                                                                                         | -           |
| `booking.buyerCancel.minutesBefore`              | integer                             | No       | at least 0, at most 43200                                                                                                 | -           |
| `booking.buyerCancel.refund`                     | string                              | No       | one of `"full"`, `"none"`                                                                                                 | -           |
| `booking.buyerReschedule`                        | object or null                      | No       | -                                                                                                                         | -           |
| `booking.buyerReschedule.minutesBefore`          | integer                             | No       | at least 0, at most 43200                                                                                                 | -           |
| `booking.buyerReschedule.maxTimes`               | integer                             | No       | at least 0, at most 10                                                                                                    | -           |
| `booking.seatsPerUnit`                           | integer                             | No       | at least 0, at most 100                                                                                                   | -           |
| `booking.seatsCap`                               | integer                             | No       | at least 0, at most 1000                                                                                                  | -           |
| `booking.bookingLimits`                          | object or null                      | No       | -                                                                                                                         | -           |
| `booking.bookingLimits.perDay`                   | integer or null                     | No       | at least 0, at most 1000                                                                                                  | -           |
| `booking.bookingLimits.perWeek`                  | integer or null                     | No       | at least 0, at most 1000                                                                                                  | -           |
| `booking.reminders`                              | array of object                     | No       | at most 3 items                                                                                                           | -           |
| `booking.reminders[].minutesBefore`              | integer                             | No       | at least 0, at most 10080                                                                                                 | -           |

## Example request

Replace each `YOUR_...` value with your own, and set the credential in the environment variable the sample reads.

```bash title="cURL"
curl -X POST "https://api.console.buildbase.app/api/v1/public/workspaces/YOUR_WORKSPACE_ID/items" \
  -H "x-session-id: $BUILDBASE_SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "typeKey": "string",
  "title": "string",
  "slug": "string",
  "variants": [
    {
      "id": "YOUR_ID",
      "prices": [
        {
          "id": "YOUR_ID",
          "currency": "string",
          "mode": "fixed"
        }
      ],
      "stock": {
        "mode": "none"
      }
    }
  ]
}'
```

```ts title="TypeScript"
const response = await fetch(
  'https://api.console.buildbase.app/api/v1/public/workspaces/YOUR_WORKSPACE_ID/items',
  {
    method: 'POST',
    headers: {
      'x-session-id': process.env.BUILDBASE_SESSION_ID ?? '',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      typeKey: 'string',
      title: 'string',
      slug: 'string',
      variants: [
        {
          id: 'YOUR_ID',
          prices: [
            {
              id: 'YOUR_ID',
              currency: 'string',
              mode: 'fixed',
            },
          ],
          stock: {
            mode: 'none',
          },
        },
      ],
    }),
  }
);
if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}
const data = await response.text();
```

```python title="Python"
import os

import requests

response = requests.post(
    "https://api.console.buildbase.app/api/v1/public/workspaces/YOUR_WORKSPACE_ID/items",
    headers={
        "x-session-id": os.environ["BUILDBASE_SESSION_ID"],
    },
    json={
        "typeKey": "string",
        "title": "string",
        "slug": "string",
        "variants": [
            {
                "id": "YOUR_ID",
                "prices": [
                    {
                        "id": "YOUR_ID",
                        "currency": "string",
                        "mode": "fixed",
                    },
                ],
                "stock": {
                    "mode": "none",
                },
            },
        ],
    },
    timeout=30,
)
response.raise_for_status()
data = response.text
```

## Responses

A successful answer is not described yet. The server answers with the status and body its handler sends.

### Any other status

The handler's own answer. Not described yet: response bodies come from captured responses (server/openapi/captured) and overlays (server/openapi/overlays).

## Errors

Each refusal, what it means, and what to do. The request changed nothing.

### 400 Bad Request

**What it means:** The request failed a `validate()` schema, or an id in the path is not a valid id. `path` names the field.

**What to do:** Fix the field the body names in `path` (or read `message`) and send the request again. Nothing was changed.

```json title="Example"
{
  "error": true,
  "success": false,
  "path": "string",
  "message": "string"
}
```

### 401 Unauthorized

**What it means:** The credential is missing, expired or not accepted here, or the caller's role has no grant for `x-permission` (refused with 401 too). The body is the plain text `Unauthorized`, or a JSON body with a `code` where the gate says why.

**What to do:** Send the credential this operation asks for (see Sign-in above), or sign in again if it expired. A valid credential is also refused when the role has no grant for the permission above.

```text title="Example"
Unauthorized
```

### 429 Too Many Requests

**What it means:** A rate limit in `x-rateLimit` was reached. `retryAfter` and the `Retry-After` header say how many seconds until the window resets.

**What to do:** Wait the number of seconds in the `Retry-After` header (also `retryAfter` in the body), then retry. Slow down repeated calls.

```json title="Example"
{
  "success": false,
  "message": "string",
  "reason": "rate_limited",
  "retryAfter": 1
}
```

## Events

A successful call can send these [webhook events](/webhooks/overview) to the endpoints that subscribe to them:

- [`item.created`](/webhooks/overview#when-each-event-fires)

## Related

- [Workspaces guide](/workspaces/overview): how this part of BuildBase works
- [All Workspaces operations](/http-api/reference/workspaces)
- [API reference](/http-api/reference): every operation, by tag
- [Sign-in and credentials for the HTTP API](/http-api/authentication)
- [How the HTTP API reports errors](/http-api/errors)
- [Make your first call](/http-api/first-call)
- [Error codes](/reference/error-codes): every `code` the API returns
- OpenAPI: operation `workspaces.items.create` in [public-v1.json](https://docs.buildbase.app/openapi/public-v1.json)
