# Aufgaben-API

Aufgaben sind die To-dos und Nachverfolgungen, die mit Ihrem Konto verknüpft sind – optional verbunden mit einem Kontakt, einem Deal oder einer Kampagne. Sie durchlaufen die **Phasen** Ihres Aufgaben-Boards (Ihre Kanban-Spalten) und besitzen einen **Typ** sowie eine **Priorität**. Dieser Leitfaden beschreibt deren Verwaltung über die API.

- **Basis-URL** — `https://api.youraiconnector.com/v1`
- **Authentifizierung** — Ihr API-Schlüssel (siehe [Authentifizierung](authentication.md))
- **Fehler & Paginierung** — siehe [Fehler & Paginierung](errors-and-pagination.md)

Alle nachstehenden Beispiele zeigen die `?apiKey=`-Abfrageform in cURL und den `X-API-Key`-Header in JavaScript und Python – beides funktioniert an jedem Endpunkt.

---

## Das Aufgaben-Objekt

```json
{
  "id": "tsk_abc123",
  "title": "Call Jane about her quote",
  "description": "She asked for pricing on the annual plan.",
  "type": "to_do",
  "priority": "high",
  "stage": "stage-1",
  "due_date": "2026-06-15T09:00:00.000Z",
  "remind_before_minutes": 15,
  "contact": "contacts/uid_whatsapp_15551234567",
  "campaign": "campaigns/abc123",
  "tags": ["sales"],
  "notes": "",
  "source": "api"
}
```

- **`type`** — `to_do`, `faq_update` oder Ihre konfigurierten Aufgabentypen (siehe [Aufgabentypen auflisten](#list-task-types)).
- **`priority`** — `none`, `low`, `normal`, `high` oder `urgent`.
- **`stage`** — die ID einer Phase auf Ihrem Aufgabenboard (siehe [Aufgabenphasen auflisten](#list-task-stages)). Wenn dies beim Erstellen weggelassen wird, landet die Aufgabe in Ihrer ersten Phase.
- **`remind_before_minutes`** — wie viele Minuten vor `due_date` eine Erinnerung gesendet werden soll. `0` bedeutet zum Fälligkeitszeitpunkt; lassen Sie es weg oder senden Sie `null` für keine Erinnerung. Muss eine ganze Zahl von `0` bis `1440` (1 Tag) sein — alles, was größer ist, wird abgelehnt. Die Erinnerung benötigt ein `due_date`, um ausgelöst zu werden, und eine Terminverschiebung der Aufgabe verschiebt die Erinnerung mit.

---

## Aufgabe erstellen

`POST /tasks` — nur `title` ist erforderlich.

::: note
**Hinweis:** `due_date` akzeptiert einen ISO 8601-Zeitstempel, einschließlich einer Tageszeit. Kombinieren Sie dies mit `remind_before_minutes`, damit die Erinnerung gemäß Ihren **Aufgaben**-Benachrichtigungseinstellungen zugestellt wird. `contact_id`, `deal_id` und `campaign_id` verknüpfen die Aufgabe mit diesen Datensätzen. `assigned_to` ist die Benutzer-ID eines Teammitglieds.
:::


> **Richtiges `assigned_to`.** Es sollte die Benutzer-ID des Kontoinhabers oder eines aktiven Teammitglieds auf demselben Konto sein. Dieser Endpunkt überprüft dies derzeit nicht, daher wird eine ID, die niemandem gehört, akzeptiert und genau so gespeichert, wie Sie sie gesendet haben – Sie erhalten trotzdem eine `201`. Kopieren Sie die ID, anstatt sie abzutippen: Diese IDs mischen `l` mit `L` und den Buchstaben `O` mit der Ziffer `0`, und ein falsches Zeichen reicht bereits aus. Um zu überprüfen, was Sie tatsächlich gesendet haben, öffnen Sie die Aufgabe im Dashboard: Das Feld **Bearbeiter** im Aufgabendatensatz zeigt die rohe ID an, wenn sie zu niemandem passt, und die Auswahl für den Bearbeiter unter **Aufgabe bearbeiten** zeigt **Nicht zugewiesen** an.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call Jane about her quote",
    "priority": "high",
    "due_date": "2026-06-15T09:00:00.000Z",
    "contact_id": "uid_whatsapp_15551234567",
    "tags": ["sales"]
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Call Jane about her quote",
    priority: "high",
    due_date: "2026-06-15T09:00:00.000Z",
    contact_id: "uid_whatsapp_15551234567",
    tags: ["sales"],
  }),
});
const data = await res.json();
console.log(data.task_id);
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "title": "Call Jane about her quote",
        "priority": "high",
        "due_date": "2026-06-15T09:00:00.000Z",
        "contact_id": "uid_whatsapp_15551234567",
        "tags": ["sales"],
    },
)
print(res.json()["task_id"])
```

**Antwort** (`201`)

```json
{ "success": true, "task_id": "tsk_abc123", "task": { "title": "Call Jane about her quote", "...": "..." } }
```

---

## Aufgaben auflisten

`GET /tasks` — gibt die Aufgaben für Ihr Konto zurück, mit optionalen Filtern.

**Abfrageparameter** (alle optional): `stage`, `priority`, `contact_id`, `deal_id`, `assigned_to`, `due_before`, `due_after` (ISO-Zeitstempel).

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/tasks?apiKey=YOUR_API_KEY&stage=stage-1&priority=high"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks?stage=stage-1&priority=high", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { tasks } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/tasks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-1", "priority": "high"},
)
tasks = res.json()["tasks"]
```

