Felo APIs

LiveDoc API

Crea knowledge base, gestisci risorse ed esegui recupero semantico e routing.

POST/v2/livedocs

Autenticazione

Bearer API key

Tipo di contenuto

application/json or multipart/form-data

Note sui limiti

Possono applicarsi limiti specifici dell'endpoint.

SuperAgent API PPT Task API

La LiveDoc API offre operazioni CRUD complete sui LiveDoc e sulle loro risorse, compresi la creazione di documenti, il caricamento di file, l'importazione di URL e il recupero semantico.

Autenticazione

Tutte le richieste richiedono una chiave API nell'header Authorization:

Authorization: Bearer YOUR_API_KEY

Uso con agenti IA

Installa il pacchetto completo felo-ai per dare a un agente il supporto LiveDoc e ogni altra Felo Skill disponibile. L'installer individua dinamicamente ogni directory del pacchetto che contiene SKILL.md, comprese le aggiunte future del pacchetto. Installa tutte le Skill trovate nella directory nativa dell'agente: Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills o Hermes Agent ~/.hermes/skills. La guida alla configurazione manuale degli agenti IA illustra i distinti passaggi su chiave API e verifica per ogni piattaforma.

1. Creare un LiveDoc

Endpoint

POST https://openapi.felo.ai/v2/livedocs

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`name`	string	Sì	Nome del LiveDoc
`description`	string	No	Descrizione del LiveDoc
`icon`	string	No	Icona del LiveDoc

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "AI Research Notes",
    "description": "Collection of AI research materials"
  }'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "short_id": "PvyKouzJirXjFdst4uKRK3",
    "name": "AI Research Notes",
    "description": "Collection of AI research materials",
    "icon": null,
    "created_at": "2026-03-09T10:00:00Z",
    "modified_at": "2026-03-09T10:00:00Z"
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`short_id`	string	ID del LiveDoc
`name`	string	Nome del LiveDoc
`description`	string	Descrizione del LiveDoc
`icon`	string	Icona del LiveDoc
`created_at`	string	Timestamp di creazione (ISO 8601)
`modified_at`	string	Timestamp dell'ultima modifica (ISO 8601)
`is_shared`	boolean	Se questo LiveDoc è condiviso con l'utente corrente (non di sua proprietà)

2. Elencare i LiveDoc

Endpoint

GET https://openapi.felo.ai/v2/livedocs

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`keyword`	string	No	Filtra per parola chiave
`page`	integer	No	Numero di pagina (parte da 1)
`size`	integer	No	Dimensione della pagina

Esempio

curl 'https://openapi.felo.ai/v2/livedocs?keyword=AI&page=1&size=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "size": 20,
    "items": [
      {
        "short_id": "PvyKouzJirXjFdst4uKRK3",
        "name": "AI Research Notes",
        "description": "Collection of AI research materials",
        "icon": null,
        "created_at": "2026-03-09T10:00:00Z",
        "modified_at": "2026-03-09T10:05:00Z",
        "is_shared": false,
        "readme": {
          "summary": "AI research notes and papers collection",
          "content": "# AI Research Notes\n\nThis LiveDoc contains..."
        }
      }
    ]
  }
}

Campi della risposta

Ogni elemento in items contiene gli stessi campi della risposta di creazione di un LiveDoc, più:

Campo	Tipo	Descrizione
`readme`	object \| null	Informazioni del README. `null` se non esiste alcun README.
`readme.summary`	string \| null	Descrizione del progetto in una riga
`readme.content`	string \| null	Contenuto del README (Markdown)

Endpoint

PUT https://openapi.felo.ai/v2/livedocs/{short_id}

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`name`	string	No	Nuovo nome del LiveDoc
`description`	string	No	Nuova descrizione del LiveDoc

Esempio

curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Research Notes"
  }'

Risposta di successo (200)

Restituisce l'oggetto LiveDoc aggiornato (stessa struttura della creazione).

4. Eliminare un LiveDoc

Endpoint

DELETE https://openapi.felo.ai/v2/livedocs/{short_id}

Esempio

curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": null
}

5. Elencare le risorse

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`resource_types`	string[]	No	Filtra per tipi di risorsa
`page`	integer	No	Numero di pagina (parte da 1)
`size`	integer	No	Dimensione della pagina

