Project Files

Upload, organize, search, and manage project files.

POST

Restore an item from trash

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

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string
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 { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7
8const result = await gc.projectFiles.restoreFileTrashItem({9  organizationId: orgs[0].id,10  projectId: projects[0].id,11  itemId: "item-id",12  data: {}13});14

GET

List places where a file is referenced

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

Parameters

page: query · number
pageSize: query · number
lite: query · string
sort: query · string
search: query · string
type: query · string
id: query · string
organizationIdRequired: path · string
projectIdRequired: path · string
fileIdRequired: path · string

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7
8const { references } = await gc.projectFiles.listFileReferences({9  organizationId: orgs[0].id,10  projectId: projects[0].id,11  fileId: "file_123",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}

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string
folderIdRequired: path · string

SDK

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

DELETE

Delete a file folder (files are moved to root)

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

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string
folderIdRequired: path · string

SDK

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

PUT

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

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

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string
fileIdRequired: path · string

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 { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7
8const result = await gc.projectFiles.replaceFileContent({9  organizationId: orgs[0].id,10  projectId: projects[0].id,11  fileId: "your-file-id",12  data: "new-file-content",13});14

DELETE

Permanently delete an item from trash

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

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string
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 { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7
8const result = await gc.projectFiles.permanentDeleteFileTrashItem({9  organizationId: orgs[0].id,10  projectId: projects[0].id,11  itemId: "item-id",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

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string
fileIdRequired: path · string

SDK

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

POST

Empty trash (permanently delete old items)

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

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string

BodyRequired

olderThanDays: integer

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7
8const result = await gc.projectFiles.emptyFileTrash({9  organizationId: orgs[0].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}

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string
fileIdRequired: path · string

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7const { files } = await gc.projectFiles.listProjectFiles({8  organizationId: orgs[0].id,9  projectId: projects[0].id,10});11
12const { file } = await gc.projectFiles.getFile({13  organizationId: orgs[0].id,14  projectId: projects[0].id,15  fileId: files[0].id,16});17

DELETE

Delete a file

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

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string
fileIdRequired: path · string

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7
8const response = await gc.projectFiles.deleteFile({9  organizationId: orgs[0].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

Parameters

page: query · number
pageSize: query · number
lite: query · string
sort: query · string
search: query · string
parentId: query · string
name: query · string
createdBy: query · string
createdAt: query · string
updatedAt: query · string
organizationIdRequired: path · string
projectIdRequired: path · string

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7
8const { folders } = await gc.projectFiles.listFileFolders({9  organizationId: orgs[0].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

Parameters

page: query · number
pageSize: query · number
lite: query · string
sort: query · string
search: query · string
mimeType: query · string
similarity: query · string
filename: query · string
queryRequired: query · string
limit: query · number
organizationIdRequired: path · string
projectIdRequired: path · string

SDK

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

GET

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

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

Parameters

page: query · number
pageSize: query · number
lite: query · string
sort: query · string
search: query · string
type: query · string
mimeType: query · string
parentId: query · string
deletedBy: query · string
deletedAt: query · string
organizationIdRequired: path · string
projectIdRequired: path · string

SDK

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

POST

Save a file from text or image content

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

Parameters

organizationIdRequired: path · string
projectIdRequired: path · string

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 { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7
8const result = await gc.projectFiles.saveFile({9  organizationId: orgs[0].id,10  projectId: projects[0].id,11  data: "file content",12});13

GET

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

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

Parameters

page: query · number
pageSize: query · number
lite: query · string
sort: query · string
search: query · string
isPublic: query · string
grounding: query · string
mimeType: query · string
folderId: query · string
organizationIdRequired: path · string
projectIdRequired: path · string

SDK

1import { createGiantContext } from "@giantcontext/sdk-typescript";2
3const gc = createGiantContext({ apiKey: process.env.GIANTCONTEXT_API_KEY! });4
5const { organizations: orgs } = await gc.me.listMyOrganizations();6const { projects } = await gc.projects.listProjects({ organizationId: orgs[0].id });7
8const { files } = await gc.projectFiles.listFiles({9  organizationId: orgs[0].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 Giant Context staff accepted and published.