---
title: "Create a brand"
method: POST
path: "/brands"
tags: ["brands"]
---

# Create a brand

`POST /brands`

## Request

- Base URL: `https://shruwd.io/api/v1`
- URL: `https://shruwd.io/api/v1/brands`
- Auth: HTTP bearer

Creates the brand and its **self entity** with one alias (the name) and
one domain (the registrable domain of `domain`), then plants the first
cycle so the next sweep measures it.

A caller with no workspace gets one here, on the free tier.

On the free tier the first cycle is the one free measurement, allowed
once per registrable domain ever; `snapshot` says whether it was
`planned` or `already_taken`. On a weekly plan the first cycle is a
`scheduled` one due now and `snapshot` is `null`.

A name of six characters or fewer, or an ordinary English word, is
refused with `422 context_terms_required` until `contextTerms` is
given — the same rule as a competitor, because the brand's name is
its own first alias and the headline mention rate counts it.

## Request body

- CreateBrandRequest
  - `name` string, required
  - `domain` string, required: A host or URL; reduced to its registrable domain (`www.northwind.io/pricing` → `northwind.io`).
  - `timezone` string: IANA zone. Defaults to UTC.
  - `contextTerms` string[]: Words that appear near the name when it means the company, such as a product category. Required when the name is six characters or fewer or an ordinary English word; a mention then counts only near one of them. The brand's domain is added to them.

## Response `201`

Created.

- BrandCreated
  - `brandId` string, required
  - `slug` string, required: The URL handle, derived from the name. See BrandSummary.
  - `name` string, required
  - `domain` string, required
  - `timezone` string, required
  - `selfEntityId` string, required: The brand's own entity; edit its aliases with `PUT /entities/{entityId}`.
  - `engines` Engine[], required
  - `firstCycle` object, nullable, required: The cycle planted for the next sweep. Null when none was (free tier, domain already measured).
    - `cycleId` string, required
    - `kind` 'scheduled' | 'manual', required
    - `scheduledFor` string, date-time, required
  - `snapshot` 'planned' | 'already_taken' | 'null', nullable, required: Free tier only. `already_taken` means this registrable domain has had its free measurement, in this workspace or another; nothing will run.

## Other responses

- `409`: `duplicate_domain`: an unarchived brand in this workspace already has the domain (`details` names it). `plan_limit`: the plan's brand count is used up.
- `422`: `context_terms_required`, `invalid_domain`, `invalid_name`, `invalid_timezone`.
- `default`: Every failure has this body.

---

[API](https://skmtc.dev/shruwd/apis/shruwd-api.md) · [All operations](https://skmtc.dev/shruwd/apis/shruwd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shruwd/apis/shruwd-api/revisions/64a5da079928?raw)