Esempio

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources?page=1&size=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "size": 20,
    "items": [
      {
        "id": "res_001",
        "title": "OpenAI Blog Post",
        "link": "https://openai.com/blog/...",
        "snippet": "Summary of the article...",
        "thumbnail": null,
        "resource_type": "web",
        "resource_key": "key_001",
        "status": "completed",
        "source": "url",
        "created_at": "2026-03-09T10:00:10Z",
        "modified_at": "2026-03-09T10:00:15Z"
      }
    ]
  }
}

Campi della risposta della risorsa

Campo	Tipo	Descrizione
`id`	string	ID della risorsa
`title`	string	Titolo della risorsa
`link`	string	Link/URL della risorsa
`snippet`	string	Riepilogo della risorsa
`thumbnail`	string	URL della miniatura
`resource_type`	string	Tipo di risorsa (ad es. `web`, `ai_doc`, `file`)
`resource_key`	string	Chiave di associazione della risorsa
`status`	string	Stato della risorsa
`source`	string	Origine della risorsa
`created_at`	string	Timestamp di creazione (ISO 8601)
`modified_at`	string	Timestamp dell'ultima modifica (ISO 8601)

6. Ottenere una singola risorsa

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}

Esempio

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

Restituisce un singolo oggetto risorsa (stessa struttura degli elementi in Elencare le risorse).

7. Aggiornare una risorsa

Aggiorna title, snippet o thumbnail di una risorsa. Vengono aggiornati solo i campi forniti; i campi omessi mantengono i valori correnti.

Endpoint

PUT https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}

Corpo della richiesta

Tutti i campi sono facoltativi.

Parametro	Tipo	Obbligatorio	Descrizione
`title`	string	No	Nuovo titolo della risorsa (massimo 500 caratteri)
`snippet`	string	No	Nuovo riepilogo della risorsa (massimo 2000 caratteri)
`thumbnail`	string	No	Nuovo URL della miniatura (massimo 2000 caratteri)

Esempio

curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Updated Title",
    "snippet": "Updated summary of the resource."
  }'

Risposta di successo (200)

Restituisce l'oggetto risorsa aggiornato (stessa struttura degli elementi in Elencare le risorse).

8. Aggiornare il contenuto di una risorsa

Aggiorna il contenuto Markdown di una risorsa ai_doc. Supportato solo per le risorse con resource_type == ai_doc. Il campo snippet viene aggiornato automaticamente con i primi 2000 byte del nuovo contenuto.

Endpoint

PUT https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}/content

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`content`	string	Sì	Nuovo contenuto Markdown della risorsa

Esempio

curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001/content' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "# Updated Document\n\nThis is the new content."
  }'

Risposta di successo (200)

Restituisce l'oggetto risorsa aggiornato (stessa struttura degli elementi in Elencare le risorse).

9. Creare una risorsa documento

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/doc

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`title`	string	No	Titolo del documento (predefinito: "New Document")
`content`	string	Sì	Contenuto del documento

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/doc' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "My Research Notes",
    "content": "Key findings from the AI research paper..."
  }'

Risposta di successo (200)

Restituisce l'oggetto risorsa creato.

10. Caricare un file come documento

Carica un file e convertilo in una risorsa documento (tipo ai_doc).

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/upload-doc

Content-Type

multipart/form-data

Parti della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`file`	file	Sì	Il file da caricare
`title`	string	No	Titolo del documento

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/upload-doc' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F '[email protected]' \
  -F 'title=My PDF Document'

Risposta di successo (200)

Restituisce l'oggetto risorsa creato.

11. Caricare un file come risorsa

Carica un file e conservane il formato originale.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/upload

Content-Type

multipart/form-data

Parti della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`file`	file	Sì	Il file da caricare

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/upload' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F '[email protected]'

Risposta di successo (200)

Restituisce l'oggetto risorsa creato.

12. Aggiungere risorse URL

Aggiungi uno o più URL come risorse a un LiveDoc.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/urls

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`urls`	array	Sì	Elenco di elementi URL da aggiungere (da 1 a 10). Ogni elemento può essere una stringa semplice o un oggetto con `url` e `title` facoltativo.

