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)

List Tickets

Retrieve growth tickets with filtering and pagination.

Endpoint

GET /v1/tickets

Query Parameters

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

{
  "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)

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)

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

GET /v1/tickets/{ticket_id}

Response

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

Example

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

PATCH /v1/tickets/{ticket_id}

Request Body

{
  "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

Response

{
  "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)

# 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

POST /v1/tickets/bulk-update

Request Body

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

Response

{
  "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

POST /v1/tickets/{ticket_id}/dismiss

Request Body

{
  "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

{
  "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

GET /v1/tickets/stats

Query Parameters

Response

{
  "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)

# 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

POST /v1/tickets/export

Request Body

{
  "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

{
  "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)

# 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

{
  "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

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

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

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:

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:

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:

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 - Generate reports that create tickets
• ICP Analysis - Understand how tickets are generated
• API Authentication - Authentication and rate limits