Library, notes, tasks, memory and research

The project’s own records, the same the agent’s tools read and write. Paths are relative to /api/v1.

POST /sessions/{sessionId}/{resource}/batch

Delete several items at once from the library, the notes, the tasks, the memory or the research.

resource is library, notes, tasks, memory or research. Each id is deleted through the same door as a single delete, independently: the answer lists one outcome per id, in order; there is no global rollback.

Path

sessionId

The session.

resource

The section: library, notes, tasks, memory or research.

Body

azionerequired

elimina (delete).

idsrequired

The ids, unique non-empty strings.

Answers The JSON envelope.

Errors5

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
RESEARCH_CONFLICT	409	The research run is not in the right state for this action.
RESEARCH_INVALID	400	The request is not valid for deep research.
RESEARCH_NOT_FOUND	404	The research run no longer exists.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/library

The library of the session’s project: the documents saved in it.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/library/{itemId}/file

Download a library item, as an attachment.

Path

sessionId

The session.

itemId

The Library file.

Answers The bytes themselves (a file or an image), not JSON.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/library/{itemId}/anteprima

Preview a library item inline (PDF and a few safe types only, sandboxed; any other type is 404).

Path

sessionId

The session.

itemId

The Library file.

Answers The bytes themselves (a file or an image), not JSON.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/library/{itemId}/rivela

Show a library item in the file manager of this computer.

Path

sessionId

The session.

itemId

The Library file.

Body

None: the body is empty.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/library/{itemId}/apri

Open a library item with this computer’s default application.

Path

sessionId

The session.

itemId

The Library file.

Body

None: the body is empty.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

PATCH /sessions/{sessionId}/library/{itemId}

Rename a library item.

Path

sessionId

The session.

itemId

The Library file.

Body

nomerequired

The new name.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

DELETE /sessions/{sessionId}/library/{itemId}

Delete a library item; the answer says which one went.

Path

sessionId

The session.

itemId

The Library file.

Body

None: the body is empty.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/notes

Your notes (global to you, not to the session’s project).

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/notes

Create a note.

Path

sessionId

The session.

Body

titolorequired

The title.

contenutorequired

The text.

formato

markdown or testo; detected when absent.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/notes/{noteId}

Read a note.

Path

sessionId

The session.

noteId

The note.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

PATCH /sessions/{sessionId}/notes/{noteId}

Change a note: only the fields sent change (at least one).

Path

sessionId

The session.

noteId

The note.

Body

titolo

The new title.

contenuto

The new text.

formato

markdown, testo, or null to detect it again.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

DELETE /sessions/{sessionId}/notes/{noteId}

Delete a note.

Path

sessionId

The session.

noteId

The note.

Body

None: the body is empty.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/tasks

Your tasks (global to you, like the notes).

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/tasks

Create a task.

Path

sessionId

The session.

Body

titolorequired

The title.

descrizione

A description, or null.

priorita

low, normal (default) or high.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/tasks/{taskId}

Read a task.

Path

sessionId

The session.

taskId

The task.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

PATCH /sessions/{sessionId}/tasks/{taskId}

Change a task’s title, description or priority (never its state: that has its own door).

Path

sessionId

The session.

taskId

The task.

Body

titolo

The new title.

descrizione

The new description, or null.

priorita

low, normal or high.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

DELETE /sessions/{sessionId}/tasks/{taskId}

Delete a task.

Path

sessionId

The session.

taskId

The task.

Body

None: the body is empty.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/tasks/{taskId}/stato

Set a task’s state.

Path

sessionId

The session.

taskId

The task.

Body

statorequired

todo, doing or done.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/memory

Your memory: what TALOS remembers about you and your work, across sessions.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/memory

Add a memory. The answer says duplicato: true when the same memory already existed.

Path

sessionId

The session.

Body

titolorequired

The title.

contenutorequired

The text.

genere

The kind: preference, project_fact, procedure or policy_note.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/memory/{memoryId}

Read a memory.

Path

sessionId

The session.

memoryId

The memory.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