Formati degli elementi URL

Ogni voce in urls può essere:

Una stringa semplice: "https://example.com/article"
Un oggetto: {"url": "https://example.com/article", "title": "Custom Title"}

Campo	Tipo	Obbligatorio	Descrizione
`url`	string	Sì	L'URL da aggiungere (da 5 a 2000 caratteri)
`title`	string	No	Titolo personalizzato per la risorsa (massimo 1000 caratteri). Se omesso, il titolo viene generato automaticamente dalla pagina.

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/urls' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      "https://example.com/article-1",
      {"url": "https://example.com/article-2", "title": "My Custom Title"}
    ]
  }'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": [
    {
      "url": "https://example.com/article-1",
      "status": "success",
      "fail_reason": null,
      "resource_id": "res_003"
    },
    {
      "url": "https://example.com/article-2",
      "status": "existed",
      "fail_reason": null,
      "resource_id": "res_004"
    }
  ]
}

Campi del risultato URL

Campo	Tipo	Descrizione
`url`	string	L'URL elaborato
`status`	string	Stato del risultato: `success`, `failed` o `existed`
`fail_reason`	string	Motivo dell'errore (null se riuscito)
`resource_id`	string	ID della risorsa creata

13. Eliminare una risorsa

Endpoint

DELETE https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}

Esempio

curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": null
}

14. Recupero (ricerca semantica)

Esegui il recupero semantico sulle risorse di un LiveDoc.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/retrieve

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Contenuto della query per la ricerca semantica
`resource_ids`	string[]	No	ID specifici delle risorse in cui cercare (da 1 a 50). Se omesso, le risorse pertinenti vengono instradate automaticamente in base alla query

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/retrieve' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "latest developments in large language models",
    "resource_ids": ["res_001", "res_002"]
  }'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": [
    {
      "id": "res_001",
      "title": "LLM Research Paper",
      "content": "Relevant content excerpt...",
      "score": 0.92,
      "metadata": {}
    }
  ]
}

Campi del risultato di recupero

Campo	Tipo	Descrizione
`id`	string	ID della risorsa
`title`	string	Titolo della risorsa
`content`	string	Contenuto corrispondente
`score`	number	Punteggio di pertinenza
`metadata`	object	Metadati aggiuntivi

15. Instradare le risorse

Instrada le risorse pertinenti di un LiveDoc in base a una query. Restituisce un elenco di ID di risorse che possono essere passati all'endpoint di recupero.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/route

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Contenuto della query per l'instradamento
`max_resources`	integer	No	Numero massimo di ID di risorse da restituire

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/route' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "latest developments in large language models",
    "max_resources": 5
  }'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": ["res_001", "res_003", "res_007"]
}

16. Scaricare il file sorgente di una risorsa

Ottieni il file sorgente di una risorsa. Restituisce un redirect 302 all'URL di download prefirmato.

Supportato solo per le risorse che hanno un file sorgente associato (ad es. documenti caricati).

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}/download

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`expires_in`	integer	No	Scadenza dell'URL in secondi (predefinito: 3600)

Esempio

curl -L 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001/download' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta

Restituisce 302 Found con un header Location che punta all'URL di download S3 prefirmato. I client HTTP con supporto ai redirect (ad es. curl -L) seguono il redirect e scaricano il file direttamente.

17. Ottenere il contenuto di una risorsa

Recupera il contenuto testuale estratto di una risorsa. Supportato per la maggior parte dei tipi di risorsa (document, web, video, ai_doc, ai_ppt, text, voice, mindmap e altri). Restituisce 400 per tipi non supportati come image.

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/resources/{resource_id}/content

Esempio

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/res_001/content' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "title": "Q4 Financial Report",
    "type": "document",
    "content": "Full extracted text content of the resource..."
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`title`	string	Titolo della risorsa
`type`	string	Tipo di risorsa
`content`	string	Contenuto testuale estratto

18. Recupero di una pagina PPT

