# Aktionen

> Auf Quellen und Regeln einwirken. 12 Tools, mit ihren Parametern und Aufrufbeispielen.

Source: https://piqline.com/de/docs/api/reference/act

Aktions-Tools des Piqline-Agenten. Im Chat verlangt jedes eine Bestätigung. Über die API gilt ein direkter Aufruf mit dem Scope `act` als Bestätigung: Rufen Sie diese Tools erst auf, nachdem die betroffene Person zugestimmt hat.

Jeder Aufruf ist eine `POST`-Anfrage mit dem Schlüssel in `Authorization: Bearer`. Der JSON-Body ist die Eingabe des Tools, und die Antwort hat die Form `{ "tool": "nom", "output": … }`. Die Beispiele enthalten nur die erforderlichen Parameter. Die Parameterbeschreibungen sind die, die die Agenten lesen.

### `subscribeSource`

Abonniert eine neue Quelle. Startet eine echte Erfassung (Lese-Jobs, Plattformkontingente).

`POST https://piqline.com/api/v1/tools/subscribeSource`

Typ: Aktion. Scopes: `act`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `platform` | `instagram \| tiktok \| youtube \| twitter \| x \| threads \| linkedin \| reddit \| …` | Ja |  |
| `target` | `string` | Nein | Handle, URL, mot-clé Marketplace, ou communauté. Une recherche LinkedIn peut s’appuyer sur query. |
| `title` | `string` | Nein |  |
| `facebookKind` | `page \| group \| marketplace` | Nein | Facebook : page publique, groupe public, ou recherche Marketplace. |
| `tiktokKind` | `profile \| live` | Nein | TikTok only. live = /v1/tiktok/user/live probe, not profile posts. |
| `linkedinKind` | `company \| search` | Nein | LinkedIn only. search = recurring public-post search on `query`. |
| `location` | `string` | Nein | Marketplace : ville ou zone. |
| `lat` | `number` | Nein |  |
| `lng` | `number` | Nein |  |
| `radiusKm` | `number` | Nein |  |
| `minPrice` | `number` | Nein |  |
| `maxPrice` | `number` | Nein |  |
| `sortBy` | `string` | Nein |  |
| `condition` | `string` | Nein |  |
| `dateListed` | `string` | Nein |  |
| `categoryId` | `string` | Nein |  |
| `delivery` | `string` | Nein |  |
| `availability` | `string` | Nein |  |
| `datePosted` | `last-hour \| last-day \| last-week \| last-month \| last-year` | Nein | LinkedIn search only. Window of each run, default last-week. |
| `query` | `string` | Nein | Marketplace keyword or LinkedIn search query. |
| `intent` | `string` | Nein | LinkedIn search: the user's ask, kept on the source. |
| `detectionEvent` | `hiring \| funding \| launch \| expansion \| reorg \| open_to_work \| leaving \| interested_comment \| …` | Nein |  |
| `detectionRounds` | `array<pre_seed \| seed \| series_a \| series_b \| series_c \| series_d \| bridge \| extension \| …>` | Nein |  |
| `detectionSectors` | `array<string>` | Nein |  |
| `detectionGeos` | `array<string>` | Nein |  |
| `detectionVocabulary` | `array<string>` | Nein |  |
| `moreQueries` | `array<string>` | Nein | LinkedIn search only. Up to 3 other phrases followed together with `query`, one per job family, each probed by probeLinkedinWatch with at least one relevant post. |
| `maxPosts` | `integer` | Nein | LinkedIn search only. Posts read at most per run: 15, 50, 100 or 200 (default 50). Each post read uses credits; a run reads only posts newer than the last one stored. |
| `detectionAuthors` | `array<recruiter \| founder \| manager>` | Nein | LinkedIn search only. Keep only posts whose author's title reads as one of these roles (recruiter, founder, manager). Empty = every author. |
| `rhythm` | `hourly \| every_6h \| daily \| weekly` | Nein | LinkedIn search only. Run rhythm chosen by the user (hourly, every_6h, daily, weekly). Omit to keep the rhythm suggested by the probe. |
| `investigation` | `object` | Nein | Lot 7: pass the investigation object from probeLinkedinWatch unchanged. |
| `trackItemVariations` | `boolean` | Nein | Marketplace / listing only. True only if the user explicitly asked to follow price, text or presence on the same item (T8). Default false: new items only. |
| `enrichFromUrl` | `boolean` | Nein | Listing / web only. Open each item URL to read the page text. Default false. Each opened page uses credits. Set true only if the user explicitly asked. |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/subscribeSource \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"instagram"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/subscribeSource", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "platform": "instagram"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/subscribeSource",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "platform": "instagram",
    },
)
output = response.json()["output"]
```

### `subscribeSources`

Abonniert mehrere Quellen in einem Aufruf und liefert ein Ergebnis pro Quelle.

`POST https://piqline.com/api/v1/tools/subscribeSources`