**Antwort** (`200`)

```json
{ "success": true, "tasks": [{ "id": "tsk_abc123", "title": "Call Jane about her quote", "...": "..." }] }
```

---

## Aufgaben suchen

`POST /tasks/search` — Volltextsuche in Titel und Beschreibung, mit denselben optionalen Filtern wie bei der Auflistung.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/search?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "quote", "priority": "high" }'
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/search", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ query: "quote", priority: "high" }),
});
```

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/tasks/search",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"query": "quote", "priority": "high"},
)
```

---

## Eine Aufgabe abrufen

`GET /tasks/{taskId}`

```bash
curl "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

Eine Aufgabe, die nicht in Ihrem Konto existiert, gibt `404` zurück.

---

## Eine Aufgabe aktualisieren

`PUT /tasks/{taskId}` — senden Sie nur die Felder, die Sie ändern möchten (`title`, `description`, `type`, `priority`, `stage`, `due_date`, `remind_before_minutes`, `contact_id`, `deal_id`, `assigned_to`, `tags`, `notes`).

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent", "notes": "Left a voicemail." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ priority: "urgent", notes: "Left a voicemail." }),
});
```

```python
requests.put(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"priority": "urgent", "notes": "Left a voicemail."},
)
```

---

## Eine Aufgabe abschließen

`POST /tasks/{taskId}/complete` — verschiebt die Aufgabe in die Phase „Abgeschlossen“ Ihres Boards. Ein optionales Feld `notes` protokolliert eine Abschlussnotiz.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Closed — customer signed up." }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ notes: "Closed — customer signed up." }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/tsk_abc123/complete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"notes": "Closed — customer signed up."},
)
```

---

## Verschieben & neu anordnen (Kanban)

**Verschieben einer Aufgabe in eine andere Phase** — `POST /tasks/{taskId}/move` mit `new_stage_id` (der Zielphase) und `new_position` (dem nullbasierten Slot innerhalb dieser Phase; erforderlich, muss eine nicht-negative Ganzzahl sein):

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-2", "new_position": 0 }'
```

