# Escritura

> Escribir en el workspace. 12 herramientas, con sus parámetros y ejemplos de llamada.

Source: https://piqline.com/es/docs/api/reference/write

Herramientas del agente Piqline que crean o modifican objetos del workspace. Requieren el scope `write`.

Cada llamada es una petición `POST` con la clave en `Authorization: Bearer`. El cuerpo JSON es la entrada de la herramienta, y la respuesta tiene la forma `{ "tool": "nom", "output": … }`. Los ejemplos solo incluyen los parámetros obligatorios. Las descripciones de los parámetros son las que leen los agentes.

### `updateWorkspaceProfile`

Guarda el perfil de necesidades del workspace: objetivos, temas, entidades, idiomas, regiones, nivel, ritmo.

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

Tipo: Escritura. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `needs` | `object` | No |  |
| `stage` | `string` | No |  |
| `onboarding_status` | `not_started \| in_progress \| done \| skipped` | No |  |
| `summary` | `string` | No |  |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/updateWorkspaceProfile \
  -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/updateWorkspaceProfile", {
  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/updateWorkspaceProfile",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={},
)
output = response.json()["output"]
```

### `followEntity`

Sigue una empresa, una marca o una cuenta pública (nunca una persona privada) para vincular sus elementos y menciones.

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

Tipo: Escritura. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | `string` | Sí |  |
| `kind` | `company \| brand \| account` | No |  |
| `siren` | `string` | No |  |
| `domain` | `string` | No |  |
| `handles` | `array<object>` | No |  |
| `role` | `self \| competitor \| client \| target \| other` | No |  |
| `aliases` | `array<string>` | No |  |

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

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

### `unfollowEntity`

Deja de seguir una entidad. Sus vínculos existentes permanecen.

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

Tipo: Eliminación. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `entityId` | `string` | Sí |  |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/unfollowEntity \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityId":"5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/tools/unfollowEntity", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "entityId": "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/unfollowEntity",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "entityId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
    },
)
output = response.json()["output"]
```

### `saveBookmark`

Guarda un marcador en la bóveda del workspace. Una URL http(s) se pone en cola para lectura, archivado y vectorización.

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

Tipo: Escritura. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `title` | `string` | Sí |  |
| `href` | `string` | Sí |  |
| `kind` | `item \| source \| signal \| graph \| search \| document \| board \| chat` | No |  |
| `subtitle` | `string` | No |  |
| `note` | `string` | No |  |
| `tags` | `array<string>` | No |  |
| `origin` | `dashboard \| api \| slack \| whatsapp \| mail \| other` | No |  |
| `originRef` | `string` | No |  |

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

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

### `setWatchContract`

Define un contrato de vigilancia sobre una fuente: la página de vigilancia solo muestra entonces los elementos que coinciden. Determinista, sin modelo.

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

Tipo: Escritura. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `sourceId` | `string` | Sí |  |
| `intent` | `string` | Sí | What this workspace watches on the source, in the person's words. |
| `include` | `array<string>` | No | Keep an item only if it contains at least one of these terms (whole word, any case or accent). |
| `exclude` | `array<string>` | No | Drop an item containing any of these terms. |
| `event` | `hiring \| funding \| launch \| expansion \| reorg \| open_to_work \| leaving \| interested_comment \| …` | No | Business event the item must announce (hiring, funding, launch…), read from its text. |
| `sectors` | `array<string>` | No |  |

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

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

### `removeWatchContract`

Elimina el contrato de vigilancia de una fuente: se vuelven a mostrar todos los elementos.

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

Tipo: Eliminación. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `sourceId` | `string` | Sí |  |

```bash tab="curl"
curl -s https://piqline.com/api/v1/tools/removeWatchContract \
  -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/removeWatchContract", {
  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/removeWatchContract",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "sourceId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
    },
)
output = response.json()["output"]
```

### `initReaderInterview`

Guarda las dos respuestas de la entrevista de lectura (lo esencial o el detalle, intención principal) en el perfil de lectura.

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

