> ## Documentation Index
> Fetch the complete documentation index at: https://docs.greenflash.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Public API

> Programmatic access to your conversation data, analytics, and AI-powered insights.

*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:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
Authorization: Bearer YOUR_API_KEY
```

Generate keys at [Settings → Connect → API keys](https://www.greenflash.ai/app/settings/connect?section=api-keys).

***

## What's Available

### Data Endpoints (All Plans)

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

<AccordionGroup>
  <Accordion title="Messages & Interactions" icon="comments">
    | Method | Endpoint                | Description               |
    | ------ | ----------------------- | ------------------------- |
    | `POST` | `/v1/messages`          | Log conversation messages |
    | `GET`  | `/v1/interactions`      | List conversations        |
    | `GET`  | `/v1/interactions/{id}` | Get conversation detail   |
  </Accordion>

  <Accordion title="Users" icon="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 |
  </Accordion>

  <Accordion title="Organizations" icon="building">
    | Method | Endpoint                 | Description            |
    | ------ | ------------------------ | ---------------------- |
    | `GET`  | `/v1/organizations`      | List organizations     |
    | `POST` | `/v1/organizations`      | Create an organization |
    | `PUT`  | `/v1/organizations/{id}` | Update an organization |
  </Accordion>

  <Accordion title="Products" icon="cube">
    | Method | Endpoint                   | Description        |
    | ------ | -------------------------- | ------------------ |
    | `GET`  | `/v1/products`             | List products      |
    | `GET`  | `/v1/products/{productId}` | Get product detail |
  </Accordion>

  <Accordion title="Prompts" icon="sparkles">
    | 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   |
  </Accordion>

  <Accordion title="Models, Segments & More" icon="layer-group">
    | 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 |
  </Accordion>
</AccordionGroup>

### 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.

<CardGroup cols={2}>
  <Card title="Simple Mode" icon="bolt">
    **Fast. No rate limits.** Returns numeric aggregates only — averages, counts, distributions. Ideal for dashboards, polling, and high-frequency requests.

    ```
    ?mode=simple
    ```
  </Card>

  <Card title="Insights Mode" icon="brain">
    **Deep. Rate limited.** Full AI analysis including topic extraction, keyword analysis, and generated summaries. Default when no mode is specified.

    ```
    ?mode=insights
    ```
  </Card>
</CardGroup>

***

## 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).

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl -sS https://www.greenflash.ai/api/v1/products/YOUR_PRODUCT_ID/analytics?mode=insights \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"vesper"}}
{
  "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

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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).

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
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.

<Tip>
  Use `mode=simple` for dashboards and high-frequency polling. Reserve `mode=insights` for deep analysis.
</Tip>

***

## 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](mailto:founders@greenflash.ai) to get started.

***

## Error Handling

| Status | Meaning                           | What to do                                                                                            |
| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `401`  | Invalid or missing API key        | Check your key at [Connect settings](https://www.greenflash.ai/app/settings/connect?section=api-keys) |
| `403`  | Plan doesn't include this feature | [Upgrade your plan](https://www.greenflash.ai/app/settings/billing)                                   |
| `404`  | Resource not found                | Verify the ID and try again                                                                           |
| `429`  | Rate limit exceeded               | Wait and retry, or switch to `mode=simple`                                                            |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference">
    Full endpoint documentation with request/response schemas.
  </Card>

  <Card title="SDK Quickstart" icon="rocket" href="/intro/quickstart">
    Get your first insight in under 5 minutes.
  </Card>

  <Card title="Claude Code Skill" icon="terminal" href="/features/claude-code-skill">
    Use Greenflash directly from your coding agent.
  </Card>

  <Card title="Business Events" icon="chart-line" href="/features/events">
    Link conversations to real business outcomes.
  </Card>
</CardGroup>