Project Files

Upload, organize, search, and manage project files.

POST

Restore an item from trash

/organizations/{organizationId}/projects/{projectId}/files/trash/{itemId}/restore

Restores a previously soft-deleted file or folder from the file trash back to the file manager. For folders, optionally restores all contained files and subfolders. Requires specifying the item type (file or folder) in the request body. Returns counts of restored files and folders for folder-type items.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

itemIdRequired

path · string

BodyRequired

typeRequired

union

restoreContents

boolean

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const result = await gc.projectFiles.restoreFileTrashItem({9  organizationId: org.id,10  projectId: projects[0].id,11  itemId: "item-123",12  data: {}13});14

GET

List places where a file is referenced

/organizations/{organizationId}/projects/{projectId}/files/{fileId}/references

Returns a comprehensive list of all entities that reference this file across the project. This includes pages, headers, footers, blog posts, templates, sidebars, dialogs, forms, and branding settings. Useful for understanding the impact of deleting or replacing a file.

Parameters

page

query · numberPage number to return, 1-indexed. Defaults to 1.

pageSize

query · numberItems per page (1-100). Defaults to 10.

lite

query · stringWhen 'true', return only essential fields (id, slug, title/name) to reduce payload size. Useful for context fetching and link resolution.

sort

query · stringSort specifier as 'field:direction'. Sortable fields: name, type. Direction is 'asc' or 'desc' and defaults to 'asc'.

query · stringFree-text search. Matched against: name.

type

query · stringFilter by type. Operators: type=value (equals), type_ne, type_gt, type_gte, type_lt, type_lte, type_like (contains), type_isnull=true|false, type_has=value (jsonb array contains), type[]=a&type[]=b (in).

query · stringFilter by id. Operators: id=value (equals), id_ne, id_gt, id_gte, id_lt, id_lte, id_like (contains), id_isnull=true|false, id_has=value (jsonb array contains), id[]=a&id[]=b (in).

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

fileIdRequired

path · stringFile ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const { references } = await gc.projectFiles.listFileReferences({9  organizationId: org.id,10  projectId: projects[0].id,11  fileId: "your-file-id",12});13

GET

Get one folder's name and parent; use listFiles with folderId to see its files

/organizations/{organizationId}/projects/{projectId}/files/folders/{folderId}

Retrieves the details of a single folder in the project file manager, including its name, parent folder ID, and creation metadata.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

folderIdRequired

path · stringFolder ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const folder = await gc.projectFiles.getFileFolder({9  organizationId: org.id,10  projectId: projects[0].id,11  folderId: "folder-123",12});13

DELETE

Delete a file folder (files are moved to root)

/organizations/{organizationId}/projects/{projectId}/files/folders/{folderId}

Soft-deletes a folder and all its contents (files and subfolders) by moving them to the file trash. The folder and its contents can be restored from trash before permanent deletion. Returns a count of deleted folders and files.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

folderIdRequired

path · stringFolder ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const result = await gc.projectFiles.deleteFileFolder({9  organizationId: org.id,10  projectId: projects[0].id,11  folderId: "folder-123",12});13

PUT

Replace a text file's content in place; id, URL and references stay unchanged

/organizations/{organizationId}/projects/{projectId}/files/{fileId}/content

Replaces the content of an existing text file. The file must be a text-based type (Markdown, plain text, CSV, JSON, YAML, HTML, CSS, JS, XML, SVG). The file's storage object is overwritten, its size is updated, and AI embeddings are re-generated from the new content. The file ID, URL, metadata, and all references remain unchanged.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

fileIdRequired

path · stringFile ID

BodyRequired

contentRequired

stringThe new text content for the file. Replaces the existing content entirely. The file must be a text-based type (Markdown, plain text, CSV, JSON, YAML, HTML, CSS, JS, XML, SVG).

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const result = await gc.projectFiles.replaceFileContent({9  organizationId: org.id,10  projectId: projects[0].id,11  fileId: "file-123",12  data: "new file content",13});14

DELETE

Permanently delete an item from trash

/organizations/{organizationId}/projects/{projectId}/files/trash/{itemId}

Permanently and irreversibly deletes a file or folder from the file trash. For files, also removes the file from cloud storage. For folders, recursively deletes all contained files and subfolders. Requires specifying the item type (file or folder) in the request body.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

itemIdRequired

path · string

BodyRequired

typeRequired

union

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const { id: organizationId } = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId });7
8const result = await gc.projectFiles.permanentDeleteFileTrashItem({9  organizationId,10  projectId: projects[0].id,11  itemId: "item-123",12  data: {}13});14

