<!-- Cogny documentation. Canonical page: https://cogny.com/docs/growth-tickets-api-reference -->

# Growth Tickets API Reference

Complete API reference for accessing and managing AI-generated growth tickets, including filtering, prioritization, and status management.

**Author:** Cogny Team  
**Published:** 2025-02-07  
**Updated:** 2026-10-05  
**Canonical:** https://cogny.com/docs/growth-tickets-api-reference

## Overview

The Growth Tickets API provides programmatic access to AI-generated growth recommendations and action items. Tickets are automatically generated based on data analysis and can be filtered, prioritized, and integrated into your project management workflows.

**Base URL:** `https://api.cogny.com/v1/tickets`

**Authentication:** Bearer token (see [API Authentication](/docs/api-overview-authentication))

## List Tickets

Retrieve growth tickets with filtering and pagination.

### Endpoint

```http
GET /v1/tickets
```

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `warehouse_id` | string | Filter by warehouse ID |
| `status` | string | Filter by status (open, in_progress, completed, dismissed) |
| `priority` | string | Filter by priority (critical, high, medium, low) |
| `category` | string | Filter by category (see categories below) |
| `created_after` | string | ISO 8601 timestamp |
| `created_before` | string | ISO 8601 timestamp |
| `updated_after` | string | ISO 8601 timestamp |
| `sort` | string | Sort field (e.g., -priority, created_at) |
| `limit` | integer | Items per page (max: 100) |
| `cursor` | string | Pagination cursor |

### Categories

- `conversion_optimization` - Improve conversion rates
- `funnel_optimization` - Reduce funnel drop-off
- `user_engagement` - Increase engagement metrics
- `revenue_growth` - Boost revenue and AOV
- `retention` - Improve user retention
- `acquisition` - Optimize user acquisition
- `technical_performance` - Fix technical issues
- `data_quality` - Improve data collection

### Response

```json
{
  "success": true,
  "data": [
    {
      "id": "tkt_abc123",
      "warehouse_id": "wh_123abc",
      "title": "Optimize Mobile Checkout Flow",
      "description": "Mobile users abandon cart at 2x desktop rate. Cart abandonment peaks at payment step (41%).",
      "category": "conversion_optimization",
      "priority": "high",
      "status": "open",
      "estimated_impact": {
        "metric": "conversion_rate",
        "current_value": 0.027,
        "projected_value": 0.034,
        "increase_percentage": 25.9,
        "confidence": 0.85
      },
      "effort": "medium",
      "action_items": [
        {
          "title": "Implement one-click checkout for returning users",
          "description": "Add Apple Pay and Google Pay integration",
          "estimated_hours": 16,
          "completed": false
        },
        {
          "title": "Reduce form fields from 12 to 6",
          "description": "Remove redundant fields and auto-fill where possible",
          "estimated_hours": 8,
          "completed": false
        }
      ],
      "supporting_data": {
        "mobile_conversion_rate": 0.027,
        "desktop_conversion_rate": 0.035,
        "cart_abandonment_rate": 0.41,
        "sample_size": 45000
      },
      "related_report_id": "rpt_xyz789",
      "created_at": "2025-02-07T10:30:00Z",
      "updated_at": "2025-02-07T10:30:00Z",
      "url": "https://app.cogny.com/tickets/tkt_abc123"
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6InRrdF9hYmMxMjMifQ",
    "total_count": 23
  }
}
```

### Example Request (cURL)

```bash
curl -X GET "https://api.cogny.com/v1/tickets?warehouse_id=wh_123abc&status=open&priority=high&sort=-priority" \
  -H "Authorization: Bearer sk_live_abc123xyz789"
```

### Example Request (Python)

```python
import requests

API_KEY = "sk_live_abc123xyz789"
BASE_URL = "https://api.cogny.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

params = {
    "warehouse_id": "wh_123abc",
    "status": "open",
    "priority": "high",
    "sort": "-priority",
    "limit": 50
}

response = requests.get(
    f"{BASE_URL}/tickets",
    headers=headers,
    params=params
)

tickets = response.json()["data"]
print(f"Found {len(tickets)} high-priority open tickets")

for ticket in tickets:
    print(f"- [{ticket['priority'].upper()}] {ticket['title']}")
    print(f"  Impact: +{ticket['estimated_impact']['increase_percentage']:.1f}% {ticket['estimated_impact']['metric']}")
```

## Get Ticket

Retrieve detailed information for a specific ticket.

### Endpoint

```http
GET /v1/tickets/{ticket_id}
```

### Response

Same structure as individual ticket in list response, with full details.

### Example

