Brands API

Look up, create, and read the enrichment history of brands. Use these before starting a brand enrichment job to avoid creating a duplicate brand, and after one to read what the job produced.

Brand matching is case-insensitive throughout. ACME, Acme, and acme are the same brand.

Endpoints

Check a brand

Returns whether a brand with this name exists in the organization. Cheaper than a create call when you only need the answer.

Endpoint: POST /api/{organization}/brands/check

Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/brands/check \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Tools" }'

Response

{
  "success": true,
  "data": {
    "exists": true
  }
}

Create a brand

Creates the brand and returns it. When a brand with that name already exists, the existing record comes back with created: false rather than an error, so this endpoint is safe to call repeatedly.

Endpoint: POST /api/{organization}/brands/create

Request

The generated slug lowercases the name and replaces each run of non-alphanumeric characters with a hyphen. If that slug is already taken by another brand, a timestamp is appended to keep it unique, so the slug you get back is not always the slug you would predict. Read it from the response rather than recomputing it.

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/brands/create \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Tools" }'

Response

{
  "success": true,
  "data": {
    "brand": {
      "id": "brand_abc123",
      "name": "Acme Tools",
      "slug": "acme-tools"
    },
    "created": true
  }
}

Brand enrichment history

Returns every enrichment result recorded against a brand name, newest first. Results are ordered by completion time, falling back to creation time for items that never completed.

Endpoint: POST /api/{organization}/brands/enrichment-history

Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/brands/enrichment-history \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Tools", "page": 1, "limit": 10 }'

Response

{
  "success": true,
  "data": {
    "history": [
      {
        "id": "beji_abc123",
        "brandName": "Acme Tools",
        "enrichedAttributes": { "founded": "1974" },
        "referenceData": { "sources": ["https://example.com/about"] },
        "completedAt": "2024-01-15T14:30:00Z",
        "createdAt": "2024-01-15T14:28:00Z",
        "modelType": "pro-v1",
        "status": "completed",
        "errorMessage": null
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 3,
      "totalPages": 1
    }
  }
}

A name with no history returns an empty history array and a total of 0, not a 404.

Errors

Next steps

• Brand Enrichment API - Run a job against these brands
• Brand Enrichment - What the job produces