Esegui un recupero approfondito del contenuto di una pagina specifica di una risorsa PPT. La pagina della diapositiva viene analizzata e vengono restituiti blocchi di contenuto classificati. Il formato della risposta è identico a quello dell'endpoint Recupero.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/resources/ppt-retrieve

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`resource_id`	string	Sì	ID della risorsa PPT
`page_number`	integer	Sì	Numero di pagina da recuperare (parte da 1)
`query`	string	Sì	Contenuto della query che descrive cosa cercare
`max_chunk`	integer	No	Numero massimo di blocchi da restituire (predefinito: 3)

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/resources/ppt-retrieve' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource_id": "res_001",
    "page_number": 3,
    "query": "product pricing information",
    "max_chunk": 3
  }'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": [
    {
      "id": "res_001_page_3_chunk_1",
      "title": "Q4 Product Deck",
      "content": "Relevant slide content excerpt...",
      "score": null,
      "metadata": {
        "resource_id": "res_001",
        "page_number": 3,
        "index": 1
      }
    }
  ]
}

Campi della risposta

Come nei campi del risultato di recupero.

Codici di errore

Codice	Stato HTTP	Descrizione
`UNAUTHORIZED`	401	La chiave API non è valida o è revocata
`LIVEDOC_CREATE_FAILED`	502	Creazione del LiveDoc non riuscita
`LIVEDOC_UPDATE_FAILED`	502	Aggiornamento del LiveDoc non riuscito
`LIVEDOC_DELETE_FAILED`	502	Eliminazione del LiveDoc non riuscita
`LIVEDOC_NOT_FOUND`	404	LiveDoc non trovato
`LIVEDOC_LIST_FAILED`	502	Elenco dei LiveDoc non riuscito
`LIVEDOC_RESOURCE_CREATE_FAILED`	502	Creazione della risorsa non riuscita
`LIVEDOC_RESOURCE_UPLOAD_FAILED`	502	Caricamento della risorsa non riuscito
`LIVEDOC_RESOURCE_DELETE_FAILED`	502	Eliminazione della risorsa non riuscita
`LIVEDOC_RESOURCE_NOT_FOUND`	404	Risorsa non trovata
`LIVEDOC_RESOURCE_LIST_FAILED`	502	Elenco delle risorse non riuscito
`LIVEDOC_RESOURCE_RETRIEVE_FAILED`	502	Recupero delle risorse non riuscito
`LIVEDOC_RESOURCE_ADD_URLS_FAILED`	502	Aggiunta delle risorse URL non riuscita

19. Ottenere il README

Ottieni il contenuto del README di un LiveDoc. Restituisce una stringa vuota se non è stato impostato alcun README.

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/readme

Esempio

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "summary": "A brief one-line description of the project.",
    "content": "# My LiveDoc\n\nThis is the README content in Markdown."
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`summary`	string \| null	Descrizione del progetto in una riga. Massimo 2000 caratteri.
`content`	string	Contenuto del README (Markdown). Stringa vuota se non impostato.

20. Creare o aggiornare il README

Crea o aggiorna il README di un LiveDoc (semantica upsert).

Endpoint

PUT https://openapi.felo.ai/v2/livedocs/{short_id}/readme

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`summary`	string	No	Descrizione del progetto in una riga (massimo 2000 caratteri)
`content`	string	No	Contenuto del README (Markdown)

Nota: è necessario fornire almeno uno tra summary e content.

Esempio

curl -X PUT 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "summary": "A brief one-line description of the project.",
    "content": "# My LiveDoc\n\nThis is the README content in Markdown."
  }'

Risposta di successo (200)

Restituisce l'oggetto README aggiornato (stessa struttura di Ottenere il README).

21. Accodare al README

Accoda contenuto alla fine di un README esistente. Se non esiste alcun README, ne viene creato uno nuovo con il contenuto fornito.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/readme/append

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`content`	string	Sì	Contenuto da accodare (Markdown)

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme/append' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "\n\n## New Section\n\nAdditional content appended to README."
  }'

Risposta di successo (200)

Restituisce l'oggetto README completo dopo l'accodamento (stessa struttura di Ottenere il README).

22. Eliminare il README

Elimina il README di un LiveDoc.

Endpoint

DELETE https://openapi.felo.ai/v2/livedocs/{short_id}/readme

Esempio

curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/readme' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": null
}

23. Elencare le attività

