Wellspring REST API

Access brand content programmatically for AI chatbots and integrations.

Overview

The Wellspring API allows authorized retailers to pull brand content — dossiers, articles, images, and videos — for use in AI chatbots, product pages, and other integrations.

Base URL: https://wellspring.icecap.ai/api/v1

All endpoints return JSON. Retailers can only access brands they have been authorized for.

Wellspring is purpose-built for seamless integration with Icecap AI's Sherpa chatbot agents — all Sherpa agents come with Wellspring automatically built in. That said, the API is fully compatible with any AI agent or chatbot platform your team uses.

Authentication

All API requests require a Bearer token in the Authorization header. Your API key is available in your retailer dashboard under API Keys.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://wellspring.icecap.ai/api/v1/brands

Keep your API key secret. Do not expose it in client-side code. If compromised, contact your account administrator to regenerate it.

List Brands

GET/api/v1/brands

Returns all brands your retailer account is authorized to access.

Query Parameters

Parameter	Description
include	Set to `briefs` to include a short AI-generated summary for each brand.
format	Set to `text` to receive a single plain-text summary string instead of JSON. Ideal for preloading into a chatbot prompt.

Default Response

{
  "brands": [
    {
      "id": "clx1abc...",
      "name": "Example Brand",
      "description": "Premium lifestyle brand with a focus on quality",
      "logoUrl": "https://..."
    }
  ]
}

With Briefs

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://wellspring.icecap.ai/api/v1/brands?include=briefs

{
  "brands": [
    {
      "id": "clx1abc...",
      "name": "Example Brand",
      "description": "Premium lifestyle brand with a focus on quality",
      "logoUrl": "https://...",
      "dossierBrief": "Example Brand is known for its premium quality, blending heritage craftsmanship with modern design."
    }
  ]
}

Text Format

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://wellspring.icecap.ai/api/v1/brands?include=briefs&format=text

{
  "summary": "- Example Brand: Known for its premium quality, blending heritage craftsmanship with modern design.\n- Another Brand: Sustainable outdoor gear for adventurous lifestyles."
}

The text format is designed to be dropped directly into a chatbot's system prompt as a brand catalog. Briefs are AI-generated and cached — first request may take a few seconds.

Search Brands

GET/api/v1/search

Search authorized brands by name. Performs a case-insensitive substring match. Useful for chatbots that need to find a brand based on user input.

Query Parameters

Parameter	Description
q	Required. The search query string.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://wellspring.icecap.ai/api/v1/search?q=example

{
  "query": "example",
  "brands": [
    {
      "id": "clx1abc...",
      "name": "Example Brand",
      "description": "Premium lifestyle brand with a focus on quality",
      "logoUrl": "https://..."
    }
  ]
}

Brand Context

GET/api/v1/context

Returns full brand context by name — the recommended endpoint for chatbot deep-dives. Includes the agent card, brief dossier, articles, and media in a single request. Looks up by exact name first, then falls back to partial match.

Query Parameters

Parameter	Description
name	Required. The brand name to look up.
format	Set to `prompt` to receive a single prompt-ready text string instead of structured JSON. Ideal for injecting directly into a chatbot system prompt.

Prompt Format (Recommended for Chatbots)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://wellspring.icecap.ai/api/v1/context?name=Example+Brand&format=prompt"

{
  "brand": {
    "id": "clx1abc...",
    "name": "Example Brand"
  },
  "format": "prompt",
  "prompt": "=== AGENT SALES CARD ===\nBRAND: Example Brand | Premium lifestyle | ...\n\n=== BRAND SUMMARY ===\nExample Brand is known for...\n\n=== REFERENCE ARTICLES ===\n..."
}

The promptfield is a structured text block with section delimiters, ready to be injected into a chatbot's context. Agent card and brief dossier are AI-generated and cached on first request.

JSON Format

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://wellspring.icecap.ai/api/v1/context?name=Example+Brand"

{
  "brand": {
    "id": "clx1abc...",
    "name": "Example Brand",
    "description": "Premium lifestyle brand with a focus on quality",
    "url": "https://www.example.com",
    "logoUrl": "https://..."
  },
  "agentCard": "BRAND: Example Brand | Premium lifestyle | ...",
  "dossierBrief": "Example Brand is known for its premium quality...",
  "articles": [
    {
      "title": "Our Signature Collection",
      "body": "Introduced in 2015...",
      "url": "https://www.example.com/signature-collection"
    }
  ],
  "images": ["https://storage.example.com/brand-hero.jpg"],
  "videoUrl": "https://www.youtube.com/watch?v=example"
}

Brand Profile

GET/api/v1/brands/:brandId

Returns the brand profile — name, description, and logo. Useful for quick lookups like "do we carry this brand?"