Typ: Aktion. Scopes: `act`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `sources` | `array<object>` | Ja |  |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/subscribeSources \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sources":[{"platform":"instagram"}]}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/subscribeSources", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "sources": [
      {
        "platform": "instagram"
      }
    ]
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/subscribeSources",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "sources": [
            {
                "platform": "instagram",
            },
        ],
    },
)
output = response.json()["output"]
```

### `unsubscribeSource`

Beendet das Folgen einer Quelle. Bereits erfasste Items bleiben im Korpus.

`POST https://piqline.com/api/v1/tools/unsubscribeSource`

Typ: Aktion. Scopes: `act`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `sourceId` | `string` | Ja |  |
| `label` | `string` | Nein | Nom lisible de la source (celui de listSources). Obligatoire pour la carte de confirmation. |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/unsubscribeSource \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/unsubscribeSource", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "sourceId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/unsubscribeSource",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "sourceId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
    },
)
output = response.json()["output"]
```

### `setHomeDashboard`

Setzt ein gespeichertes Board als Startseite des Workspace.

`POST https://piqline.com/api/v1/tools/setHomeDashboard`

Typ: Aktion. Scopes: `act`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `dashboardId` | `string` | Ja |  |
| `title` | `string` | Nein | Titre du tableau, pour la carte de confirmation. Jamais l’identifiant seul. |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/setHomeDashboard \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dashboardId":"5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/setHomeDashboard", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "dashboardId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/setHomeDashboard",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "dashboardId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
    },
)
output = response.json()["output"]
```

### `upsertSignalRule`

Erstellt oder aktualisiert eine Persistenz-Signalregel: Sie löst aus, wenn ein Item länger als der Schwellenwert online bleibt.

`POST https://piqline.com/api/v1/tools/upsertSignalRule`

Typ: Aktion. Scopes: `act`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `ruleId` | `string` | Nein |  |
| `thresholdDays` | `integer` | Nein |  |
| `staleGraceDays` | `integer` | Nein |  |
| `itemTypes` | `array<post \| video \| article \| listing \| job_offer>` | Nein |  |
| `enabled` | `boolean` | Nein |  |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/upsertSignalRule \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/upsertSignalRule", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/upsertSignalRule",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={},
)
output = response.json()["output"]
```

### `upsertQuestionRule`

Erstellt oder aktualisiert eine Dauerfrage: ein Satz in einfacher Sprache, den Jev an jedes neue Item der Quellen des Workspace stellt. Der Wahrscheinlichkeitsschwellenwert erzeugt das Signal.

`POST https://piqline.com/api/v1/tools/upsertQuestionRule`

Typ: Aktion. Scopes: `act`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `ruleId` | `string` | Nein |  |
| `question` | `string` | Ja |  |
| `minProbability` | `number` | Nein |  |
| `itemTypes` | `array<post \| video \| article \| listing \| job_offer>` | Nein |  |
| `enabled` | `boolean` | Nein |  |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/upsertQuestionRule \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"texte"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/upsertQuestionRule", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "question": "texte"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/upsertQuestionRule",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "question": "texte",
    },
)
output = response.json()["output"]
```

### `startInvestigation`

Reiht eine Edge-Recherche im Hintergrund für diesen Workspace ein (Owner oder Admin).

`POST https://piqline.com/api/v1/tools/startInvestigation`

Typ: Aktion. Scopes: `act`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `intent` | `string` | Ja | Need in one sentence, from sujets / zones / langues already noted |
| `perimeter` | `object` | Nein | Optional sectors, geos, accounts, seed URLs from the need profile |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/startInvestigation \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intent":"texte"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/startInvestigation", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "intent": "texte"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/startInvestigation",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "intent": "texte",
    },
)
output = response.json()["output"]
```

### `startHunt`

Startet eine Suche: Personen finden, die nachprüfbare Kriterien erfüllen, jedes Kriterium durch eine datierte öffentliche Quelle belegt. Sensible Kriterien werden abgelehnt, es werden keine Kontaktdaten geliefert. Läuft im Hintergrund und verbraucht die Credits des Monats; Owner oder Admin.

`POST https://piqline.com/api/v1/tools/startHunt`

