# API

ClearFeed provides REST API endpoints to create and manage tickets programmatically. This allows you to integrate ClearFeed ticketing into your existing tools, workflows, and automation systems.

{% hint style="info" %}
**ClearFeed Tickets Only:** This method is only available for **ClearFeed's native ticketing system**. For external ticketing systems (Zendesk, Jira, etc.), use their native APIs or refer to [integration-specific documentation](https://docs.clearfeed.ai/clearfeed-help-center/integrations/task-and-ticketing-systems).
{% endhint %}

## When to Use the API

Use the ClearFeed API to create tickets when:

* **Integrating with internal tools** - Connect your custom applications to ClearFeed
* **Automating ticket creation** - Create tickets from monitoring systems, webhooks, or scheduled jobs
* **Bulk operations** - Create or update multiple tickets programmatically
* **Custom workflows** - Build custom ticketing flows for your specific needs
* **Third-party integrations** - Connect services that don't have native ClearFeed integration

## Setup API Collection

Before using the API, you need to create an **API Collection** to manage API-based tickets.

### Step 1: Create API Collection

1. Go to **Collections** → Click **Add New Collection**
2. Select **API Collection**
3. Configure the Collection settings:
   * **Name** - Give your API Collection a descriptive name
   * **Add Responders** - Select users who will respond to these tickets
   * **Select Request Channel** - Choose the Slack channel where API tickets will be posted
     * For private channels, follow the [channel management guide](https://docs.clearfeed.ai/clearfeed-help-center/sources/manage-request-channels)
   * **(Optional) Associate Triage Channel** - Link or create a triage channel for team visibility
     * Learn more: [Triage Channel Setup](https://github.com/clearfeed/new-docs/blob/main/helpdesk-concepts/triage-channel.md)
4. **Enable Workflows** (Optional) - Set up alerts for unattended tickets
   * Learn more: [Workflows Guide](https://docs.clearfeed.ai/clearfeed-help-center/clearfeed-helpdesk/workflows)

### Step 2: Get API Credentials

1. Navigate to **Settings → Developer Settings**
2. Generate or copy your **API Key**
3. Store the API key securely - you'll need it for API requests **Learn More:** [Developer Settings](https://docs.clearfeed.ai/clearfeed-help-center/account-setup/developer-settings)

## Creating Tickets via API

### API Endpoint

Use the **Create Request API** endpoint to create new tickets:

```
POST https://api.clearfeed.ai/v1/requests
```

**API Documentation:** [Create Request API Reference](https://docs.clearfeed.ai/api/reference/api-reference/requests#create-request)

### Request Format

**Headers:**

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

**Body:**

```json
{
  "collection_id": "col_abc123",
  "title": "API ticket title",
  "description": "Detailed description of the issue",
  "priority": "high",
  "requester_email": "customer@example.com",
  "custom_fields": {
    "environment": "production",
    "severity": "critical"
  }
}
```

**Required Fields:**

* `collection_id` - The ID of your API Collection
* `title` - Ticket title/subject
* `description` - Detailed description of the issue

**Optional Fields:**

* `priority` - Ticket priority (low, medium, high, urgent)
* `requester_email` - Email of the person requesting support
* `assignee_id` - User ID to assign the ticket to
* `custom_fields` - Additional metadata as key-value pairs
* `tags` - Array of tags for categorization

### Example: Create Ticket with cURL

```bash
curl -X POST https://api.clearfeed.ai/v1/requests \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "col_abc123",
    "title": "Production API Error - 500 responses",
    "description": "Users are experiencing 500 errors when accessing the /api/orders endpoint. Started approximately 30 minutes ago.",
    "priority": "urgent",
    "requester_email": "ops@example.com",
    "custom_fields": {
      "environment": "production",
      "service": "orders-api",
      "error_rate": "25%"
    }
  }'
```

### Example: Create Ticket with Python

```python
import requests

url = "https://api.clearfeed.ai/v1/requests"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "collection_id": "col_abc123",
    "title": "Production API Error - 500 responses",
    "description": "Users are experiencing 500 errors when accessing the /api/orders endpoint.",
    "priority": "urgent",
    "requester_email": "ops@example.com",
    "custom_fields": {
        "environment": "production",
        "service": "orders-api",
        "error_rate": "25%"
    }
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
```

### Response

Successful ticket creation returns:

```json
{
  "id": "req_xyz789",
  "ticket_id": "CF-12345",
  "collection_id": "col_abc123",
  "title": "Production API Error - 500 responses",
  "status": "open",
  "priority": "urgent",
  "created_at": "2025-01-15T10:30:00Z",
  "slack_thread_url": "https://yourworkspace.slack.com/archives/C123/p1234567890"
}
```

## What Happens After Creating a Ticket

Once you create a ticket via API:

1. **Ticket is posted to Slack** - A message appears in the configured Request Channel
2. **Team notification** - Responders receive Slack notifications
3. **Ticket ID assigned** - A unique ClearFeed ticket ID is generated (e.g., CF-12345)
4. **Tracking begins** - The ticket is tracked in the ClearFeed system
5. **Team can respond** - Responders reply in the Slack thread to manage the ticket

## Managing Tickets via API

Beyond creating tickets, the ClearFeed API supports:

* **Update tickets** - Modify status, priority, assignee
* **Get ticket details** - Retrieve ticket information
* **Add comments** - Post updates to tickets programmatically
* **Search tickets** - Query tickets by various criteria
* **Close tickets** - Mark tickets as resolved

**Full API Documentation:** [ClearFeed API Reference](https://docs.clearfeed.ai/api/reference)

## FAQs

1. **How do I get my API credentials?**\
   **Answer:** Navigate to **Settings → Developer Settings** in the ClearFeed web app to generate your API key.
2. **Is there a rate limit for API requests?**\
   **Answer:** Yes, API rate limits apply. Refer to the [API Documentation](https://docs.clearfeed.ai/api/reference) for current rate limits and best practices.
3. **Can I create tickets in multiple Collections using the same API key?**\
   **Answer:** Yes, the API key is workspace-level. Specify different `collection_id` values to create tickets in different Collections.
4. **How do I specify who the ticket is assigned to?**\
   **Answer:** Include the `assignee_id` field in your API request with the user's ID. You can get user IDs from the ClearFeed API or web app
5. **What happens if the API request fails?**\
   **Answer:** The API returns appropriate HTTP status codes and error messages. Implement error handling in your code to retry or log failures.
6. **Can I update an existing ticket via API?**\
   **Answer:** Yes, use the Update Request endpoint. See [API Documentation](https://docs.clearfeed.ai/api/reference) for details.
7. **Are webhooks available to receive ticket updates?**\
   **Answer:** Yes, ClearFeed supports webhooks for ticket events. Configure them in **Settings → Developer Settings → Webhooks**.