consciousbn Integration API

A REST API for integrating supermarket and partner databases with consciousbn. Supports bulk brand imports, real-time supermarket sync, and full CRUD management. All responses are JSON.

Authentication

Integration and admin endpoints require a Bearer token in the Authorization header:

CopyAuthorization: Bearer cbk_live_a1b2c3d4e5f6...

API keys have one of four permission levels:

Generate API Key

Create an API key for a supermarket or partner. You need an admin key for the first request, or no key if this is the very first key being created.

Active Keys

Requires admin key in the field above.

Quick Start

1. Test the connection

Copycurl http://localhost:3001/api/health

2. Fetch all brands

Copycurl http://localhost:3001/api/brands

3. Search brands stocked at Tesco

Copycurl "http://localhost:3001/api/brands?supermarket=Tesco&grade=A"

4. Bulk import from your system (Node.js)

Copyconst response = await fetch('http://localhost:3001/api/v1/import/brands', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer cbk_live_YOUR_KEY_HERE'
  },
  body: JSON.stringify({
    source: 'Tesco Product Database v2',
    brands: [
      {
        name: 'Green Valley Oats',
        parentCompany: 'Green Valley Foods Ltd',
        country: 'UK',
        category: 'Food & Drink',
        description: 'Award-winning organic oats brand.',
        esgCommitments: true,
        esgMet: true,
        lawsuits: false,
        accreditations: { organic: true, vegan: true },
        supermarkets: ['Tesco', 'Waitrose']
      }
      // ... up to 500 brands per request
    ]
  })
});
const result = await response.json();
console.log(result.data.summary);
// { total: 1, inserted: 1, updated: 0, skipped: 0, errors: 0 }

5. Python example

Copyimport requests

API = 'http://localhost:3001'
KEY = 'cbk_live_YOUR_KEY_HERE'
HEADERS = {'Authorization': f'Bearer {KEY}'}

# Bulk import
brands = [{'name': 'EcoBrand', 'category': 'Cleaning', 'esgCommitments': True, ...}]
res = requests.post(f'{API}/api/v1/import/brands',
    json={'source': 'Sainsburys DB', 'brands': brands}, headers=HEADERS)
print(res.json())

Public API

GET /api/brands

Returns a list of brands with optional filtering, search, and sorting. No authentication required.

CopyGET /api/brands?q=organic&grade=A&accred=vegan&accred=bcorp&limit=20

200 OK
{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Earth Essentials",
      "parentCompany": "GreenCorp Holdings",
      "country": "UK",
      "category": "Personal Care",
      "description": "Premium organic personal care...",
      "esgCommitments": true,
      "esgMet": true,
      "lawsuits": false,
      "accreditations": { "vegan": true, "crueltyFree": true, "organic": true, "bcorp": true },
      "sustainabilityScore": 100,
      "grade": "A",
      "supermarkets": ["Sainsbury's", "Waitrose"],
      "createdAt": "2025-06-01T10:00:00Z",
      "updatedAt": "2025-06-01T10:00:00Z"
    }
  ]
}

GET /api/brands/:id

Returns a single brand by its numeric ID.

CopyGET /api/brands/1
200 OK — single brand object (same shape as above)

POST /api/brands

Creates a new brand. Grade and score are auto-calculated from ESG fields. Name must be unique.

CopyPOST /api/brands
Content-Type: application/json

{
  "name": "EcoBrand",                  // required, max 200 chars
  "parentCompany": "EcoCorp Ltd",
  "country": "UK",
  "category": "Food & Drink",
  "description": "Sustainable food brand.",
  "esgCommitments": true,
  "esgMet": true,
  "lawsuits": false,
  "accreditations": {
    "vegan": true,
    "crueltyFree": false,
    "organic": true,
    "bcorp": false
  },
  "supermarkets": ["Tesco", "Waitrose"]
}

201 Created — created brand object

PUT /api/brands/:id

Full update of a brand. Missing fields fall back to existing values.

CopyPUT /api/brands/42
Content-Type: application/json
{ "esgMet": true, "accreditations": { "bcorp": true } }

200 OK — updated brand object

