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

# FunnelFox API reference

> Complete FunnelFox API docs: endpoints, authentication, request examples, and response formats. Build custom integrations with your funnels.

The FunnelFox API provides read access to your funnel data, enabling you to
retrieve information about funnels, user profiles, sessions, subscriptions,
and products. Use it to build custom dashboards, sync data with external
systems, or create detailed reports.

<Warning>This doc covers the **FunnelFox API** only. If you’re using the **FunnelFox Billing API**, go to the [Billing API section](/develop/api-billing).</Warning>

## Base URL

All API requests should be made to:

```
https://api.funnelfox.io/public/v1
```

## Authentication

Every API request requires authentication using your project's secret key
via the `Fox-Secret` header.

```bash theme={null}
curl https://api.funnelfox.io/public/v1/funnels \
  -H "Fox-Secret: secret_your_key_here"
```

<Info>
  This is the same secret key used for webhooks. Never expose
  it in client-side code or public repositories. Keep it secure on your server.
</Info>

## Quick Start

<Steps>
  <Step title="Get Your Secret Key">
    Find your Fox-Secret in [Project Settings](/dashboard/settings)
  </Step>

  <Step title="Make Your First Request">
    Test the API with a simple funnels list request:

    ```bash theme={null}
    curl https://api.funnelfox.io/public/v1/funnels \
      -H "Fox-Secret: secret_your_key"
    ```
  </Step>

  <Step title="Parse the Response">
    Handle the JSON response with pagination metadata
  </Step>

  <Step title="Build Your Integration">
    Use the data to power your analytics, reporting, or automation
  </Step>
</Steps>

## Available Endpoints

The API provides read access to core FunnelFox data, plus an endpoint to
anonymize profiles:

<CardGroup cols={2}>
  <Card title="Funnels" icon="route">
    * `GET /funnels` - List all funnels
    * `GET /funnels/{id}` - Get funnel details

    Monitor funnel performance and configuration
  </Card>

  <Card title="Profiles & Sessions" icon="user">
    * `GET /profiles/{id}` - Get user profile
    * `POST /profiles/anonymize` - Anonymize profiles (GDPR erasure)
    * `GET /sessions/{id}` - Get session data
    * `GET /sessions/{id}/replies` - Get form responses

    Track user journeys and collected data
  </Card>

  <Card title="Subscriptions" icon="credit-card">
    * `GET /subscriptions` - List subscriptions
    * `GET /subscriptions/{id}` - Get subscription details

    Monitor recurring revenue and subscription states
  </Card>

  <Card title="Products" icon="box">
    * `GET /products` - List all products
    * `GET /products/{id}` - Get product details

    Access your product catalog data
  </Card>
</CardGroup>

## Making Requests

### Request Headers

All requests must include:

| Header         | Required | Description                                 |
| -------------- | -------- | ------------------------------------------- |
| `Fox-Secret`   | Yes      | Your project's secret key                   |
| `Content-Type` | No       | Set to `application/json` for POST requests |

### Example Request

```javascript theme={null}
// Node.js with fetch
const response = await fetch('https://api.funnelfox.io/public/v1/funnels', {
  headers: {
    'Fox-Secret': process.env.FUNNELFOX_SECRET
  }
});

const data = await response.json();
console.log(`Found ${data.data.length} funnels`);
```

## Response Format

All successful responses follow this structure:

```json theme={null}
{
  "data": [...],  // Array of requested resources
  "pagination": {
    "cursor": "abc123",  // Use for next page
    "has_more": true     // More results available
  }
}
```

### Pagination

The API uses cursor-based pagination for list endpoints. The cursor represents
the ID of the last item in the current page.

```bash theme={null}
# First page
GET /funnels?limit=20

# Next page using cursor from previous response
GET /funnels?limit=20&cursor=abc123
```

**Pagination parameters:**

* `limit` - Number of items per page (1-100, default: 20)
* `cursor` - ID of the last item from previous page

```javascript theme={null}
// Paginating through all funnels
async function getAllFunnels() {
  const funnels = [];
  let cursor = null;
  
  do {
    const url = new URL('https://api.funnelfox.io/public/v1/funnels');
    url.searchParams.set('limit', '50');
    if (cursor) url.searchParams.set('cursor', cursor);
    
    const response = await fetch(url, {
      headers: { 'Fox-Secret': SECRET }
    });
    
    const data = await response.json();
    funnels.push(...data.data);
    
    cursor = data.pagination.has_more ? data.pagination.cursor : null;
  } while (cursor);
  
  return funnels;
}
```

## Error Handling

The API returns standard HTTP status codes and JSON error messages:

### Error Response Format

```json theme={null}
{
  "message": "Description of the error"
}
```

## Filtering & Querying

Many endpoints support filtering to narrow down results:

### Funnel Filters

```bash theme={null}
# Filter by title
GET /funnels?filter[title]=welcome

# Filter by alias
GET /funnels?filter[alias]=onboarding

# Filter by type
GET /funnels?filter[type]=cancellation

# Include deleted funnels
GET /funnels?filter[deleted]=true

# Combine filters
GET /funnels?filter[type]=default&filter[title]=pricing&limit=10
```

### Subscription Filters

```bash theme={null}
# Filter by status
GET /subscriptions?filter[status]=active

# Filter by product
GET /subscriptions?filter[product_id]=prod_123

# Filter by date range (if supported)
GET /subscriptions?filter[created_after]=2024-01-01
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized errors">
    * Verify your Fox-Secret is correct
    * Check you're using the header name `Fox-Secret` (case-sensitive)
    * Ensure the secret hasn't been regenerated in Project Settings
  </Accordion>

  <Accordion title="Empty data arrays">
    * Check your filters aren't too restrictive
    * Verify the resources exist in your project
    * Ensure you're using the correct IDs
  </Accordion>

  <Accordion title="Pagination not working">
    * Use the exact cursor value from the previous response
    * Don't modify or decode the cursor
    * Check `has_more` before requesting next page
  </Accordion>

  <Accordion title="404 Not Found">
    * Verify the endpoint URL is correct
    * Check the resource ID exists
    * Ensure you're using the v1 API path
  </Accordion>
</AccordionGroup>

## What's Next

* \[API Reference]\(/api-reference/list-funnels - Detailed endpoint documentation
* [Webhooks](/develop/webhooks) - Real-time event notifications
* [Project Settings](/dashboard/settings) - Manage your API credentials