Gestell API Reference
Getting Started
The Gestell API can be accessed through REST and our SDK. We recommend using the SDK for Intellisense features that offer extensive code completion and typesystems for both Node and Python.
The SDKs support passing your API Key via a .env file or through your terminal session. You can generate a key through the Gestell Workspace.
Guides
If you are new to Gestell, we recommend reading our guides to get started quickly and seamlessly, we offer a variety of guides for both agent orchestration and sdk usage.
View the Gestell Guides
Organization
The Gestell Organization API provides programmatic access to manage organizations. It also enables granular control of organization membership through user management, role assignments, and permission modifications.
Organization Types
- UUID id: The Organization UUID
- String name: Display name of the organization
- String description: Brief description of the organization
- OrganizationPlan plan: Active subscription plan
- preview Evaluation tier with limited features
- developer Individual developer tier for testing or hobby projects
- starter Entry-level tier for small teams or startups
- scale Scaled tier for growing teams with increased usage
- enterprise Enterprise-grade tier with custom SLAs and support
- Status status: Operational status (e.g., "active", "suspended")
- Date dateCreated: Organization creation timestamp
- Date dateUpdated: Last update timestamp
Get Organization
Retrieves an organization by id
Accepts the following
id: String - Unique identifier of the organization to retrieve
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Organization
List Organizations
Lists all organizations you are a member of
Accepts the following
search?: String - Optional search term to filter organizations by name
take?: Number - Maximum number of organizations to return (default: 10, max: 100)
skip?: Number - Number of organizations to skip for pagination (default: 0)
extended?: Boolean - Whether to include extended organization details (default: false)
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Organization[]
Update Organization
Updates an organization
Accepts the following
organizationId: String - Unique identifier of the organization to update
name: String - New name for the organization
description: String - New description for the organization
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Add Members
Adds members to an organization
Accepts the following
organizationId: String - ID of the organization to add members to
members: MemberPayload[] - Array of member objects to add to the organization
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Remove Members
Remove members from an organization
Accepts the following
organizationId: String - ID of the organization to remove members from
members: String[] - Array of member IDs to remove from the organization
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Collection
The Collection API provides programmatic management of organizations within the Gestell ecosystem via REST and SDK interfaces, enabling creation, retrieval, editing, and deletion of collections.
Collection Types
- UUID id: Unique identifier for the collection
- UUID organizationId: Identifier of the parent organization
- String name: Display name of the collection
- CollectionType type: The type of the collection
- frame When you only want the OCR outputs
- searchable-frame Lighter version of canonized collections for search-based reasoning
- canon Complete canonized collection with best search-based reasoning capabilities
- features Specialized collection for category extractions of content
- String description: Description of the collection's purpose
- Boolean pii: Whether this collection contains PII data
- PiiType piiType: Classification of PII/PHI
- generic Standard personal data without specialized legal or health context
- legal Information with legal or regulatory implications (e.g., SSN, license numbers)
- medical Protected health information subject to medical privacy regulations
- PiiIdentifierOption[] piiControls: Array of PII identifier options for UI controls
- String[] tags: Tags associated with this collection for filtering/search
- String instructions: General instructions for collection usage
- String graphInstructions: Instructions specific to graph-based operations
- String promptInstructions: Instructions for prompt-based interactions
- String searchInstructions: Instructions for search operations
- Date dateCreated: Timestamp when the collection was created
- Date dateUpdated: Timestamp when the collection was last updated
Get Collection
Retrieves a collection by id
Accepts the following
collectionId: String - The ID of the collection to be retrieved
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Collection
List Collections
Lists all collections you are a member of
Accepts the following
search?: String - Search term to filter collections by name
take?: Number - Maximum number of collections to return (default: 10, max: 100)
skip?: Number - Number of collections to skip for pagination (default: 0)
extended?: Boolean - If true, returns extended collection details
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Collection[]
Create Collection
Create a new collection
Accepts the following
UUID organizationId: The ID of the organization that will own this collection
String name: The display name for the collection
CollectionType type: The type of collection being created
String[]? tags: Optional tags to categorize the collection
String? description: A description of the collection's purpose or contents
Boolean? pii: Indicates if the collection contains Personally Identifiable Information
PiiIdentifierOption[]? piiControls: Configuration for PII identification and handling
String? instructions: General instructions for processing this collection
String? graphInstructions: Specific instructions for graph operations
String? promptInstructions: Instructions for prompt generation
String? searchInstructions: Instructions for search operations
CreateCategoryPayload[]? categories: Initial set of categories to create
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
id: UUID
Update Collection
Update a collection
Accepts the following
UUID collectionId: The ID of the collection to update
UUID? organizationId: The ID of the organization that owns this collection
String? name: The new display name for the collection
CollectionType? type: The type of collection
String? description: A description of the collection's purpose or contents
Boolean? pii: Indicates if the collection contains Personally Identifiable Information
PiiIdentifierOption[]? piiControls: Configuration for PII identification and handling
String? instructions: General instructions for processing this collection
String? graphInstructions: Specific instructions for graph operations
String? promptInstructions: Instructions for prompt generation
String? searchInstructions: Instructions for search operations
String[]? tags: Tags to categorize the collection
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Delete Collection
Delete a collection. This will delete all documents in it. This action is not reversible.
Accepts the following
collectionId: String - The ID of the collection to be deleted
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Add Category
Add a new category to a Collection
Accepts the following
collectionId: UUID
name: String
type: Category Type
instructions: String
singleEntry: Boolean
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Update Category
Updates a category for a collection
Accepts the following
collectionId: UUID
name: String
type: Category Type
instructions: String
singleEntry: Boolean
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Remove Category
Remove a category from a Collection
Accepts the following
collectionId: String - The ID of the collection containing the category
categoryId: String - The ID of the category to be removed
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Query
This section provides an overview of the Gestell Query API, detailing its functions for searching, using prompts, retrieving features (labels), and accessing tables.
Query Types
Search Result
- String content: The content of the search result
- String citation: The citation of the search result
- String reason: The reason for the search result
Search Query
Searchs a collection
Accepts the following
collectionId: String - Identifier of the target collection
categoryId?: String - Optional category filter within the collection
prompt: String - Natural-language query or prompt
method?: SearchMethod - Desired search performance/accuracy mode
type?: SearchType - Desired output format of the search
vectorDepth?: Number - Number of vector hops to explore
nodeDepth?: Number - Number of node hops to explore
maxQueries?: Number - Maximum number of sub-queries to issue
maxResults?: Number - Maximum number of results to return
includeContent?: Boolean - Include full content in each result
includeEdges?: Boolean - Include edge references in each result
edgesInResult?: Boolean - Embed edge data within result objects
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Result[]
Prompt Query
Prompts a collection. Note that this returns a readable stream.
Accepts the following
collectionId: String - Identifier of the target collection
categoryId?: String - Optional category filter within the collection
prompt: String - Natural-language query or prompt
method?: SearchMethod - Desired search performance/accuracy mode
type?: SearchType - Desired output format of the search
vectorDepth?: Number - Number of vector hops to explore
nodeDepth?: Number - Number of node hops to explore
maxQueries?: Number - Maximum number of sub-queries to issue
maxResults?: Number - Maximum number of results to return
template?: String - Optional prompt instructions for the model
cot?: Boolean - Enable chain-of-thought reasoning (RECOMMENDED)
messages?: PromptMessage[] - Chat history and context in order (oldest to newest)
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Readable Stream
Feature Query
Returns data from a feature category
Accepts the following
collectionId: String - ID of the collection containing the features
categoryId: String - ID of the category to query features from
take?: Number - Maximum number of features to return (default: 10, max: 100)
skip?: Number - Number of features to skip for pagination (default: 0)
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: FeatureResult[]
Export Feature
Exports the data from a feature as either JSON or CSV
Accepts the following
collectionId: String - ID of the collection containing the features
categoryId: String - ID of the category to export features from
format?: 'json' | 'csv' - Output format (default: 'json')
skip?: Number - Number of features to skip for pagination (default: 0)
take?: Number - Maximum number of features to return (default: 100)
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: FeatureResult[] | string
Table Query
Returns data from a table category
Accepts the following
collectionId: UUID
categoryId: UUID
skip: Number defaults to 0
take: Number defaults to 10, max 100
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Record<string, string>
Export Table
Exports the data from a table as either JSON or CSV
Accepts the following
collectionId: String - ID of the collection containing the table data
categoryId: String - ID of the category to export table data from
format?: 'json' | 'csv' - Output format (default: 'json')
take?: Number - Maximum number of rows to return (default: 100)
skip?: Number - Number of rows to skip for pagination (default: 0)
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Record<string, string> | string
Document
The Gestell Document API facilitates document management, including creation, updates, deletion, and retrieval. It also enables users to view document layouts and job statuses.
Document Types
- String id: Unique identifier for the document
- String collectionId: Identifier of the parent collection
- String name: Human-readable name of the document (e.g., filename)
- String type: MIME type or custom type label of the document
- LayoutType layoutType: The layout parsing strategy applied
- Number layoutNodes: Number of layout nodes generated during parsing
- Boolean tables: Whether the document contains tables to be parsed
- String instructions: Custom instructions or notes for processing
- Job? job: Optional processing job associated with this document
- Layout[]? layout: Parsed layout structure, varying by layoutType
- DocumentLayout[] For text/image based documents
- PhotoLayout[] For images
- VideoLayout[] For videos
- AudioLayout[] For audio
- Object? metadata: File metadata
- Number size: File size in bytes
- Number pages: Number of pages (if applicable)
- Number length: Duration in seconds (for audio/video)
- Date dateCreated: Timestamp when the document was created
- Date dateUpdated: Timestamp when the document was last updated
Get Document
Retrieves a document by id
Accepts the following
collectionId: String - ID of the collection containing the document
documentId: String - ID of the document to retrieve
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Document
Export Document
Export a document as either JSON or raw text. Note that raw text will not export photo metadata from documents and you do not get precise positions of elements on the screen.
Accepts the following
collectionId: String - ID of the collection containing the document
documentId: String - ID of the document to export
type?: 'json' | 'text' - Format of the exported document (defaults to JSON)
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Document
List Document
Lists all documents within a collection
Accepts the following
collectionId: String - The unique identifier of the collection to query
search?: String - Optional text to search within document content or metadata
take?: Number - Number of documents to return (default: 10, max: 100)
skip?: Number - Number of documents to skip (default: 0)
extended?: Boolean - Whether to include extended document data (metadata and layout)
status?: JobStatus - Filter documents by overall enframing state
nodes?: JobStatus - Filter by status of the nodes indexing stage
edges?: JobStatus - Filter by status of the edges graph-building stage
vectors?: JobStatus - Filter by status of the vector generation stage
category?: JobStatus - Filter by status of the category generation stage
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Document[]
Update Document
Update a document
Accepts the following
collectionId: String - ID of the collection containing the document
documentId: String - ID of the document to update
name?: String - New name for the document
instructions?: String - Updated instructions or description
tables?: Boolean - Whether to perform additional OCR processing for tables
job?: Boolean - Whether to dispatch a background job for processing
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Upload Document
Upload a document. Accepts a buffer, path, in Node, it accepts the client side File type
Accepts the following
collectionId: String - ID of the collection to upload the document to
name: String - Name of the document
type?: String - MIME type (auto-detected if not provided)
file: String | Buffer | File - File content as path, Buffer, or File object
instructions?: String - Optional instructions for the upload
job?: Boolean - Whether to process upload as a background job
tables?: Boolean - Whether to include tables in the document
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Presign Document
Presigns a document to be uploaded to the Gestell Server
Accepts the following
collectionId: String - ID of the collection to upload the document to
filename: String - Filename for the document to be uploaded
type: String - MIME type of the document (e.g., application/pdf)
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
url: String
path: String
Create Document
After uploading a presigned document. Create the document as a record in the Gestell Database
Accepts the following
collectionId: String - ID of the collection to create the document in
name: String - Name of the new document
path: String - Path for the document
type: String - Document mime type (e.g., application/pdf)
instructions?: String - Optional instructions for document creation
job?: Boolean - Whether to run creation as a background job
tables?: Boolean - Whether to do additional table processing
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
id: UUID
Delete Document
Delete a document from a collection. This action is not reversible.
Accepts the following
collectionId: String - ID of the collection containing the document
documentId: String - ID of the document to delete
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Job
The Gestell Job API enables users to monitor job statuses and provides the ability to reprocess or cancel jobs as needed.
Get Job
Retrieves a job by its Collection and Document ID
Accepts the following
collectionId: String - ID of the collection containing the document
documentId: String - ID of the document to get job information for
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Job
List Jobs
Lists all jobs, can be filtered by its processing status
Accepts the following
collectionId: String - ID of the collection to list jobs from
status?: JobStatus - Filter jobs by enframing status
nodes?: JobStatus - Filter jobs by node processing status
edges?: JobStatus - Filter jobs by edge processing status
vectors?: JobStatus - Filter jobs by vector processing status
category?: JobStatus - Filter jobs by category processing status
search?: String - Search term to filter jobs
take?: Number - Maximum number of jobs to return (default: 10, max: 100)
skip?: Number - Number of jobs to skip for pagination (default: 0)
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: Job[]
Reprocess Jobs
Reprocesses documents based on their document ids
Accepts the following
collectionId: String - ID of the collection containing the documents
ids: String[] - Array of document IDs to reprocess
type: JobType - Type of reprocessing to perform
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Cancel Jobs
Cancels jobs via their document id
Accepts the following
collectionId: String - ID of the collection containing the jobs
ids: String[] - Array of Document IDs to cancel jobs for
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable