GoliathDevelopersGet an API key
Guides / Library API

Library API

Read and edit files and folders, share them, run skip traces and tags on Library files, and manage memory notes through the Goliath developer API

About

The Library is your organization’s file system: the Team space, each person’s My files, records such as call recordings and contact attachments, and the memory shelves your AI employees read from. Through the API you can browse and search it, read and edit text files and spreadsheets in place, move, share and trash items, run a skip trace or property tag on a Library file, and manage memory notes.

All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

Browsing and searching (READ scope)

operationId Scope What it does
listSpaceRoots READ The roots the key owner can open: Team, their own My files, and any read-only system space. Each id is the spaceId the other operations take. Uploads and downloads live in listFiles, not here.
listSpaceFolder READ One folder (or a space root when folderId is omitted): folders, then files, each with abilities, fileType, size, owner, creator and path. Hidden items are not returned.
getSpaceItem READ One folder or file by id, with its path, owner, creator, current version and abilities.
listRecentSpaceItems READ The Recent view: files the key owner can see that changed lately, newest first.
listSpacesSharedWithMe READ The Shared with me view: items teammates shared with the key owner directly, with the key owner’s role on each.
listSpaceTrash READ The Trash view, with trashedAt. Trashed items are purged 30 days after trashing.
searchSpaceItems READ Case-insensitive substring search on names across everything the key owner can see; at most 50 results. Names only, not contents.
searchSpaces READ One search across every Library zone (files, Library, Data), grouped by zone, with each hit’s id, kind and app link. limit applies per zone (max 25).
listSpaceItemActivity READ A folder or file’s latest 50 events — created, renamed, moved, edited, shared, trashed, downloaded — and who did each.
listSpaceItemVersions READ A file’s saved versions (the newest 200), newest first, with who saved each and which is current.
getSpaceAccessList READ Who can open an item: its audience and each person it is shared with, with their role.

Records (READ scope)

operationId Scope What it does
listSpaceCalls READ Records › Calls, newest first. Filter by direction, contact, who handled the call, or contact name. Read one call with getCallRecording.
listSpaceContactFiles READ Records › Contact files: attachments and voicemails, newest first. Filter by contact, deal, channel, direction or name. Only files whose contact the key owner may open.

Reading file contents (READ scope)

operationId Scope What it does
getSpaceTextContent READ A text file’s content (up to 2 MB, truncated when cut), or every visible sheet of a workbook as CSV. Returned as data — never executed or rendered. Its versionId is the baseVersionId for saveSpaceTextFile.
getSpaceTextLines READ A text file’s lines, numbered (`N
searchSpaceText READ The numbered lines of one text file holding any of terms (case-insensitive), with a few lines of context around each match. Finds something in a long file in one read instead of paging.
readSpaceSheet READ A spreadsheet’s cells (.xlsx, CSV, TSV) by A1 range, one sheet at a time, formulas beside their values, 12,000 characters per page (nextStartRow). find keeps only rows containing some words. Reaches any row of a sheet up to 200,000 rows; its versionId is the baseVersionId for editSpaceSheetCells.

Creating and editing files (WRITE scope)

operationId Scope What it does
createSpaceFolder WRITE Create a folder in a space root or a folder the key owner can edit. A name already in use gets “ (2)“. creationKey makes a retry return the same folder.
createSpaceTextFile WRITE Save text as a new file (up to 5 MB). The name’s extension decides the type; binary types are refused.
saveSpaceTextFile WRITE Save new text as a file’s next version. Pass baseVersionId so a save over someone else’s newer version is refused instead of overwriting it.
insertSpaceTextLines WRITE Insert lines into a text file by line number, leaving every existing line as it was, as the next version.
editSpaceTextLines WRITE Replace, delete or move line ranges (and insert lines) by line number, all as one next version — for reorganizing a file too large to re-send whole.
editSpaceSheetCells WRITE Change spreadsheet cells by A1 address, or append rows, as one next version. Every other cell, sheet, format and size is kept and formulas are recomputed. An .xlsx whose save would drop charts, pivots, comments, tables, macros, validation, external links or data connections is refused.
describeSpaceItem WRITE Set or clear the short description shown under an item.
renameSpaceItem WRITE Rename a folder or file; refused when the name is taken in that folder.
restoreSpaceItemVersion WRITE Make an older version current again, as a new version — nothing is lost.
savePagePdf WRITE Print an app page to PDF as the key owner sees it and save it where their agent-made files go.
setAgentFilesFolder WRITE Choose where files an agent makes in the key owner’s chats are saved: a folder they can edit, or null for the root of My files.

Moving, copying and filing (WRITE scope)

operationId Scope What it does
moveSpaceItems WRITE Move up to 200 items, all or nothing. Needs edit access on both sides, and MANAGER when the move changes who can see an item (unless it was already open to the whole team).
copySpaceItem WRITE Copy a file (not folders). The copy belongs to the key owner and carries no sharing.
copyUploadedFileToSpace WRITE Copy an upload’s original file (listFiles uploads[].file.id) into a folder the key owner can edit — the app’s “Copy to My files”.
fileLibraryItemsOnContact WRITE Attach Library items to a contact’s files, as the contact’s Attach › From Library does: a snapshot copy of each file, and a page as its PDF.
fileLibraryItemsOnDeal WRITE The same for a deal’s files.

Sharing (WRITE scope)

operationId Scope What it does
setSpaceGrant WRITE Share an item (and everything in it) with an active teammate as VIEWER, EDITOR or MANAGER, or stop sharing with role: null. Needs MANAGER. Never shares outside the organization.
setSpaceAccessMode WRITE RESTRICTED closes an item to its owner and the people it is shared with; INHERIT reopens it to its folder’s audience, which can widen who sees it. Needs MANAGER.

Trash (WRITE scope)

operationId Scope What it does
trashSpaceItems WRITE Trash up to 200 items with everything in them. Restorable for 30 days.
restoreSpaceItems WRITE Restore trashed items to where they were, or to the space root if that folder is gone.
deleteSpaceItemsForever WRITE Permanently delete trashed items — rows, versions and bytes. Items not in the trash are refused.

Running a skip trace or tag on a Library file (READ + WRITE scopes)

A Library spreadsheet of properties can be skip traced or tagged, as the Files review in the app does. The run is mapped, previewed and confirmed: startLibraryFileRun → mapLibraryFileRun → previewLibraryFileRun (and reviseLibraryFileRun as needed) → confirmLibraryFileRun. Each step after the first takes the run’s fileProcessingTaskId, and every step takes skipTrace: true for a skip trace, false for a property tag.

operationId Scope What it does
startLibraryFileRun WRITE Start a run on a Library file (spaceItemId). Returns the run’s fileProcessingTaskId. Nothing runs yet.
mapLibraryFileRun WRITE Map the file’s columns with the import mapper (up to a few minutes). Returns the row count and the columns.
previewLibraryFileRun READ The first 1 to 10 rows as the run reads them — a skip trace’s lookups, or a tag’s properties — plus the row count.
reviseLibraryFileRun WRITE Change the mapping in plain words (message) and re-run the mapper.
confirmLibraryFileRun WRITE Run it. A skip trace adds the phones and emails it finds to the file as a new version; a tag puts the properties on tagName’s list. Starts in the background and returns at once.

Memory notes (READ + WRITE scopes)

Memory is what Goliath’s agents remember: notes on shelves for the key owner, the team, each AI employee, and each contact. A shelf holds subjects; a subject holds notes. See also the Memory API.

operationId Scope What it does
listMemoryShelves READ The shelves the key owner may open — their own, the team’s, AI employees’, and contacts’ (only contacts they may open in the CRM) — with how many subjects each holds.
listMemorySubjects READ One shelf’s subjects (AI employees or contacts) by name, with note counts. Cursor-paged.
getMemorySubjectNotes READ One subject’s notes in reading order, with their sources; retired: true returns the forgotten ones instead. Cursor-paged (after = endCursor).
addMemoryNote WRITE Add a pinned note to a shelf the key owner may open. Adding the same words again returns the existing note.
editMemoryNote WRITE Correct a note’s words. The correction is a new, pinned note with its own id.
pinMemoryNote WRITE Pin or unpin a note.
forgetMemoryNote WRITE Forget a note, with an optional reason.
restoreMemoryNote WRITE Bring a forgotten note back.
getMemoryDreamLog READ The newest 50 changes dreaming (the nightly memory pass) made to one subject. Each entry’s id is the eventId for undoMemoryDream.
undoMemoryDream WRITE Undo one dreaming change. On a waiting trust proposal it declines the step; raising a trust rung or ceiling and accepting a step stay in the app.
queueMemoryDream WRITE Queue a dreaming pass now for the key owner’s own shelf, outside the nightly run. Returns false when dreaming is off for the organization; other shelves are not available to keys.

Example

Find a spreadsheet by name, then read its first rows:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "searchSpaceItems", "variables": { "query": "probate leads" } }'
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "readSpaceSheet", "variables": { "itemId": "SPACE_ITEM_ID", "range": "A1:H50" } }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.