Greenflash Docs

Everything Greenflash knows about your AI product is available through the API. Embed analytics in your own product, build custom dashboards, automate workflows, or power AI-assisted experiences through the chat endpoint.

Authentication

Every request requires your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate keys at Settings → Developers → API Keys.

What’s Available

Data Endpoints (All Plans)

Core data — your conversations, users, organizations, and configuration. Available on every plan, including Free.

Messages & Interactions

Method	Endpoint	Description
`POST`	`/v1/messages`	Log conversation messages
`GET`	`/v1/interactions`	List conversations
`GET`	`/v1/interactions/{id}`	Get conversation detail

Users

Method	Endpoint	Description
`GET`	`/v1/users`	List users
`POST`	`/v1/users`	Create or upsert a user
`PUT`	`/v1/users/{userId}`	Update a user
`GET`	`/v1/users/{userId}/segments`	Get user segment memberships

Organizations

Method	Endpoint	Description
`GET`	`/v1/organizations`	List organizations
`POST`	`/v1/organizations`	Create an organization
`PUT`	`/v1/organizations/{id}`	Update an organization

Products

Method	Endpoint	Description
`GET`	`/v1/products`	List products
`GET`	`/v1/products/{productId}`	Get product detail

Prompts

Method	Endpoint	Description
`GET`	`/v1/prompts`	List prompts
`POST`	`/v1/prompts`	Create a prompt
`GET`	`/v1/prompts/{id}`	Get prompt detail
`PUT`	`/v1/prompts/{id}`	Update a prompt
`DELETE`	`/v1/prompts/{id}`	Delete a prompt

Models, Segments & More

Method	Endpoint	Description
`GET`	`/v1/models`	List models
`GET`	`/v1/models/{modelId}`	Get model detail
`GET`	`/v1/segments`	List segments
`POST`	`/v1/segments`	Create a custom segment
`GET`	`/v1/segments/{segmentId}`	Get segment detail
`GET`	`/v1/inbox`	List inbox items
`GET`	`/v1/inbox/{conversationId}`	Get inbox item detail
`POST`	`/v1/ratings`	Log a user rating
`POST`	`/v1/events`	Create a business event

Analytics Endpoints (Growth+)

Computed insights, AI-generated summaries, and aggregated metrics. These require a Growth or Enterprise plan.

Method	Endpoint	What you get
`GET`	`/v1/products/{productId}/analytics`	Product-level quality, topics, keywords, sentiment
`GET`	`/v1/interactions/{id}/analytics`	Per-conversation analysis scores
`GET`	`/v1/users/{userId}/analytics`	User behavior patterns and quality metrics
`GET`	`/v1/organizations/{id}/analytics`	Organization-level aggregates
`GET`	`/v1/segments/{segmentId}/analytics`	Segment health and comparison data
`GET`	`/v1/models/{modelId}/analytics`	Model performance and quality scores
`GET`	`/v1/prompts/{id}/analytics`	Prompt effectiveness and optimization data

Chat Endpoint (Growth+)

Method	Endpoint	What you get
`POST`	`/v1/chat`	AI-powered conversational analytics with SSE streaming

Analysis Modes

Analytics endpoints support two modes. Pick the one that matches your use case.

Simple Mode

Fast. No rate limits. Returns numeric aggregates only — averages, counts, distributions. Ideal for dashboards, polling, and high-frequency requests.

?mode=simple

Insights Mode

Deep. Rate limited. Full AI analysis including topic extraction, keyword analysis, and generated summaries. Default when no mode is specified.

?mode=insights

Chat Endpoint

The chat endpoint is the same Greenflash AI assistant available in-app and via Slack — now accessible through the API. It streams responses using Server-Sent Events (SSE).

curl -sS -N \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"question": "What are the top issues my users are facing?"}' \
  "https://www.greenflash.ai/api/v1/chat"

SSE event types:

Event	Description
`tool_call`	The agent is calling an internal tool (e.g., `getProductAnalytics`)
`tool_result`	Tool call completed
`text_delta`	Partial response text — concatenate these into the final answer
`done`	Stream complete. Contains `conversationId` for follow-up turns
`error`	Something went wrong. Contains `error` and `code`

Multi-turn conversations: Capture the conversationId from the done event and pass it back in subsequent requests along with a messages array to maintain context.

curl -sS -N \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which users are most affected?",
    "conversationId": "conv_abc123",
    "messages": [
      {"role": "user", "content": "What are the top issues my users are facing?"},
      {"role": "assistant", "content": "Based on your recent conversations..."}
    ]
  }' \
  "https://www.greenflash.ai/api/v1/chat"

Example: End-to-End Setup

Here’s the full loop — create a user, log a conversation, then retrieve analytics.

1. Identify a user

curl -sS -X POST https://www.greenflash.ai/api/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user-456",
    "externalOrganizationId": "acme-corp-123",
    "name": "Jane Doe",
    "email": "jane@acme.com",
    "properties": {
      "plan": "enterprise",
      "role": "admin"
    }
  }'