Response

{
  "id": "clx1abc...",
  "name": "Example Brand",
  "description": "Premium lifestyle brand with a focus on quality",
  "logoUrl": "https://..."
}

Dossier

GET/api/v1/brands/:brandId/dossier

Returns the brand dossier — a comprehensive briefing covering history, tone, audience, products, and key facts. Ideal for powering a chatbot's brand knowledge.

Query Parameters

Parameter	Description
format	`brief` for a 2-3 sentence summary, or `agent-card` for a structured sales enablement card. Omit for the full dossier.

Full Dossier

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://wellspring.icecap.ai/api/v1/brands/:brandId/dossier

{
  "dossier": "Example Brand is a premium lifestyle company founded in...",
  "format": "full"
}

Brief Dossier

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://wellspring.icecap.ai/api/v1/brands/:brandId/dossier?format=brief

{
  "dossier": "Example Brand is known for its premium quality, blending heritage craftsmanship with modern design.",
  "format": "brief"
}

The brief summary is AI-generated and cached. First request may take a few seconds.

Agent Card

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://wellspring.icecap.ai/api/v1/brands/:brandId/dossier?format=agent-card

{
  "dossier": "BRAND: Example Brand | Premium lifestyle | Est. 2010\nPOSITION: Mid-to-high range, targets quality-conscious consumers 25-45\nVOICE: Warm, confident, approachable\n...",
  "format": "agent-card"
}

The agent card is a structured, token-efficient briefing designed to be dropped into a chatbot's system prompt. It covers brand positioning, selling angles, objection handling, and tone guidance. AI-generated and cached on first request.

Agent Card

GET/api/v1/brands/:brandId/agent-card

Returns a structured sales enablement card optimized for AI agents. The card tells your chatbot how to sellthe brand — customer pain points, aspirations, selling angles, objection handling, and do/don't rules. Also available via the dossier endpoint with ?format=agent-card.

Response

{
  "agentCard": "BRAND: Example Brand | Premium lifestyle | Est. 2010\nPOSITION: Mid-to-high range ($50-500), targets quality-conscious consumers 25-45\nVOICE: Warm, confident, approachable\nPAIN POINTS: Desire for quality over quantity, gift-giving confidence, sustainability concerns\nASPIRATIONS: Curated lifestyle, reliable quality, feel-good purchases\nKEY PRODUCTS: Signature Line ($100-300), Essentials ($50-150), Gift Sets ($75-200)\nSELLING ANGLES: Ethically sourced materials, 5-year quality guarantee, designed in-house\nOBJECTION HANDLING: Price → quality guarantee and longevity; Trust → transparent sourcing; Fit → easy returns\nDO: Highlight quality and craftsmanship, mention guarantee, suggest products by occasion\nDON'T: Compare to competitors, offer unauthorized discounts, use overly formal language"
}

AI-generated and cached. First request may take a few seconds to generate.

Articles

GET/api/v1/brands/:brandId/articles

Returns brand articles — product stories, brand news, and selling points. A chatbot can reference these when discussing specific products or brand features.

Response

{
  "articles": [
    {
      "title": "Our Signature Collection",
      "body": "Introduced in 2015, the Signature line brings together...",
      "url": "https://www.example.com/signature-collection"
    }
  ]
}

Images

GET/api/v1/brands/:brandId/images

Returns brand image URLs. Use these to display product imagery, campaign visuals, or brand assets in your chatbot or storefront.

Response

{
  "images": [
    "https://storage.example.com/brand-hero.jpg",
    "https://storage.example.com/brand-product-1.jpg"
  ]
}

Video

GET/api/v1/brands/:brandId/video

Returns the brand's promotional video URL. Typically a YouTube link to a campaign or brand story video.

Response

{
  "videoUrl": "https://www.youtube.com/watch?v=example"
}

Full Content

GET/api/v1/brands/:brandId/content

Returns all brand content in a single response. Useful if you need everything at once rather than making multiple requests.

Response

{
  "brand": {
    "id": "clx1abc...",
    "name": "Example Brand",
    "description": "Premium lifestyle brand with a focus on quality",
    "logoUrl": "https://..."
  },
  "content": {
    "title": "Example Brand Content",
    "dossier": "Example Brand is a premium lifestyle company...",
    "agentCard": "BRAND: Example Brand | Premium lifestyle | ...",
    "articles": [...],
    "imageUrls": [...],
    "videoUrl": "https://..."
  }
}

Error Handling

The API uses standard HTTP status codes. Errors return a JSON object with an error field.

Status	Meaning
401	Missing or invalid API key
403	Not authorized for this brand
404	Brand not found

{
  "error": "Not authorized for this brand"
}