Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

Closient indexes brands from many sources (Open Food Facts, Open Beauty Facts, USDA, manual entry, etc.). A brand with organization=null is unclaimed — crowd-sourced metadata waiting for the legitimate brand owner to claim it and start managing the record. This skill walks an authenticated brand-owner through the claim flow end-to-end.

​
When to use

  • A brand owner wants to manage their products on Closient.
  • The agent needs to attach an Organization to an existing Brand record (so analytics, product edits, and resolver routing work).
  • A retailer’s onboarding flow turned up an unclaimed brand the retailer also owns.
For pure brand creation (no pre-existing record on Closient), the same endpoint creates the brand already linked to the caller’s organization — see Step 2 below.

​
Auth

OAuth token (or API key) with brands:write scope. The caller must hold OWNER or MANAGER role on the Organization that will own the claimed brand. A VIEWER cannot claim.

​
Flow

​
Step 1 — Discover candidate unclaimed brands

GET /brands/api/v1/brands?name=<query>
Returns paginated brands. Unclaimed brands have organization=null in the source data but are NOT filtered by the API today (see Known gaps below). The agent should:
  1. Issue the search.
  2. Pull the full brand record for each candidate via GET /brands/api/v1/brands/{id} to see organization_id.
  3. Present the user with the matches that are unclaimed.

​
Step 2 — Create-and-claim (the supported path today)

POST /brands/api/v1/brands
Content-Type: application/json

{
  "organization_id": "<caller's org short id>",
  "name": "Acme Snacks",
  "website": "https://acmesnacks.com",
  "description": "Premium trail mix and snack foods."
}
If no existing unclaimed record matches, this creates the brand already linked to the caller’s organization (which is the destination state of a claim anyway). The endpoint rejects duplicates within the same organization (409).

​
Step 3 — Enrich the claimed brand

Once the brand exists and is linked, the agent should immediately: 
PATCH /brands/api/v1/brands/{id}
{
  "instagram": "...",
  "facebook": "...",
  "website": "...",
  "description": "..."
}
Social links + description materially improve brand-analytics signal and the brand’s surface on the Closient resolver pages. 
POST /brands/api/v1/brands/{id}/logo
Content-Type: multipart/form-data

logo: <image file>
PNG or SVG, max 2 MB. The logo shows on resolver hosted pages and in search results. 
GET /brands/api/v1/brands/{id}
The organization field should reflect the caller’s organization. Once set, organization cannot be cleared (Brand.organization is a one-way claim per apps/brands/models.py).

​
Required inputs

  • organization_id — the caller’s organization (claim destination).
  • name — brand display name.

​
Optional inputs

  • website, description
  • Social links (instagram, facebook, twitter, linkedin, youtube, tiktok, pinterest, threads) — via PATCH.
  • logo — via POST /brands/{id}/logo.

​
Output

  • verification_status — currently always linked once POST returns 201 (no manual review gate today; see Known gaps).
  • brand_id — the short ID of the linked brand.
  • next_steps — recommend the user upload a logo, fill social links, and start adding products to their brand.

​
Guidance for agents

  • Search first, create second. Always run the discovery query (Step 1) before creating, even if the brand is well-known — the user may have a Closient-side record they don’t know about. Duplicate brands per organization are blocked (409) but cross-org duplicates are not, so this is the only protection against accidentally creating a second crowd-sourced copy.
  • Confirm the organization before posting. The caller may belong to multiple orgs; ask which one owns the brand. The account/whoami endpoint lists the caller’s organizations.
  • One-way claim. Once organization is set, it cannot be cleared via the API (the model raises on attempts to null it). Surface this to the user before the POST.
  • Don’t loop on duplicate errors. A 409 means the brand already exists for that organization — fetch and patch instead of retrying.

​
Known gaps (planned)

  • No “claim existing unclaimed brand” endpoint. Today the BrandUpdateIn schema does not accept organization, so the only way to attach an organization to an existing unclaimed record is via the POST (which creates a new linked record). A dedicated POST /brands/{id}/claim is planned so an existing crowd-sourced Brand can be claimed without duplicating it. Until then, the agent should flag candidate unclaimed records to the human owner for reconciliation.
  • No ?unclaimed=true filter. The list endpoint accepts name and organization_id filters but not a “show me only unclaimed” query. Agents must fetch detail records to determine claim state.
  • No ownership verification step. There is no domain-verification / email-loop / DNS-TXT check today — claims are accepted on the strength of the OAuth scope alone. A verification step (TXT record on the brand’s website domain) is planned.
  • No brand-merge. If a duplicate linked brand was accidentally created, there is no API to merge it into the canonical record.
  • onboard-retailer — the parallel flow for retailer Organizations connecting their POS.
  • brand-scan-summary — once claimed, see engagement on your products.
  • brand-retail-footprint — once claimed, see distribution coverage.
  • brand-search-demand — once claimed, see geographic demand.