```bash
curl -X GET https://api.cogny.com/v1/tickets/tkt_abc123 \
  -H "Authorization: Bearer sk_live_abc123xyz789"
```

## Update Ticket

Update ticket status, priority, or other fields.

### Endpoint

```http
PATCH /v1/tickets/{ticket_id}
```

### Request Body

```json
{
  "status": "in_progress",
  "priority": "critical",
  "assignee": "user_456",
  "notes": "Started implementation. Targeting completion by end of week.",
  "action_items": [
    {
      "title": "Implement one-click checkout for returning users",
      "completed": true
    },
    {
      "title": "Reduce form fields from 12 to 6",
      "completed": false
    }
  ]
}
```

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | Update status (open, in_progress, completed, dismissed) |
| `priority` | string | Update priority (critical, high, medium, low) |
| `assignee` | string | Assign to user ID |
| `notes` | string | Add notes or comments |
| `action_items` | array | Update action item completion status |

### Response

```json
{
  "success": true,
  "data": {
    "id": "tkt_abc123",
    "status": "in_progress",
    "priority": "critical",
    "assignee": "user_456",
    "notes": "Started implementation. Targeting completion by end of week.",
    "updated_at": "2025-02-07T15:45:00Z"
  }
}
```

### Example (Python)

```python
# Update ticket status
update = {
    "status": "in_progress",
    "assignee": "user_456",
    "notes": "Started implementation"
}

response = requests.patch(
    f"{BASE_URL}/tickets/tkt_abc123",
    headers=headers,
    json=update
)

ticket = response.json()["data"]
print(f"Ticket updated: {ticket['status']}")
```

## Bulk Update Tickets

Update multiple tickets in a single request.

### Endpoint

```http
POST /v1/tickets/bulk-update
```

### Request Body

```json
{
  "ticket_ids": ["tkt_abc123", "tkt_def456", "tkt_ghi789"],
  "updates": {
    "status": "in_progress",
    "assignee": "user_456"
  }
}
```

### Response

```json
{
  "success": true,
  "data": {
    "updated_count": 3,
    "failed_count": 0,
    "updated_ids": ["tkt_abc123", "tkt_def456", "tkt_ghi789"]
  }
}
```

## Dismiss Ticket

Mark a ticket as dismissed with optional reason.

### Endpoint

```http
POST /v1/tickets/{ticket_id}/dismiss
```

### Request Body

```json
{
  "reason": "not_applicable",
  "notes": "Already implemented similar solution in Q4 2024"
}
```

### Dismiss Reasons

- `not_applicable` - Recommendation doesn't apply to business
- `already_implemented` - Solution already in place
- `insufficient_impact` - Expected impact too low to justify effort
- `resource_constraints` - Lack resources to implement
- `other` - Other reason (provide notes)

### Response

```json
{
  "success": true,
  "data": {
    "id": "tkt_abc123",
    "status": "dismissed",
    "dismissed_at": "2025-02-07T16:00:00Z",
    "dismiss_reason": "already_implemented",
    "notes": "Already implemented similar solution in Q4 2024"
  }
}
```

## Get Ticket Statistics

Retrieve aggregated statistics for tickets.

### Endpoint

```http
GET /v1/tickets/stats
```

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `warehouse_id` | string | Filter by warehouse ID |
| `created_after` | string | ISO 8601 timestamp |
| `created_before` | string | ISO 8601 timestamp |

### Response

```json
{
  "success": true,
  "data": {
    "total_tickets": 47,
    "by_status": {
      "open": 23,
      "in_progress": 12,
      "completed": 8,
      "dismissed": 4
    },
    "by_priority": {
      "critical": 5,
      "high": 15,
      "medium": 18,
      "low": 9
    },
    "by_category": {
      "conversion_optimization": 12,
      "funnel_optimization": 8,
      "user_engagement": 7,
      "revenue_growth": 6,
      "retention": 5,
      "acquisition": 4,
      "technical_performance": 3,
      "data_quality": 2
    },
    "estimated_total_impact": {
      "conversion_rate_increase": 0.15,
      "revenue_increase_percentage": 23.5,
      "users_retained": 1250
    },
    "completion_rate": 0.17,
    "average_time_to_complete_days": 14.5
  }
}
```

### Example (Python)

```python
# Get ticket statistics
response = requests.get(
    f"{BASE_URL}/tickets/stats",
    headers=headers,
    params={"warehouse_id": "wh_123abc"}
)

stats = response.json()["data"]

print(f"Total tickets: {stats['total_tickets']}")
print(f"Open: {stats['by_status']['open']}")
print(f"High priority: {stats['by_priority']['high']}")
print(f"Estimated revenue increase: +{stats['estimated_total_impact']['revenue_increase_percentage']:.1f}%")
```