Tipo: Escritura. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `density` | `essentiel \| detail` | Sí |  |
| `intent` | `read-arrivals \| spot-change \| watch-entities \| compare \| measure-coverage \| control-sources \| analyze-market \| prepare-output \| …` | Sí |  |

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

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

### `applyBoardChange`

Aplica a un tablero cambios que ya fueron aprobados.

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

Tipo: Escritura. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `dashboardId` | `string` | No |  |
| `changes` | `array<object>` | Sí |  |

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

response = requests.post(
    "https://piqline.com/api/v1/tools/applyBoardChange",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "changes": [
            {
                "id": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
                "kind": "add",
                "widgetId": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
                "reason": "texte",
                "title": "texte",
            },
        ],
    },
)
output = response.json()["output"]
```

### `buildDashboard`

Construye un tablero directamente, sin pasar por el selector de widgets.

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

Tipo: Escritura. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `spec` | `object` | Sí |  |
| `save` | `boolean` | No | Persist the board when the user is owner/admin. |

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

response = requests.post(
    "https://piqline.com/api/v1/tools/buildDashboard",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "spec": {
            "version": 1,
            "title": "texte",
            "description": "texte",
            "period": "1h",
            "widgets": [
                {
                    "kind": "texte",
                    "title": "texte",
                },
            ],
        },
    },
)
output = response.json()["output"]
```

### `saveWorkspaceTable`

Crea una tabla del workspace, rellenada con las columnas útiles.

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

Tipo: Escritura. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `name` | `string` | Sí |  |
| `comment` | `string` | Sí |  |
| `columns` | `array<object>` | Sí |  |
| `rows` | `array<object>` | Sí |  |

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

response = requests.post(
    "https://piqline.com/api/v1/tools/saveWorkspaceTable",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={
        "name": "texte",
        "comment": "texte",
        "columns": [
            {
                "id": "5a0e9c1f-2b7d-4e63-8f14-d3c8a6b92e70",
                "name": "texte",
                "type": "text",
            },
        ],
        "rows": [
            {},
        ],
    },
)
output = response.json()["output"]
```

### `writeFromWatch`

Redacta un texto a partir de los elementos de las vigilancias del workspace (artículo, publicación de LinkedIn, hilo de X, pie de foto de Instagram, boletín, guion de vídeo, nota de prensa, artículo SEO, correo, resumen), en nueve idiomas, con cada dato citado [n] a su fuente; el texto se une a los borradores. Consume unos pocos créditos.

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

Tipo: Escritura. Scopes: `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `instruction` | `string` | Sí | What to write and for whom, in plain words, e.g. « Le post de la semaine sur ce qui a bougé dans la cosmétique ». |
| `example` | `string` | No | Optional sample text whose style to follow. |
| `scope` | `object` | No | Which items of the workspace watches to write from: sources, topics, keywords, platforms, item types or item ids, period and depth. Default: the last 7 days, 15 items. |
| `pen` | `object` | No | Format (article, linkedin, x_thread, instagram, newsletter, video_script, press_release, seo_brief, email, summary), goal, tone, framework, length, voice, language (fr, en, es, de, it, pt, nl, he, ar), creativity, variants and options. |
| `save` | `boolean` | No | Keep the text in the workspace drafts (default). false: return it only. |

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

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

### `setTableFeed`

Da vida a una tabla: en cuanto un elemento del corpus cumple la regla, se añade, previa confirmación. status=paused detiene el rellenado.

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

Tipo: Acción. Scopes: `act`, `write`.

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `schema` | `string` | No |  |
| `name` | `string` | Sí |  |
| `status` | `live \| paused` | No |  |
| `prompt` | `string` | Sí | The person's words, unchanged. |
| `summary` | `string` | Sí | What you understood, in plain French, one sentence. |
| `sourceIds` | `array<string>` | No |  |
| `sourceLabels` | `array<string>` | No |  |
| `query` | `string` | No |  |
| `platform` | `string` | No |  |
| `itemType` | `post \| video \| article \| listing \| job_offer` | No |  |
| `alreadyMatching` | `integer` | No | How many items searchItems found just now. |

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

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