GET

Open a file's content inline: text as string, images as base64, 10 MB cap

/organizations/{organizationId}/projects/{projectId}/files/{fileId}/open

Returns the actual content of a file inline — text as a string, images as base64. Use this when you need to read or analyze a file's content rather than just its metadata. Text files (Markdown, CSV, JSON, YAML, plain text, HTML, CSS, JS, XML, SVG) are returned in the 'content' field. Image files (PNG, JPG, GIF, WebP) are returned as base64 in the 'base64Content' field. Files over 10 MB or unsupported types return 404.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

fileIdRequired

path · stringFile ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const file = await gc.projectFiles.openFile({9  organizationId: org.id,10  projectId: projects[0].id,11  fileId: "target-file-id",12});13

POST

Empty trash (permanently delete old items)

/organizations/{organizationId}/projects/{projectId}/files/trash/empty

Permanently deletes all items from the file trash, optionally filtering to only delete items older than a specified number of days. Removes files from cloud storage and recursively deletes folder contents. Returns counts of deleted files and folders.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

BodyRequired

olderThanDays

integer

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const result = await gc.projectFiles.emptyFileTrash({9  organizationId: org.id,10  projectId: projects[0].id,11  data: {}12});13

GET

Get one file's metadata only (URL, type, size, folder); openFile returns the content

/organizations/{organizationId}/projects/{projectId}/files/{fileId}

Retrieves the full details of a single file in the project file manager, including its filename, MIME type, size, dimensions, storage URL, alt text, caption, and folder assignment.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

fileIdRequired

path · stringFile ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const file = await gc.projectFiles.getFile({9  organizationId: org.id,10  projectId: projects[0].id,11  fileId: "file-123",12});13

DELETE

Delete a file

/organizations/{organizationId}/projects/{projectId}/files/{fileId}

Soft-deletes a file from the project file manager by moving it to the file trash. The file can be restored from trash before it is permanently deleted. Also removes the file from cloud storage if permanently deleted later.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

fileIdRequired

path · stringFile ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const result = await gc.projectFiles.deleteFile({9  organizationId: org.id,10  projectId: projects[0].id,11  fileId: "file-123",12});13

GET

List file folders in a project

/organizations/{organizationId}/projects/{projectId}/files/folders

Returns all folders in the project file manager. Filter by parentId to list only the children of one folder, or parentId_isnull=true for the project root. Omit both to list every folder in the project. Folders are used to organize uploaded files (images, documents, media).

Parameters

page

query · numberPage number to return, 1-indexed. Defaults to 1.

pageSize

query · numberItems per page (1-100). Defaults to 10.

lite

query · stringWhen 'true', return only essential fields (id, slug, title/name) to reduce payload size. Useful for context fetching and link resolution.

sort

query · stringSort specifier as 'field:direction'. Sortable fields: name, slug, createdAt, updatedAt. Direction is 'asc' or 'desc' and defaults to 'asc'.

query · stringFree-text search. Matched against: name, slug.

parentId

query · stringFilter by parentId. Operators: parentId=value (equals), parentId_ne, parentId_gt, parentId_gte, parentId_lt, parentId_lte, parentId_like (contains), parentId_isnull=true|false, parentId_has=value (jsonb array contains), parentId[]=a&parentId[]=b (in).

name

query · stringFilter by name. Operators: name=value (equals), name_ne, name_gt, name_gte, name_lt, name_lte, name_like (contains), name_isnull=true|false, name_has=value (jsonb array contains), name[]=a&name[]=b (in).

createdBy

query · stringFilter by createdBy. Operators: createdBy=value (equals), createdBy_ne, createdBy_gt, createdBy_gte, createdBy_lt, createdBy_lte, createdBy_like (contains), createdBy_isnull=true|false, createdBy_has=value (jsonb array contains), createdBy[]=a&createdBy[]=b (in).

createdAt

query · stringFilter by createdAt. Operators: createdAt=value (equals), createdAt_ne, createdAt_gt, createdAt_gte, createdAt_lt, createdAt_lte, createdAt_like (contains), createdAt_isnull=true|false, createdAt_has=value (jsonb array contains), createdAt[]=a&createdAt[]=b (in).

updatedAt

query · stringFilter by updatedAt. Operators: updatedAt=value (equals), updatedAt_ne, updatedAt_gt, updatedAt_gte, updatedAt_lt, updatedAt_lte, updatedAt_like (contains), updatedAt_isnull=true|false, updatedAt_has=value (jsonb array contains), updatedAt[]=a&updatedAt[]=b (in).

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const { folders } = await gc.projectFiles.listFileFolders({9  organizationId: org.id,10  projectId: projects[0].id,11});12

GET

Search file contents by meaning; returns matching snippet and relevance score per file

/organizations/{organizationId}/projects/{projectId}/files/search

Searches project files by their content using semantic/AI search. Returns files whose content matches the meaning of the query, along with the matching content snippet and a relevance score.

Parameters

page

query · numberPage number to return, 1-indexed. Defaults to 1.

pageSize

query · numberItems per page (1-100). Defaults to 10.

lite

query · stringWhen 'true', return only essential fields (id, slug, title/name) to reduce payload size. Useful for context fetching and link resolution.

sort

query · stringSort specifier as 'field:direction'. Sortable fields: similarity, filename, mimeType. Direction is 'asc' or 'desc' and defaults to 'asc'.

query · stringFree-text search. Matched against: filename, originalFilename, matchingContent.

mimeType

query · stringFilter by mimeType. Operators: mimeType=value (equals), mimeType_ne, mimeType_gt, mimeType_gte, mimeType_lt, mimeType_lte, mimeType_like (contains), mimeType_isnull=true|false, mimeType_has=value (jsonb array contains), mimeType[]=a&mimeType[]=b (in).

similarity

query · stringFilter by similarity. Operators: similarity=value (equals), similarity_ne, similarity_gt, similarity_gte, similarity_lt, similarity_lte, similarity_like (contains), similarity_isnull=true|false, similarity_has=value (jsonb array contains), similarity[]=a&similarity[]=b (in).

filename

query · stringFilter by filename. Operators: filename=value (equals), filename_ne, filename_gt, filename_gte, filename_lt, filename_lte, filename_like (contains), filename_isnull=true|false, filename_has=value (jsonb array contains), filename[]=a&filename[]=b (in).

queryRequired

query · stringSemantic search query

limit

query · number

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const { files } = await gc.projectFiles.searchFiles({9  organizationId: org.id,10  projectId: projects[0].id,11  query: "search term",12});13

GET

List a project's trashed files and folders, restorable until permanently deleted

/organizations/{organizationId}/projects/{projectId}/files/trash

Returns all soft-deleted files and folders currently in the project's file trash. Items remain in trash until they are restored or permanently deleted. Each item includes its original metadata and the date it was trashed.

Parameters

page

query · numberPage number to return, 1-indexed. Defaults to 1.

pageSize

query · numberItems per page (1-100). Defaults to 10.

lite

query · stringWhen 'true', return only essential fields (id, slug, title/name) to reduce payload size. Useful for context fetching and link resolution.

sort

query · stringSort specifier as 'field:direction'. Sortable fields: name, deletedAt, sizeBytes, type. Direction is 'asc' or 'desc' and defaults to 'asc'.

query · stringFree-text search. Matched against: name.

type

mimeType

parentId

deletedBy

query · stringFilter by deletedBy. Operators: deletedBy=value (equals), deletedBy_ne, deletedBy_gt, deletedBy_gte, deletedBy_lt, deletedBy_lte, deletedBy_like (contains), deletedBy_isnull=true|false, deletedBy_has=value (jsonb array contains), deletedBy[]=a&deletedBy[]=b (in).

deletedAt

query · stringFilter by deletedAt. Operators: deletedAt=value (equals), deletedAt_ne, deletedAt_gt, deletedAt_gte, deletedAt_lt, deletedAt_lte, deletedAt_like (contains), deletedAt_isnull=true|false, deletedAt_has=value (jsonb array contains), deletedAt[]=a&deletedAt[]=b (in).

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const { trash } = await gc.projectFiles.listFileTrash({9  organizationId: org.id,10  projectId: projects[0].id,11});

POST

Save a file from text or image content

/organizations/{organizationId}/projects/{projectId}/files/save

Saves a file to the project from raw text content (Markdown, Mermaid, CSV, JSON, YAML, plain text, etc.) or base64-encoded binary data — images (PNG, JPG, GIF, WebP, SVG) and documents alike (PDF, Word, Excel), with document text extracted and embedded exactly as a console upload would. The file is stored in the project and processed for AI embeddings (text) or image classification (images). Use this to save documents, notes, diagrams, structured data, or screenshots into the project knowledge base.

Parameters

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

BodyRequired

title

stringDisplay title for the file.

content

stringThe text content of the file. Supports plain text, Markdown, Mermaid diagrams, CSV, JSON, YAML, and other text-based formats. Use this OR base64Content.

filenameRequired

stringFilename with extension (e.g. 'notes.md', 'diagram.mmd', 'data.csv', 'screenshot.png'). The extension determines how the file is stored and processed.