PATCH /sessions/{sessionId}/memory/{memoryId}

Change a memory: only the fields sent change (at least one).

Path

sessionId

The session.

memoryId

The memory.

Body

titolo

The new title.

contenuto

The new text.

genere

preference, project_fact, procedure or policy_note.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

DELETE /sessions/{sessionId}/memory/{memoryId}

Delete a memory.

Path

sessionId

The session.

memoryId

The memory.

Body

None: the body is empty.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/research

The deep research runs of the session’s project.

Path

sessionId

The session.

Answers The JSON envelope.

Errors2

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/research/{researchId}/pausa

Pause a research run.

Path

sessionId

The session.

researchId

The research.

Body

None: the body is empty.

Answers The JSON envelope.

Errors6

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
RESEARCH_CONFLICT	409	The research run is not in the right state for this action.
RESEARCH_INVALID	400	The request is not valid for deep research.
RESEARCH_NOT_FOUND	404	The research run no longer exists.
RESEARCH_RECHECK_UNAVAILABLE	409	This research run cannot be checked again yet.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/research/{researchId}/ripresa

Resume a paused research run.

Path

sessionId

The session.

researchId

The research.

Body

None: the body is empty.

Answers The JSON envelope.

Errors6

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
RESEARCH_CONFLICT	409	The research run is not in the right state for this action.
RESEARCH_INVALID	400	The request is not valid for deep research.
RESEARCH_NOT_FOUND	404	The research run no longer exists.
RESEARCH_RECHECK_UNAVAILABLE	409	This research run cannot be checked again yet.

Any operation can also answer the common errors.

POST /sessions/{sessionId}/research/{researchId}/riverifica

Check the sources of a finished research run again.

Path

sessionId

The session.

researchId

The research.

Body

None: the body is empty.

Answers The JSON envelope.

Errors6

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
RESEARCH_CONFLICT	409	The research run is not in the right state for this action.
RESEARCH_INVALID	400	The request is not valid for deep research.
RESEARCH_NOT_FOUND	404	The research run no longer exists.
RESEARCH_RECHECK_UNAVAILABLE	409	This research run cannot be checked again yet.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/research/{researchId}/esporta

Export a research run as a file.

Path

sessionId

The session.

researchId

The research.

Query

formatorequired

md, html, pdf, docx, json, bib, ris or fonti (the sources, as Markdown).

tono

For the report: report (default), brief or dossier.

Answers The bytes themselves (a file or an image), not JSON.

Errors3

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
RESEARCH_INVALID	400	The request is not valid for deep research.
RESEARCH_NOT_FOUND	404	The research run no longer exists.

Any operation can also answer the common errors.

GET /sessions/{sessionId}/research/{researchId}

One research run: its question, plan, sources and report.

Path

sessionId

The session.

researchId

The research.

Answers The JSON envelope.

Errors6

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
RESEARCH_CONFLICT	409	The research run is not in the right state for this action.
RESEARCH_INVALID	400	The request is not valid for deep research.
RESEARCH_NOT_FOUND	404	The research run no longer exists.
RESEARCH_RECHECK_UNAVAILABLE	409	This research run cannot be checked again yet.

Any operation can also answer the common errors.

DELETE /sessions/{sessionId}/research/{researchId}

Delete a research run; when it cannot be deleted now the answer is RESEARCH_CONFLICT with the reason.

Path

sessionId

The session.

researchId

The research.

Body

None: the body is empty.

Answers The JSON envelope.

Errors6

Code	Status	Meaning
NOT_FOUND	404	Nothing answers at this address, or the resource it names does not exist.
QUERY_INVALID	400	The request is not valid: a query parameter or a body field is missing, unknown or malformed.
RESEARCH_CONFLICT	409	The research run is not in the right state for this action.
RESEARCH_INVALID	400	The request is not valid for deep research.
RESEARCH_NOT_FOUND	404	The research run no longer exists.
RESEARCH_RECHECK_UNAVAILABLE	409	This research run cannot be checked again yet.

Any operation can also answer the common errors.