# 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](/clearfeed-help-center/integrations/task-and-ticketing-systems.md).
{% 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](/clearfeed-help-center/sources/manage-request-channels.md)
   * **(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](/clearfeed-help-center/clearfeed-helpdesk/workflows.md)

### 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](/clearfeed-help-center/account-setup/developer-settings.md)

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clearfeed.ai/clearfeed-help-center/how-it-works/creating-or-linking-tickets/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.