folderId

stringTarget folder ID. Files are placed in the root if omitted. Takes precedence over folderPath.

isPublic

booleanWhether this file should be publicly accessible. Public files can be embedded in websites and viewed by public RAG surfaces when their grounding mode is allowed. Private files are only accessible to authenticated project members. Defaults to false for this endpoint. If grounding='context', this is coerced to true because context is public shaping material.

mimeType

stringMIME type of the content. Inferred from filename extension if not provided. Common values: text/plain, text/markdown, text/csv, application/json, text/yaml, image/png, image/jpeg.

grounding

unionHow the AI should use this file's content. Ask the user before choosing. 'fact' (default) = content the AI can cite verbatim (prices, testimonials, team bios, product specs, support docs). 'context' = public background that shapes AI-generated content but is never quoted directly (competitive research, market positioning, brand voice, strategy docs safe for public-page generation). If grounding='context', isPublic is coerced to true.

folderPath

stringSlash-delimited folder path (e.g. 'business/competitors'). Each segment is get-or-created under the prior level. Ignored if folderId is provided.

description

stringHuman-authored description of the file's content. Combined with AI vision classification to produce richer embeddings. Especially useful for screenshots and diagrams where the AI may describe the visual chrome rather than the semantic meaning.

base64Content

stringBase64-encoded binary content. Use this OR content. Images (PNG, JPG, GIF, WebP, SVG) get variants, AI classification and auto-populated alt text and caption. DOCUMENTS ARE ALSO ACCEPTED — PDF, Word (.docx, .doc), Excel (.xlsx, .xls) — and their text is extracted and embedded into the knowledge base exactly as a console upload would. Set mimeType accordingly (application/pdf, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) or let it be inferred from the filename extension. Base64 costs roughly one token per three bytes of file, so this is bounded by what the caller can afford to hold, not by the format.

permissionGroup

stringOptional RBAC group identifier. Plumbed for future enforcement but not yet gated at retrieval.

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const result = await gc.projectFiles.saveFile({9  organizationId: org.id,10  projectId: projects[0].id,11  data: { filename: "example.txt", content: "Hello World" }12});13

GET

List a project's files, with search, filtering and sorting

/organizations/{organizationId}/projects/{projectId}/files

Returns a paginated list of files (images, documents, media) uploaded to the project file manager. Search matches filename, original filename, title and description. Filter with folderId (folderId_isnull=true for the project root), mimeType (mimeType_like=image/ for every image), isPublic and grounding.

Parameters

page

query · numberPage number to return, 1-indexed. Defaults to 1.

pageSize

query · numberItems per page (1-100). Defaults to 10.

lite

query · stringWhen 'true', return only essential fields (id, slug, title/name) to reduce payload size. Useful for context fetching and link resolution.

sort

query · stringSort specifier as 'field:direction'. Sortable fields: filename, originalFilename, mimeType, sizeBytes, title, uploadedAt, updatedAt. Direction is 'asc' or 'desc' and defaults to 'asc'.

query · stringFree-text search. Matched against: filename, originalFilename, title, description.

isPublic

query · stringFilter by isPublic. Operators: isPublic=value (equals), isPublic_ne, isPublic_gt, isPublic_gte, isPublic_lt, isPublic_lte, isPublic_like (contains), isPublic_isnull=true|false, isPublic_has=value (jsonb array contains), isPublic[]=a&isPublic[]=b (in).

grounding

query · stringFilter by grounding. Operators: grounding=value (equals), grounding_ne, grounding_gt, grounding_gte, grounding_lt, grounding_lte, grounding_like (contains), grounding_isnull=true|false, grounding_has=value (jsonb array contains), grounding[]=a&grounding[]=b (in).

mimeType

folderId

query · stringFilter by folderId. Operators: folderId=value (equals), folderId_ne, folderId_gt, folderId_gte, folderId_lt, folderId_lte, folderId_like (contains), folderId_isnull=true|false, folderId_has=value (jsonb array contains), folderId[]=a&folderId[]=b (in).

organizationIdRequired

path · stringOrganization ID

projectIdRequired

path · stringProject ID

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const org = await gc.organizations.getOrganizationBySlug({ slug: "my-org" });6const { projects } = await gc.projects.listProjects({ organizationId: org.id });7
8const { files } = await gc.projectFiles.listFiles({9  organizationId: org.id,10  projectId: projects[0].id,11});12

BuiltAutonomously With AI

This content was built autonomously. Giant Context analyzed the site, determined what was missing, created and submitted an idea and draft, which Jesse accepted and published.