2. Log a conversation

curl -sS -X POST https://www.greenflash.ai/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "YOUR_PRODUCT_ID",
    "externalConversationId": "conv-789",
    "externalUserId": "user-456",
    "model": "gpt-4o",
    "systemPrompt": "You are a helpful customer support assistant.",
    "messages": [
      {
        "role": "user",
        "content": "How do I reset my password?",
        "externalMessageId": "msg-001"
      },
      {
        "role": "assistant",
        "content": "Go to Settings → Security → Reset Password. You will receive a confirmation email within 60 seconds.",
        "externalMessageId": "msg-002"
      }
    ]
  }'

3. Retrieve analytics

curl -sS https://www.greenflash.ai/api/v1/products/YOUR_PRODUCT_ID/analytics?mode=insights \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "totalConversations": 487,
  "averageUserSentiment": { "label": "positive", "score": 0.68 },
  "averageConversationRating": 4.3,
  "averageConversationQualityIndex": 0.82,
  "topics": [
    { "name": "Billing Questions", "count": 142 },
    { "name": "Technical Support", "count": 98 },
    { "name": "Feature Requests", "count": 87 }
  ],
  "keywords": [
    { "name": "billing", "count": 234 },
    { "name": "invoice", "count": 156 }
  ]
}

4. Ask the AI agent

curl -sS -N \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"question": "Why are billing conversations rated so poorly?"}' \
  "https://www.greenflash.ai/api/v1/chat"

The chat agent investigates your data, surfaces root causes with evidence, and recommends specific fixes.

Pagination

All list endpoints use Link header pagination (RFC 8288).

curl -sS https://www.greenflash.ai/api/v1/interactions?page=1&limit=50 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response body: a flat JSON array of items
Pagination info: returned in the Link HTTP header
No rel="next" link means you’re on the last page

Link: <https://www.greenflash.ai/api/v1/interactions?page=2&limit=50>; rel="next"

Rate Limits

Insights mode analytics are rate limited on a rolling hourly window:

Plan	Analytics (insights mode)	Chat
Growth	50 / hour	20 / hour
Enterprise	Custom	Custom

Simple mode analytics are not rate limited. Caching: Repeated requests with the same parameters return cached results without consuming your rate limit. Use consistent query parameters to maximize cache hits.

Use mode=simple for dashboards and high-frequency polling. Reserve mode=insights for deep analysis.

White Labeling

Embed Greenflash analytics directly in your product under your own brand. Deliver user- or organization-specific insights powered by Greenflash, with full control over branding and domain.

Brand control — Remove all Greenflash branding for a fully native experience
Tenant isolation — Per-customer domains and isolated analytics environments
Dual modes — Use simple for real-time dashboards, insights for deep analysis

Available on the Enterprise plan. Contact us to get started.

Error Handling

Status	Meaning	What to do
`401`	Invalid or missing API key	Check your key at Developer Settings
`403`	Plan doesn’t include this feature	Upgrade your plan
`404`	Resource not found	Verify the ID and try again
`429`	Rate limit exceeded	Wait and retry, or switch to `mode=simple`

Next Steps

API Reference

Full endpoint documentation with request/response schemas.

SDK Quickstart

Get your first insight in under 5 minutes.

Claude Code Skill

Use Greenflash directly from your coding agent.

Business Events

Link conversations to real business outcomes.

Getting Started

Features

Data & Integrations

Analyses

Developers

Public API

Authentication

What’s Available

Data Endpoints (All Plans)

Analytics Endpoints (Growth+)

Chat Endpoint (Growth+)

Analysis Modes

Simple Mode

Insights Mode

Chat Endpoint

Example: End-to-End Setup

1. Identify a user

2. Log a conversation

3. Retrieve analytics

4. Ask the AI agent

Rate Limits

White Labeling

Error Handling

Next Steps

API Reference

SDK Quickstart

Claude Code Skill

Business Events

Getting Started

Features

Data & Integrations

Analyses

Developers

​Authentication

​What’s Available

​Data Endpoints (All Plans)

​Analytics Endpoints (Growth+)

​Chat Endpoint (Growth+)

​Analysis Modes

Simple Mode

Insights Mode

​Chat Endpoint

​Example: End-to-End Setup

​1. Identify a user

​2. Log a conversation

​3. Retrieve analytics

​4. Ask the AI agent

​Pagination

​Rate Limits

​White Labeling

​Error Handling

​Next Steps

API Reference

SDK Quickstart

Claude Code Skill

Business Events

Authentication

What’s Available

Data Endpoints (All Plans)

Analytics Endpoints (Growth+)

Chat Endpoint (Growth+)

Analysis Modes

Chat Endpoint

Example: End-to-End Setup

1. Identify a user

2. Log a conversation

3. Retrieve analytics

4. Ask the AI agent

Pagination

Rate Limits

White Labeling

Error Handling

Next Steps