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
View the Gestell API Guide
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: The Organization Name
- String description: The Organization Description
- Member[] members: The Organization Members
- Collections[] collections: The Organization Collections
- Date dateCreated
- Date dateUpdated
Get Organization
Retrieves an organization by id
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
skip?: Number defaults to zero
take?: Number defaults to 10, max 100
search?: String filter by name
extended?: Boolean returns an extended dataset with collections included
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
id: UUID
name: String
description: String
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
id: UUID
members: MemberPayload[]
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
id: UUID
members: String[]
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: The Collection UUID
- UUID organizationId: The Organization UUID
- Organization organization: The Organization info
- String name: The Collection name
- Type type: The Collection type
- frame Extract document contents only
- searchable-frame Simple search for document contents
- canon A canonized collection, which enables collection documents to be searched, categorized and indexed
- features Extract and structure documents only, Which include features (labels) or tables
- String[] tags: Unique tag identifiers for the Collection
- String instructions: Instructions for Gestell to process the Collection documents
- String graphInstructions: Instructions for Gestell to graph the Collection documents
- String promptInstructions: Instructions for how to respond in prompts
- String searchInstructions: Instructions for Gestell on how to index documents for search
- Category[] categories: Categories for the collection
- Document[] documents: The documents in the collection
- Date dateCreated
- Date dateUpdated
Get Collection
Retrieves a collection by id
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
skip?: Number defaults to zero
take?: Number defaults to 10, max 100
search?: String filter by name
tag?: String filter by tag
extended?: Boolean returns an extended dataset with documents included
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
organizationId: UUID
name: String
description?: String
tags?: String[]
type: Collection Type
instructions?: String
graphInstructions?: String
promptInstructions?: String
searchInstructions?: String
categories?: CategoryPayload[]
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
collectionId: UUID
organizationId: UUID
name?: String
description?: String
type?: Collection Type
instructions?: String
graphInstructions?: String
promptInstructions?: String
searchInstructions?: String
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: UUID
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
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
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: UUID
categoryId: UUID
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
- UUID collectionId: The Collection UUID
- UUID categoryId: The Category UUID (Optional)
- String prompt: The search prompt
- Type method: The search method (Optional)
- fast Fast search
- normal Normal search
- precise Precise search
- Type type: The search type (Optional)
- summary Summary search
- phrase Phrase search
- keywords Keywords search
- Number vectorDepth: The vector depth (Optional)
- Number nodeDepth: The node depth (Optional)
- Number maxQueries: The maximum number of queries (Optional)
- Number maxResults: The maximum number of results (Optional)
- Boolean includeContent: Include content in the search results (Optional)
- Boolean includeEdges: Include edges in the search results (Optional)
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: UUID
categoryId?: UUID
prompt: String
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: UUID
categoryId?: UUID
messages: Message[]
prompt: String
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: 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: FeatureResult[]
Export Feature
Exports the data from a feature as either JSON or CSV
Accepts the following
collectionId: UUID
categoryId: UUID
type: json or csv
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: FeatureResult[]
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: TableResult[]
Export Table
Exports the data from a table as either JSON or CSV
Accepts the following
collectionId: UUID
categoryId: UUID
type: json or csv
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
result: FeatureResult[]
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: The unique identifier of the document.
- String collectionId: The ID of the collection this document belongs to.
- String path: The path to the document.
- String name: The name of the document.
- String type: The type of the document.
- String layoutType: The layout type of the document.
- Number layoutNodes: The number of layout nodes in the document.
- String instructions: Instructions for processing this document.
- Job job: The job associated with this document.
- Layout[] layout: The layout of the document.
- DocumentLayout[] Document Layout: An array of document layout objects.
- PhotoLayout[] Photo Layout: An array of photo layout objects.
- VideoLayout[] Video Layout: An array of video layout objects.
- AudioLayout[] Audio Layout: An array of audio layout objects.
- String dateCreated: The date the document was created.
- String dateUpdated: The date the document was last updated.
Get Document
Retrieves a document by id
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
type: text or 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: UUID
skip?: Number defaults to zero
take?: Number defaults to 10, max 100
search?: String filter by name
extended?: Boolean returns an extended dataset with document layouts included
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: UUID
documentId: UUID
name: String
instructions: String
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: UUID
name: String
type?: Content Type only required if providing a buffer
file: Buffer or File Path or File
instructions: String
job: Boolean
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
filename: String
type: Content Type
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: UUID
name: String
path: String
type: Content Type
instructions?: String
job?: Boolean
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: UUID
documentId: UUID
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
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
skip?: Number defaults to zero
take?: Number defaults to 10, max 100
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: UUID
ids: String[]
type: Job Type
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable
Cancel Jobs
Cancels jobs based on their job id
Accepts the following
collectionId: UUID
ids: String[]
Which returns the following
status: OK or ERROR
message?: a message describing an error if applicable