## Export Tickets

Export tickets to various formats for external systems.

### Endpoint

```http
POST /v1/tickets/export
```

### Request Body

```json
{
  "format": "csv",
  "filters": {
    "warehouse_id": "wh_123abc",
    "status": "open",
    "priority": ["critical", "high"]
  },
  "include_fields": [
    "title",
    "description",
    "priority",
    "status",
    "estimated_impact",
    "action_items"
  ]
}
```

### Supported Formats

- `csv` - Comma-separated values
- `json` - JSON format
- `xlsx` - Excel spreadsheet
- `jira` - JIRA import format
- `asana` - Asana import format
- `linear` - Linear import format

### Response

```json
{
  "success": true,
  "data": {
    "export_id": "exp_xyz123",
    "format": "csv",
    "status": "completed",
    "download_url": "https://api.cogny.com/v1/tickets/exports/exp_xyz123/download",
    "expires_at": "2025-02-08T10:30:00Z",
    "ticket_count": 23
  }
}
```

### Example (Python - Export to CSV)

```python
# Export tickets to CSV
export_request = {
    "format": "csv",
    "filters": {
        "warehouse_id": "wh_123abc",
        "status": "open"
    }
}

response = requests.post(
    f"{BASE_URL}/tickets/export",
    headers=headers,
    json=export_request
)

export = response.json()["data"]

# Download the export
download_response = requests.get(
    export["download_url"],
    headers=headers
)

with open("cogny_tickets.csv", "wb") as f:
    f.write(download_response.content)

print(f"Exported {export['ticket_count']} tickets to cogny_tickets.csv")
```

## Webhooks

Subscribe to ticket events via webhooks.

### Event Types

- `ticket.created` - New ticket generated
- `ticket.updated` - Ticket fields updated
- `ticket.status_changed` - Status changed
- `ticket.completed` - Ticket marked as completed
- `ticket.dismissed` - Ticket dismissed

### Webhook Payload

```json
{
  "id": "evt_abc123",
  "type": "ticket.status_changed",
  "created_at": "2025-02-07T10:30:00Z",
  "data": {
    "ticket_id": "tkt_abc123",
    "warehouse_id": "wh_123abc",
    "previous_status": "open",
    "new_status": "in_progress",
    "changed_by": "user_456",
    "ticket": {
      "title": "Optimize Mobile Checkout Flow",
      "priority": "high",
      "category": "conversion_optimization"
    }
  }
}
```

### Configure Webhook

```bash
curl -X POST https://api.cogny.com/v1/webhooks \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/cogny",
    "events": ["ticket.created", "ticket.status_changed"],
    "secret": "whsec_your_webhook_secret"
  }'
```

## Integration Examples

### Sync to JIRA

```python
import requests
from jira import JIRA

# Cogny configuration
COGNY_API_KEY = "sk_live_abc123xyz789"
COGNY_BASE_URL = "https://api.cogny.com/v1"

# JIRA configuration
JIRA_URL = "https://your-domain.atlassian.net"
JIRA_EMAIL = "your-email@example.com"
JIRA_API_TOKEN = "your_jira_token"

cogny_headers = {
    "Authorization": f"Bearer {COGNY_API_KEY}",
    "Content-Type": "application/json"
}

jira = JIRA(server=JIRA_URL, basic_auth=(JIRA_EMAIL, JIRA_API_TOKEN))

def sync_tickets_to_jira(warehouse_id, jira_project_key):
    """Sync open Cogny tickets to JIRA"""

    # Get open tickets from Cogny
    response = requests.get(
        f"{COGNY_BASE_URL}/tickets",
        headers=cogny_headers,
        params={
            "warehouse_id": warehouse_id,
            "status": "open",
            "limit": 100
        }
    )

    tickets = response.json()["data"]

    for ticket in tickets:
        # Map Cogny priority to JIRA
        priority_map = {
            "critical": "Highest",
            "high": "High",
            "medium": "Medium",
            "low": "Low"
        }

        # Create JIRA issue
        issue_dict = {
            'project': {'key': jira_project_key},
            'summary': ticket['title'],
            'description': f"{ticket['description']}\n\n"
                         f"Category: {ticket['category']}\n"
                         f"Estimated Impact: +{ticket['estimated_impact']['increase_percentage']:.1f}%\n"
                         f"Effort: {ticket['effort']}\n\n"
                         f"Source: {ticket['url']}",
            'issuetype': {'name': 'Task'},
            'priority': {'name': priority_map[ticket['priority']]}
        }

        jira_issue = jira.create_issue(fields=issue_dict)

        # Create subtasks for action items
        for action_item in ticket['action_items']:
            subtask_dict = {
                'project': {'key': jira_project_key},
                'summary': action_item['title'],
                'description': action_item['description'],
                'issuetype': {'name': 'Sub-task'},
                'parent': {'key': jira_issue.key}
            }
            jira.create_issue(fields=subtask_dict)

        print(f"Created JIRA issue {jira_issue.key}: {ticket['title']}")

        # Update Cogny ticket with JIRA reference
        requests.patch(
            f"{COGNY_BASE_URL}/tickets/{ticket['id']}",
            headers=cogny_headers,
            json={
                "notes": f"Synced to JIRA: {jira_issue.key}"
            }
        )

# Usage
sync_tickets_to_jira("wh_123abc", "GROWTH")
```