DELETE /api/brands/:id

CopyDELETE /api/brands/42
200 OK
{ "success": true, "data": { "deleted": true, "id": 42 } }

GET /api/meta

Returns distinct values for filter dropdowns.

CopyGET /api/meta
200 OK
{ "success": true, "data": { "categories": ["Cleaning","Food & Drink",...], "supermarkets": ["ASDA","Tesco",...], "grades": ["A","B","C","D","F"] } }

GET /api/stats

Dashboard summary stats in one query.

CopyGET /api/stats
200 OK
{ "success": true, "data": { "total": 10, "gradeA": 3, "avgScore": 68, "certified": 8, "gradeDistrib": [...], "accredStats": { "vegan": 6, "crueltyFree": 7, "organic": 5, "bcorp": 4 } } }

Supermarket Integration API

POST /api/v1/import/brands

Bulk upsert up to 500 brands per request. Matches existing brands by name and updates them; new brands are inserted. If the API key has a supermarket tag, that supermarket is automatically added to each brand.

CopyPOST /api/v1/import/brands
Authorization: Bearer cbk_live_YOUR_KEY
Content-Type: application/json

{
  "source": "Tesco Weekly Sync",
  "brands": [
    {
      "name": "Green Valley Oats",
      "parentCompany": "Green Valley Foods",
      "country": "UK",
      "category": "Food & Drink",
      "esgCommitments": true,
      "esgMet": true,
      "lawsuits": false,
      "accreditations": { "vegan": true, "organic": true },
      "supermarkets": ["Tesco"]
    }
  ]
}

200 OK
{
  "success": true,
  "data": {
    "summary": { "total": 1, "inserted": 1, "updated": 0, "skipped": 0, "errors": 0 },
    "errors": [],
    "importId": 3
  }
}

GET /api/v1/brands/by-supermarket/:supermarket

Returns all brands stocked at the specified supermarket. Useful for syncing your inventory against consciousbn.

CopyGET /api/v1/brands/by-supermarket/Tesco
Authorization: Bearer cbk_live_YOUR_KEY

200 OK — array of brand objects stocked at Tesco

PATCH /api/v1/brands/:id/supermarkets

Add or remove a brand from specific supermarkets without overwriting others.

CopyPATCH /api/v1/brands/7/supermarkets
Authorization: Bearer cbk_live_YOUR_KEY
Content-Type: application/json

{ "add": ["Tesco", "Ocado"], "remove": ["ASDA"] }

200 OK
{ "success": true, "data": { "id": 7, "supermarkets": ["Ocado", "Tesco", "Waitrose"] } }

GET /api/v1/import/logs

View the last 50 import runs for the authenticated API key.

CopyGET /api/v1/import/logs
Authorization: Bearer cbk_live_YOUR_KEY

200 OK
[{ "id": 3, "source": "Tesco Weekly Sync", "total": 1, "inserted": 1, "updated": 0, "skipped": 0, "errors": 0, "status": "done", "started_at": "...", "finished_at": "..." }]

Admin: Key Management

GET /api/admin/keys

List all API keys. Requires admin-level key.

CopyGET /api/admin/keys
Authorization: Bearer cbk_live_ADMIN_KEY

POST /api/admin/keys

Create a new API key. The first key ever can be created without authentication (bootstrap).

CopyPOST /api/admin/keys
Authorization: Bearer cbk_live_ADMIN_KEY
Content-Type: application/json

{
  "name": "Tesco Integration",
  "partnerType": "supermarket",
  "supermarket": "Tesco",
  "permissions": ["read","write"],
  "rateLimit": 2000
}

201 Created
{
  "success": true,
  "data": { "id": 2, "name": "Tesco Integration", "key": "cbk_live_...", ... },
  "warning": "Save this key now — it will never be shown again."
}

DELETE /api/admin/keys/:id

CopyDELETE /api/admin/keys/2
Authorization: Bearer cbk_live_ADMIN_KEY
200 OK — { "revoked": true, "id": 2 }

Error Codes

Copy// All errors follow this shape:
{ "success": false, "error": "A brand with this name already exists" }