Typ: Aktion. Scopes: `act`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `brief` | `string` | Ja | Who to find, in one or two sentences. |
| `purpose` | `string` | Ja | Why these people are sought, in one sentence. Recorded with the hunt. |
| `criteria` | `array<object>` | Ja |  |
| `target` | `integer` | Nein | How many people to find. |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/startHunt \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brief":"texte","purpose":"texte","criteria":[{"label":"texte"}]}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/startHunt", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "brief": "texte",
    "purpose": "texte",
    "criteria": [
      {
        "label": "texte"
      }
    ]
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/startHunt",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "brief": "texte",
        "purpose": "texte",
        "criteria": [
            {
                "label": "texte",
            },
        ],
    },
)
output = response.json()["output"]
```

### `buildAdAudit`

Rückwirkendes Audit der Kampagnen von 1 bis 6 bereits erfassten Werbetreibenden über N Monate: eine Workspace-Tabelle (Werbetreibender, Monat, neue Anzeigen, Stopps, Bibliotheken, Länder, gelesene Bedarfe, Hochfahren) und die Zahlen einer zitierten Zusammenfassung. Keine Credits.

`POST https://piqline.com/api/v1/tools/buildAdAudit`

Typ: Schreiben. Scopes: `write`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `advertisers` | `array<string>` | Ja | Names of the advertisers, as in the collections. |
| `months` | `integer` | Nein |  |
| `name` | `string` | Nein | Table name. Default: « Audit publicitaire ». |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/buildAdAudit \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"advertisers":["texte"]}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/buildAdAudit", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "advertisers": [
      "texte"
    ]
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/buildAdAudit",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "advertisers": [
            "texte",
        ],
    },
)
output = response.json()["output"]
```

### `findCreatorSponsors`

Wer YouTube-Creator in einer Nische bezahlt: Suche nach aktuellen Videos, aus jedem Video abgeleitete Sponsoren, eine Workspace-Tabelle „Sponsoren · Nische“. Verbraucht Credits; Bestätigung im Chat, Owner oder Admin.

`POST https://piqline.com/api/v1/tools/findCreatorSponsors`

Typ: Aktion. Scopes: `act`, `write`, `explore`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `niche` | `string` | Ja | Words of the niche, as a creator would title a video (« compléments alimentaires »). |
| `videos` | `integer` | Nein |  |
| `period` | `this_week \| this_month \| this_year` | Nein |  |
| `country` | `string` | Nein | YouTube region, FR by default. |
| `follow` | `boolean` | Nein | true: follow the niche, run again every week, and raise A13 when a brand starts sponsoring creators of the niche (in the bell and alert e-mails). |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/findCreatorSponsors \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"niche":"texte"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/findCreatorSponsors", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "niche": "texte"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/findCreatorSponsors",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "niche": "texte",
    },
)
output = response.json()["output"]
```

### `importAdHistory`

Importiert den Google-Verlauf einer Werbetreibenden-Erfassung: bis zu 20 Seiten (etwa 800 Anzeigen seit 2021), um vergangene Kampagnen zu datieren. Verbraucht Credits; Bestätigung im Chat, Owner oder Admin.

`POST https://piqline.com/api/v1/tools/importAdHistory`

Typ: Aktion. Scopes: `act`, `write`, `explore`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `collection` | `string` | Ja | Name of the advertiser collection. |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/importAdHistory \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"collection":"texte"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/importAdHistory", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "collection": "texte"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/importAdHistory",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "collection": "texte",
    },
)
output = response.json()["output"]
```

### `startAdCollection`

Startet eine Anzeigenerfassung zu einem Werbetreibenden (Name oder Domain) oder einem Stichwort: liest Meta, TikTok, Google und LinkedIn, bringt jede Anzeige ins gleiche Format und liest dann Winkel, Angebot, Zielgruppe und Tonalität. Verbraucht Credits; Bestätigung im Chat, Owner oder Admin.

`POST https://piqline.com/api/v1/tools/startAdCollection`

Typ: Aktion. Scopes: `act`, `write`, `explore`.

| Parameter | Typ | Erforderlich | Beschreibung |
| --- | --- | --- | --- |
| `query` | `string` | Ja | Nom ou domaine de l'annonceur (kind advertiser), ou mot-clé (kind keyword). |
| `kind` | `advertiser \| keyword` | Nein |  |
| `libraries` | `array<meta \| tiktok \| google \| linkedin>` | Nein | Bibliothèques à lire. Google ne cherche pas par mot-clé. |
| `country` | `string` | Nein | Code pays ISO. Restreint Meta et LinkedIn, choisit l'entité annonceur de Google (FR par défaut). Courants : FR, BE, CH, LU, DE, ES, IT, NL, GB, IE, US, CA, MA, SN, CI, AU, BR, JP. |
| `depth` | `apercu \| large` | Nein | apercu : une page par bibliothèque. large : jusqu'à quatre pages (plus long). |
| `cadence` | `manuel \| quotidien \| hebdomadaire` | Nein | manuel : à la main. quotidien ou hebdomadaire : la collecte se repasse seule, dans le plafond du jour, et ses signaux arrivent dans la cloche. |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/startAdCollection \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"levée de fonds"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/startAdCollection", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "levée de fonds"
  }),
});
const { output } = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/tools/startAdCollection",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "query": "levée de fonds",
    },
)
output = response.json()["output"]
```