Ottieni un elenco paginato delle attività di un LiveDoc. I risultati sono ordinati per sort crescente, status crescente e created_at decrescente.

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/tasks

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`status`	integer	No	Filtra per stato: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE
`labels`	string[]	No	Filtra per etichette (le attività devono contenere tutte le etichette specificate)
`page`	integer	No	Numero di pagina (parte da 1)
`size`	integer	No	Dimensione della pagina

Esempio

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks?status=0&page=1&size=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 1,
    "page": 1,
    "size": 20,
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Write documentation",
        "description": "Write API documentation for the new endpoints",
        "status": 0,
        "sort": 0,
        "labels": ["docs", "priority-high"],
        "created_at": "2026-03-19T10:00:00Z",
        "modified_at": "2026-03-19T10:00:00Z"
      }
    ]
  }
}

Campi della risposta dell'attività

Campo	Tipo	Descrizione
`id`	string	ID dell'attività (UUID)
`title`	string	Titolo dell'attività
`description`	string	Descrizione dell'attività
`status`	integer	Stato dell'attività: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE
`sort`	integer	Ordine di ordinamento (non negativo)
`labels`	string[]	Elenco delle etichette
`operated_by`	string	Firma dell'operatore, ad es. `claude-code`, `openclaw`
`created_at`	string	Timestamp di creazione (ISO 8601)
`modified_at`	string	Timestamp dell'ultima modifica (ISO 8601)

24. Creare un'attività

Crea una nuova attività in un LiveDoc.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/tasks

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`title`	string	Sì	Titolo dell'attività
`description`	string	No	Descrizione dell'attività
`status`	integer	Sì	Stato dell'attività: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE
`sort`	integer	Sì	Ordine di ordinamento (intero non negativo)
`labels`	string[]	No	Elenco delle etichette (massimo 10, ciascuna massimo 50 caratteri)
`operated_by`	string	No	Firma dell'operatore, ad es. `claude-code`, `openclaw` (massimo 100 caratteri)

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Write documentation",
    "description": "Write API documentation for the new endpoints",
    "status": 0,
    "sort": 0,
    "labels": ["docs", "priority-high"]
  }'

Risposta di successo (200)

Restituisce l'oggetto attività creato (stessa struttura degli elementi in Elencare le attività).

25. Aggiornare un'attività

Aggiorna parzialmente un'attività. Vengono aggiornati solo i campi forniti; i campi omessi mantengono i valori correnti.

Endpoint

PATCH https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}

Corpo della richiesta

Tutti i campi sono facoltativi.

Parametro	Tipo	Obbligatorio	Descrizione
`title`	string	No	Nuovo titolo dell'attività
`description`	string	No	Nuova descrizione dell'attività
`status`	integer	No	Nuovo stato: `0`=TODO, `1`=IN_PROGRESS, `2`=DONE
`sort`	integer	No	Nuovo ordine di ordinamento (non negativo)
`labels`	string[]	No	Nuovo elenco di etichette (massimo 10, ciascuna massimo 50 caratteri)
`operated_by`	string	No	Firma dell'operatore, ad es. `claude-code`, `openclaw` (massimo 100 caratteri)

Esempio

curl -X PATCH 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": 1
  }'

Risposta di successo (200)

Restituisce l'oggetto attività aggiornato (stessa struttura degli elementi in Elencare le attività).

26. Eliminare un'attività

Elimina logicamente un'attività.

Endpoint

DELETE https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}

Esempio

curl -X DELETE 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": null
}

27. Elencare i record delle attività

Ottieni un elenco paginato dei record di un'attività (commenti e cronologia delle modifiche), ordinati per created_at crescente.

Endpoint

GET https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}/records

Parametri di query

Parametro	Tipo	Obbligatorio	Descrizione
`record_type`	string	No	Filtra per tipo di record: `comment`, `edit`, `status_change`
`page`	integer	No	Numero di pagina (parte da 1)
`size`	integer	No	Dimensione della pagina

Esempio

curl 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000/records' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Risposta di successo (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 2,
    "page": 1,
    "size": 20,
    "items": [
      {
        "id": "rec_001",
        "record_type": "comment",
        "content": "This is a comment",
        "meta": null,
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "created_at": "2026-03-19T10:05:00Z",
        "modified_at": "2026-03-19T10:05:00Z"
      },
      {
        "id": "rec_002",
        "record_type": "status_change",
        "content": null,
        "meta": {"from": 0, "to": 1},
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "created_at": "2026-03-19T10:10:00Z",
        "modified_at": "2026-03-19T10:10:00Z"
      }
    ]
  }
}

