# Tasks API

Uppgifter är att-göra-punkter och uppföljningar kopplade till ditt konto — valfritt länkade till en kontakt, affär eller kampanj. De rör sig genom **stadierna** på din uppgiftstavla (dina kanban-kolumner) och har en **typ** och **prioritet**. Den här guiden täcker hur du hanterar dem via API:et.

- **Bas-URL** — `https://api.youraiconnector.com/v1`
- **Autentisering** — din API-nyckel (se [Autentisering](authentication.md))
- **Fel och sidnumrering** — se [Fel och sidnumrering](errors-and-pagination.md)

Alla exempel nedan visar frågeformuläret `?apiKey=` i cURL och headern `X-API-Key` i JavaScript och Python — båda fungerar på alla slutpunkter.

---

## Uppgiftsobjektet

```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` eller dina konfigurerade uppgiftstyper (se [Lista uppgiftstyper](#list-task-types)).
- **`priority`** — `none`, `low`, `normal`, `high` eller `urgent`.
- **`stage`** — id för ett stadium på din uppgiftstavla (se [Lista uppgiftsstadier](#list-task-stages)). Om det utelämnas vid skapande hamnar uppgiften i ditt första stadium.
- **`remind_before_minutes`** — hur många minuter före `due_date` som en påminnelse ska skickas. `0` innebär vid förfallotiden; utelämna det eller skicka `null` för ingen påminnelse. Måste vara ett heltal från `0` till `1440` (1 dag) — allt större avvisas. Påminnelsen kräver en `due_date` för att aktiveras, och omplanering av uppgiften flyttar påminnelsen med den.

---

## Skapa en uppgift

`POST /tasks` — endast `title` krävs.

::: note
**Obs:** `due_date` accepterar en ISO 8601-tidsstämpel, inklusive tid på dygnet. Kombinera med `remind_before_minutes` för att få påminnelsen levererad enligt dina aviseringsinställningar för **Uppgifter**. `contact_id`, `deal_id` och `campaign_id` länkar uppgiften till dessa poster. `assigned_to` är en teammedlems användar-id.
:::


> **Att få `assigned_to` rätt.** Det bör vara användar-id:t för kontoinnehavaren eller en aktiv teammedlem på samma konto. Denna slutpunkt kontrollerar för närvarande inte detta, så ett id som inte tillhör någon accepteras och lagras exakt som du skickade det — du får fortfarande en `201`. Kopiera id:t istället för att skriva in det på nytt: dessa id:n blandar `l` med `L` och bokstaven `O` med siffran `0`, och ett felaktigt tecken räcker. För att kontrollera vad du faktiskt skickade, öppna uppgiften i instrumentpanelen: fältet **Tilldelad** på uppgiftsposten faller tillbaka på att visa det råa id:t när det inte matchar någon, och väljaren för tilldelad person i **Redigera uppgift** visar **Ej tilldelad**.

**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"])
```

**Svar** (`201`)

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

---

## Lista uppgifter

`GET /tasks` — returnerar uppgifterna för ditt konto, med valfria filter.

**Frågeparametrar** (alla valfria): `stage`, `priority`, `contact_id`, `deal_id`, `assigned_to`, `due_before`, `due_after` (ISO-tidsstämplar).

**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"]
```

**Svar** (`200`)

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

---

## Sök uppgifter

`POST /tasks/search` — fulltextsökning i titel och beskrivning, med samma valfria filter som vid listning.

```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"},
)
```

---

## Hämta en uppgift

`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"})
```

En uppgift som inte finns på ditt konto returnerar `404`.

---

## Uppdatera en uppgift

`PUT /tasks/{taskId}` — skicka endast de fält du vill ändra (`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."},
)
```

---

## Slutför en uppgift

`POST /tasks/{taskId}/complete` — flyttar uppgiften till din tavlas slutförda-stadium. Ett valfritt `notes`-fält sparar en avslutande anteckning.

```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."},
)
```

---

## Flytta & sortera om (kanban)

**Flytta en uppgift till ett annat stadium** — `POST /tasks/{taskId}/move` med `new_stage_id` (målstadiet) och `new_position` (den nollbaserade platsen inom det stadiet; obligatorisk, måste vara ett icke-negativt heltal):

```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 }'
```

**Ändra ordning på uppgifter inom ett stadium** — `POST /tasks/reorder` med `stage_id` och uppgifts-ID:n i deras nya ordning:

```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"]},
)
```

---

## Uppgifter för en kontakt

`GET /tasks/contact/{contactId}` — varje uppgift kopplad till en kontakt.

```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 av uppgiftstavla

### Lista uppgiftstadier

`GET /tasks/stages` — din tavlas kolumner, i ordning. Använd ett stadium `id` som `stage`-fält när du skapar eller flyttar uppgifter.

```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 }] }
```

### Uppdatera uppgiftstadier

`PUT /tasks/stages` — ersätt din tavlas stadiumkonfiguration. Skicka hela den sorterade `stages`-arrayen.

```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 }
  ] }'
```

### Lista uppgiftstyper

`GET /tasks/types` — de uppgiftstyper som är konfigurerade på ditt konto (används som `type`-fält).

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

---

## Godkänn ett förslag till FAQ

När AI-boten föreslår en ny FAQ skapar den en uppgift av typen `faq_update`. `POST /tasks/{taskId}/approve-faq` omvandlar förslaget till en riktig FAQ i kunskapsbasen för den AI-agent som skapade det och slutför uppgiften. Du kan skriva över frågan/svaret i brödtexten.

Lägg till `"send_follow_up": true` för att även låta AI:n skicka svaret till uppgiftens länkade kontakt direkt, som ett naturligt meddelande i den chatten (samma sak som reglaget **Skicka svaret till kontakten nu** gör i appen). Svaret skickas via den AI-agent som hanterar kontakten.

```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` talar om för dig vad som hände med meddelandet: `not_requested` (flagga ej satt), `published` (skickat), `queued` (boten höll på att svara kontakten, svaret skickas så snart den är klar), `skipped_no_contact` (uppgiften har ingen länkad kontakt), `skipped_no_campaign` (ingen agent eller kampanj kunde svara för den kontakten) eller `skipped_error`. FAQ:n skapas i samtliga fall.

Se [FAQs API](faqs.md) för att hantera den resulterande FAQ:n.

---

## Ta bort en uppgift

`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ästa steg

- [Contacts API](contacts.md) — koppla uppgifter till rätt kontakt
- [Webhooks API](webhooks.md) — få aviseringar om `Task Created`, `Task Updated` och `Task Completed`
- [API-referens](reference.md) — den fullständiga interaktiva utforskaren för slutpunkter