**Neuordnen von Aufgaben innerhalb einer Phase** — `POST /tasks/reorder` mit `stage_id` und den Aufgaben-IDs in ihrer neuen Reihenfolge:

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"] }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/reorder", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ stage_id: "stage-1", ordered_task_ids: ["tsk_3", "tsk_1", "tsk_2"] }),
});
```

```python
requests.post(
    "https://api.youraiconnector.com/v1/tasks/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"stage_id": "stage-1", "ordered_task_ids": ["tsk_3", "tsk_1", "tsk_2"]},
)
```

---

## Aufgaben für einen Kontakt

`GET /tasks/contact/{contactId}` — jede Aufgabe ist mit einem Kontakt verknüpft.

```bash
curl "https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567?apiKey=YOUR_API_KEY"
```

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", { headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
res = requests.get("https://api.youraiconnector.com/v1/tasks/contact/uid_whatsapp_15551234567", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## Konfiguration des Aufgaben-Boards

### Auflisten der Aufgabenphasen

`GET /tasks/stages` — die Spalten Ihres Boards in der entsprechenden Reihenfolge. Verwenden Sie eine Phasen-`id` als `stage`-Feld beim Erstellen oder Verschieben von Aufgaben.

```bash
curl "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY"
```

```json
{ "success": true, "stages": [{ "id": "stage-1", "name": "To Do", "is_completed_stage": false }, { "id": "stage-done", "name": "Done", "is_completed_stage": true }] }
```

### Aktualisieren der Aufgabenphasen

`PUT /tasks/stages` — Ersetzen der Phasenkonfiguration Ihres Boards. Senden Sie das vollständige sortierte `stages`-Array.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/tasks/stages?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stages": [
    { "id": "stage-1", "name": "To Do", "is_completed_stage": false },
    { "id": "stage-2", "name": "In Progress", "is_completed_stage": false },
    { "id": "stage-done", "name": "Done", "is_completed_stage": true }
  ] }'
```

### Auflisten der Aufgabentypen

`GET /tasks/types` — die in Ihrem Konto konfigurierten Aufgabentypen (verwendet als `type`-Feld).

```bash
curl "https://api.youraiconnector.com/v1/tasks/types?apiKey=YOUR_API_KEY"
```

---

## Genehmigen eines FAQ-Vorschlags

Wenn der KI-Bot eine neue FAQ vorschlägt, erstellt er eine Aufgabe vom Typ `faq_update`. `POST /tasks/{taskId}/approve-faq` wandelt diesen Vorschlag in eine echte FAQ in der Wissensdatenbank des KI-Agenten um, der ihn erstellt hat, und schließt die Aufgabe ab. Sie können die Frage/Antwort im Textkörper überschreiben.

Fügen Sie `"send_follow_up": true` hinzu, damit die KI die Antwort auch sofort an den mit der Aufgabe verknüpften Kontakt sendet, als natürliche Nachricht in diesem Chat (dasselbe, was der Schalter **Antwort jetzt an den Kontakt senden** in der App bewirkt). Die Antwort wird über den KI-Agenten gesendet, der diesen Kontakt bearbeitet.

```bash
curl -X POST "https://api.youraiconnector.com/v1/tasks/tsk_faq99/approve-faq?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Do you offer refunds?", "answer": "Yes, within 30 days.", "send_follow_up": true }'
```

```json
{ "success": true, "faq_id": "faq_xyz", "task_id": "tsk_faq99", "follow_up_status": "published" }
```

`follow_up_status` teilt Ihnen mit, was mit der Nachricht passiert ist: `not_requested` (Flag nicht gesetzt), `published` (gesendet), `queued` (der Bot war gerade dabei, diesem Kontakt zu antworten; die Antwort wird gesendet, sobald er fertig ist), `skipped_no_contact` (die Aufgabe hat keinen verknüpften Kontakt), `skipped_no_campaign` (kein Agent oder keine Kampagne konnte für diesen Kontakt antworten) oder `skipped_error`. Das FAQ wird in jedem Fall erstellt.

Siehe die [FAQs-API](faqs.md), um die resultierende FAQ zu verwalten.

---

## Löschen einer Aufgabe

`DELETE /tasks/{taskId}`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/tasks/tsk_abc123?apiKey=YOUR_API_KEY"
```

```javascript
await fetch("https://api.youraiconnector.com/v1/tasks/tsk_abc123", { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } });
```

```python
requests.delete("https://api.youraiconnector.com/v1/tasks/tsk_abc123", headers={"X-API-Key": "YOUR_API_KEY"})
```

---

## Nächste Schritte

- [Kontakte-API](contacts.md) — Verknüpfen Sie Aufgaben mit dem richtigen Kontakt
- [Webhooks-API](webhooks.md) — Lassen Sie sich über `Task Created`, `Task Updated` und `Task Completed` benachrichtigen
- [API-Referenz](reference.md) — Der vollständige interaktive Endpunkt-Explorer