Campi della risposta del record dell'attività

Campo	Tipo	Descrizione
`id`	string	ID del record
`record_type`	string	Tipo di record: `comment` / `edit` / `status_change`
`content`	string	Testo del commento (solo per il tipo `comment`)
`meta`	object	Dettagli della modifica (per i tipi `edit` e `status_change`)
`task_id`	string	ID dell'attività principale
`operated_by`	string	Firma dell'operatore, ad es. `claude-code`, `openclaw`
`created_at`	string	Timestamp di creazione (ISO 8601)
`modified_at`	string	Timestamp dell'ultima modifica (ISO 8601)

28. Aggiungere un commento a un'attività

Aggiungi un commento a un'attività.

Endpoint

POST https://openapi.felo.ai/v2/livedocs/{short_id}/tasks/{task_id}/comments

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`content`	string	Sì	Contenuto del commento
`operated_by`	string	No	Firma dell'operatore, ad es. `claude-code`, `openclaw` (massimo 100 caratteri)

Esempio

curl -X POST 'https://openapi.felo.ai/v2/livedocs/PvyKouzJirXjFdst4uKRK3/tasks/550e8400-e29b-41d4-a716-446655440000/comments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "content": "This task is now in progress."
  }'

Risposta di successo (200)

Restituisce l'oggetto record creato (stessa struttura degli elementi in Elencare i record delle attività).

Codici di errore (aggiornati)

Codice	Stato HTTP	Descrizione
`UNAUTHORIZED`	401	La chiave API non è valida o è revocata
`LIVEDOC_CREATE_FAILED`	502	Creazione del LiveDoc non riuscita
`LIVEDOC_UPDATE_FAILED`	502	Aggiornamento del LiveDoc non riuscito
`LIVEDOC_DELETE_FAILED`	502	Eliminazione del LiveDoc non riuscita
`LIVEDOC_NOT_FOUND`	404	LiveDoc non trovato
`LIVEDOC_LIST_FAILED`	502	Elenco dei LiveDoc non riuscito
`LIVEDOC_RESOURCE_CREATE_FAILED`	502	Creazione della risorsa non riuscita
`LIVEDOC_RESOURCE_UPLOAD_FAILED`	502	Caricamento della risorsa non riuscito
`LIVEDOC_RESOURCE_DELETE_FAILED`	502	Eliminazione della risorsa non riuscita
`LIVEDOC_RESOURCE_NOT_FOUND`	404	Risorsa non trovata
`LIVEDOC_RESOURCE_LIST_FAILED`	502	Elenco delle risorse non riuscito
`LIVEDOC_RESOURCE_RETRIEVE_FAILED`	502	Recupero delle risorse non riuscito
`LIVEDOC_RESOURCE_ADD_URLS_FAILED`	502	Aggiunta delle risorse URL non riuscita
`LIVEDOC_README_GET_FAILED`	502	Lettura del README non riuscita
`LIVEDOC_README_UPDATE_FAILED`	502	Creazione o aggiornamento del README non riuscito
`LIVEDOC_README_DELETE_FAILED`	502	Eliminazione del README non riuscita
`LIVEDOC_README_NOT_FOUND`	404	README non trovato
`LIVEDOC_TASK_LIST_FAILED`	502	Elenco delle attività non riuscito
`LIVEDOC_TASK_CREATE_FAILED`	502	Creazione dell'attività non riuscita
`LIVEDOC_TASK_UPDATE_FAILED`	502	Aggiornamento dell'attività non riuscito
`LIVEDOC_TASK_DELETE_FAILED`	502	Eliminazione dell'attività non riuscita
`LIVEDOC_TASK_NOT_FOUND`	404	Attività non trovata
`LIVEDOC_TASK_RECORD_LIST_FAILED`	502	Elenco dei record delle attività non riuscito
`LIVEDOC_TASK_COMMENT_CREATE_FAILED`	502	Creazione del commento dell'attività non riuscita