### Slack Notifications

```python
import requests

SLACK_WEBHOOK_URL = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

def notify_high_priority_tickets(warehouse_id):
    """Send Slack notification for high-priority tickets"""

    # Get high-priority tickets
    response = requests.get(
        f"{COGNY_BASE_URL}/tickets",
        headers=cogny_headers,
        params={
            "warehouse_id": warehouse_id,
            "status": "open",
            "priority": "high"
        }
    )

    tickets = response.json()["data"]

    if not tickets:
        return

    # Format Slack message
    blocks = [
        {
            "type": "header",
            "text": {
                "type": "plain_text",
                "text": f"🚀 {len(tickets)} High-Priority Growth Opportunities"
            }
        }
    ]

    for ticket in tickets[:5]:  # Show top 5
        impact = ticket['estimated_impact']
        blocks.append({
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": f"*{ticket['title']}*\n"
                       f"Category: {ticket['category']}\n"
                       f"Impact: +{impact['increase_percentage']:.1f}% {impact['metric']}\n"
                       f"Effort: {ticket['effort']}"
            },
            "accessory": {
                "type": "button",
                "text": {
                    "type": "plain_text",
                    "text": "View Ticket"
                },
                "url": ticket['url']
            }
        })

    # Send to Slack
    requests.post(SLACK_WEBHOOK_URL, json={"blocks": blocks})

# Usage
notify_high_priority_tickets("wh_123abc")
```

## Best Practices

### 1. Prioritize by Impact

Focus on tickets with highest estimated impact:

```python
response = requests.get(
    f"{BASE_URL}/tickets",
    headers=headers,
    params={
        "warehouse_id": "wh_123abc",
        "status": "open",
        "sort": "-estimated_impact.increase_percentage",
        "limit": 10
    }
)

top_tickets = response.json()["data"]
```

### 2. Track Completion

Update ticket status as work progresses:

```python
def update_ticket_progress(ticket_id, completed_action_index):
    """Mark action item as completed"""

    # Get current ticket
    response = requests.get(
        f"{BASE_URL}/tickets/{ticket_id}",
        headers=headers
    )
    ticket = response.json()["data"]

    # Update action items
    action_items = ticket["action_items"]
    action_items[completed_action_index]["completed"] = True

    # Check if all items completed
    all_completed = all(item["completed"] for item in action_items)
    new_status = "completed" if all_completed else "in_progress"

    # Update ticket
    requests.patch(
        f"{BASE_URL}/tickets/{ticket_id}",
        headers=headers,
        json={
            "status": new_status,
            "action_items": action_items
        }
    )
```

### 3. Regular Sync

Sync tickets to your project management system regularly:

```python
import schedule
import time

def sync_job():
    """Regular sync job"""
    sync_tickets_to_jira("wh_123abc", "GROWTH")
    notify_high_priority_tickets("wh_123abc")

# Run every hour
schedule.every().hour.do(sync_job)

while True:
    schedule.run_pending()
    time.sleep(60)
```

## Next Steps

- [Report Builder API](/docs/report-builder-api-reference) - Generate reports that create tickets
- [ICP Analysis](/docs/icp-analysis-technical-overview) - Understand how tickets are generated
- [API Authentication](/docs/api-overview-authentication) - Authentication and rate limits

---

In this section:

- **Growth Tickets API Reference** (this page): https://cogny.com/docs/growth-tickets-api-reference
- Report Builder API Reference: https://cogny.com/docs/report-builder-api-reference
- Cogny API Overview and Authentication: https://cogny.com/docs/api-overview-authentication

Source page: https://cogny.com/docs/growth-tickets-api-reference  
All documentation: https://cogny.com/docs  
Cogny for agents: https://cogny.com/llms.txt