openapi: 3.0.0 info: title: GroundX API description: Ground Your RAG Apps in Fact not Fiction version: 1.0.0 contact: email: support@groundx.ai license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - description: GroundX Base URL url: https://api.groundx.ai/api tags: - name: Document - name: Project - name: Bucket - name: Preprocessor - name: Inventory - name: Search - name: API Key Management paths: /v1/apikey: get: tags: - API Key Management summary: Get API keys operationId: ApiKeyManagement_list description: Retrieve the API keys for the authenticated user. responses: '200': description: Successful retrieval of API keys content: application/json: schema: $ref: '#/components/schemas/ApiKeyManagementListResponse' '401': description: Unauthorized '403': description: Forbidden /v1/inventory: get: tags: - Inventory summary: searches inventory operationId: Inventory_search description: | By passing in the appropriate options, you can search for available inventory in the system parameters: - description: pass an optional search string for looking up inventory in: query name: searchString required: false schema: type: string - description: number of records to skip for pagination in: query name: skip schema: type: integer format: int32 minimum: 0 - description: maximum number of records to return in: query name: limit schema: type: integer format: int32 minimum: 0 maximum: 50 responses: '200': description: search results matching criteria content: application/json: schema: $ref: '#/components/schemas/InventorySearchResponse' '400': description: bad input parameter post: tags: - Inventory summary: adds an inventory item operationId: Inventory_add description: Adds an item to the system requestBody: description: Inventory item to add content: application/json: schema: $ref: '#/components/schemas/InventoryItem' responses: '201': description: item created '400': description: invalid input, object invalid '409': description: an existing item already exists /v1/project/{projectId}: post: tags: - Project summary: Bound project and bucket operationId: Project_bindBucket description: Bind a specific bucket to a project. parameters: - description: The ID of the project to bind the bucket to. name: projectId in: path required: true schema: type: integer requestBody: description: The bucket ID to bind to the project. required: true content: application/json: schema: $ref: '#/components/schemas/ProjectBucketBinding' responses: '200': description: Successful binding of project and bucket. '400': description: Invalid request data. '401': description: Unauthorized. '403': description: Forbidden. get: tags: - Project summary: Look up an existing project operationId: Project_get description: This endpoint allows you to retrieve a specific project by projectId. parameters: - description: The ID of the project to retrieve. in: path name: projectId required: true schema: type: string responses: '200': description: Successful retrieval of project content: application/json: schema: $ref: '#/components/schemas/ProjectResponse' put: tags: - Project summary: Update an existing project operationId: Project_update description: This endpoint allows you to update an existing project. parameters: - description: The ID of the project to update. in: path name: projectId required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProjectUpdateRequest' responses: '200': description: Successful update of project content: application/json: schema: $ref: '#/components/schemas/ProjectResponse' delete: tags: - Project summary: Delete an existing project operationId: Project_delete description: This endpoint allows you to delete your existing projects. parameters: - description: The ID of the project to delete. in: path name: projectId required: true schema: type: string responses: '200': description: Successful deletion of project content: application/json: schema: $ref: '#/components/schemas/ProjectDeleteResponse' /v1/project: get: tags: - Project summary: Look up existing projects operationId: Project_list description: This endpoint allows you to retrieve your existing projects. responses: '200': description: Successful retrieval of projects content: application/json: schema: $ref: '#/components/schemas/ProjectListResponse' post: tags: - Project summary: Create a project operationId: Project_create description: This endpoint allows you to initialize a new project. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProjectCreateRequest' responses: '200': description: Successful creation of project content: application/json: schema: $ref: '#/components/schemas/ProjectResponse' /v1/bucket/{bucketId}: get: tags: - Bucket summary: Look up an existing bucket operationId: Bucket_get description: Look up a bucket by its bucketId. parameters: - description: The ID of the bucket to retrieve. in: path name: bucketId required: true schema: type: integer responses: '200': description: Look up success content: application/json: schema: $ref: '#/components/schemas/BucketResponse' '400': description: Invalid bucket ID '401': description: Permission denied put: tags: - Bucket summary: Update an existing bucket operationId: Bucket_update description: Update the configurations of an existing bucket. parameters: - description: The ID of the bucket to update. in: path name: bucketId required: true schema: type: integer requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BucketUpdateRequest' responses: '200': description: Bucket successfully updated content: application/json: schema: $ref: '#/components/schemas/BucketResponse' '400': description: Invalid body parameter '401': description: Permission denied delete: tags: - Bucket summary: Delete an existing bucket operationId: Bucket_delete description: Deletes a bucket by bucketId. parameters: - description: The ID of the bucket to delete. in: path name: bucketId required: true schema: type: integer responses: '200': description: Bucket successfully deleted content: application/json: schema: $ref: '#/components/schemas/BucketDeleteResponse' '400': description: Invalid bucket ID '401': description: Permission denied /v1/bucket: get: tags: - Bucket summary: Look up existing buckets operationId: Bucket_list description: Look up existing buckets associated with your account. responses: '200': description: Look up success content: application/json: schema: $ref: '#/components/schemas/BucketListResponse' '401': description: Permission denied post: tags: - Bucket summary: Create a bucket operationId: Bucket_create description: Create a new bucket for your content. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BucketCreateRequest' responses: '200': description: Bucket successfully created content: application/json: schema: $ref: '#/components/schemas/BucketResponse' '400': description: Invalid body parameter '401': description: Permission denied /v1/ingest/document/{documentId}: get: tags: - Document summary: Look up an existing document operationId: Document_get parameters: - name: documentId in: path required: true schema: type: string responses: '200': description: Look up success content: application/json: schema: $ref: '#/components/schemas/DocumentResponse' '400': description: Invalid document ID '401': description: Permission denied delete: tags: - Document summary: Delete documents operationId: Document_delete parameters: - name: documentId in: path required: true schema: type: string responses: '200': description: Documents successfully deleted content: application/json: schema: $ref: '#/components/schemas/DocumentDeleteResponse' '400': description: Invalid document ID '401': description: Permission denied /v1/ingest/documents/remote: post: tags: - Document summary: Upload hosted documents to GroundX operationId: Document_uploadRemote requestBody: content: application/json: schema: $ref: '#/components/schemas/DocumentRemoteUploadRequest' responses: '200': description: Documents successfully uploaded content: application/json: schema: $ref: '#/components/schemas/IngestResponse' '400': description: Invalid document type or source URL '401': description: Permission denied /v1/ingest/documents/local: post: tags: - Document summary: Upload local documents to GroundX operationId: Document_uploadLocal requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/DocumentLocalUploadRequest' responses: '200': description: Documents successfully uploaded content: application/json: schema: $ref: '#/components/schemas/IngestResponse' '400': description: Invalid document type or source URL '401': description: Permission denied /v1/ingest/documents: get: tags: - Document summary: Look up all existing documents operationId: Document_list responses: '200': description: Look up success content: application/json: schema: $ref: '#/components/schemas/DocumentListResponse' '401': description: Permission denied /v1/ingest/documents/{id}: get: tags: - Document summary: Look up existing documents by processId, bucketId, or projectId operationId: Document_lookup parameters: - name: id in: path required: true schema: type: string responses: '200': description: Look up success content: application/json: schema: $ref: '#/components/schemas/DocumentLookupResponse' '401': description: Permission denied /v1/ingest/{processId}: get: tags: - Document summary: Look up document processing status by processId operationId: Document_getProcessingStatusByProcessId parameters: - name: processId in: path required: true schema: type: string responses: '200': description: Look up success content: application/json: schema: $ref: '#/components/schemas/ProcessStatusResponse' '401': description: Permission denied /v1/preprocess: post: tags: - Preprocessor summary: Setup Custom Pre-Processor operationId: Preprocessor_setup description: >- Initializes a custom pre-processor that can be applied to your content and search queries. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PreprocessorSetupRequest' multipart/form-data: schema: $ref: '#/components/schemas/PreprocessorSetupRequest' responses: '200': description: Pre-processor successfully setup content: application/json: schema: $ref: '#/components/schemas/PreprocessorSetupResponse' '400': description: Invalid script '401': description: Permission denied delete: tags: - Preprocessor summary: Delete Custom Pre-Processor operationId: Preprocessor_delete description: Deletes existing custom pre-processors that you own or manage. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PreprocessorDeleteRequest' responses: '200': description: Pre-processor successfully deleted '400': description: Invalid script '401': description: Permission denied get: tags: - Preprocessor summary: Query pre-processors operationId: Preprocessor_list description: >- Look up existing pre-processors your account has access to, including those you have created yourself. parameters: - description: An array of preprocessor IDs in: query name: preprocess required: true schema: type: array items: type: string responses: '200': description: Look up success content: application/json: schema: $ref: '#/components/schemas/PreprocessorResponse' '400': description: Invalid preprocessor_ids '401': description: Permission denied /v1/search/{projectId}: post: tags: - Search summary: Perform a search query of your content operationId: Search_content description: Search and retrieve relevant content from a project with projectId. parameters: - description: The ID of the project to search within. in: path name: projectId required: true schema: type: string - description: Number of results in: query name: 'n' required: false schema: type: integer default: 20 minimum: 1 maximum: 100 requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' responses: '200': description: Search query success content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Invalid request data '401': description: Permission denied components: schemas: ProjectBucketBinding: type: object required: - project properties: project: type: object required: - bucketId properties: bucketId: description: The ID of the bucket to bind to the project. type: integer SearchRequest: type: object properties: search: type: object properties: query: description: The search query type: string nextToken: description: Token to retrieve the next set of paginated results type: string SearchResponse: type: object properties: search: type: object properties: count: description: Total results type: integer results: type: array items: $ref: '#/components/schemas/SearchResultItem' query: description: The search query type: string score: description: Top result relevance score type: number text: description: Combined text from results type: string nextToken: description: For paginated results type: string SearchResultItem: type: object properties: chunkId: description: Unique system generated ID for the chunk type: string documentId: description: Unique system generated ID for the document type: string metadata: description: Document and chunk level metadata type: object score: description: Result relevance score type: number sourceUrl: description: Document source URL type: string text: description: Text from result type: string PreprocessorSetupRequest: type: object properties: description: description: A human readable description for your pre-processor type: string name: description: A human readable name for your pre-processor type: string script: description: An array of GroundedScript commands type: array items: type: string PreprocessorSetupResponse: type: object properties: preprocess: type: object properties: preprocessors: type: array items: type: object properties: id: description: preprocessor ID type: string PreprocessorDeleteRequest: type: object properties: preprocessors: description: An array of preprocessor IDs type: array items: type: string PreprocessorResponse: type: object properties: preprocess: type: object properties: preprocessors: type: array items: type: object properties: id: description: preprocessor ID type: string status: type: string enum: - ok - error - warning status_message: description: human readable status description type: string type: type: string enum: - custom - standard script: type: array items: type: string ProjectCreateRequest: type: object properties: project: type: object properties: name: type: string ProjectResponse: type: object properties: project: $ref: '#/components/schemas/ProjectDetail' InventoryItem: type: object required: - id - name - manufacturer - releaseDate properties: id: type: string format: uuid example: d290f1ee-6c54-4b01-90e6-d701748f0851 name: type: string example: Widget Adapter releaseDate: type: string format: date-time example: '2016-08-29T09:12:33.001Z' manufacturer: $ref: '#/components/schemas/Manufacturer' Manufacturer: required: - name properties: name: type: string example: ACME Corporation homePage: type: string format: url example: https://www.acme-corp.com phone: type: string example: 408-867-5309 type: object ProjectDetail: type: object properties: buckets: type: array items: $ref: '#/components/schemas/BucketDetail' created: type: string format: date-time fileCount: type: integer fileSize: type: string projectId: type: string name: type: string updated: type: string format: date-time BucketDetail: type: object properties: bucketId: type: integer fileCount: type: integer fileSize: type: string name: type: string BucketResponse: type: object properties: bucket: $ref: '#/components/schemas/BucketDetail' BucketCreateRequest: type: object properties: bucket: type: object properties: name: type: string BucketUpdateRequest: type: object properties: bucket: type: object properties: name: type: string ProjectUpdateRequest: type: object properties: project: type: object properties: name: type: string DocumentResponse: type: object properties: document: type: object properties: bucketId: type: integer documentId: type: string fileName: type: string fileSize: type: string fileType: type: string metadata: type: object processId: type: string processedUrl: type: string sourceUrl: type: string status: type: string statusMessage: type: string DocumentRemoteUploadRequest: type: object properties: bucketId: type: integer sourceUrl: type: string callbackData: type: string callbackUrl: type: string metadata: type: object type: $ref: '#/components/schemas/DocumentType' documents: type: array items: type: object properties: bucketId: type: integer sourceUrl: type: string callbackData: type: string callbackUrl: type: string metadata: type: object type: $ref: '#/components/schemas/DocumentType' DocumentType: type: string enum: - txt - docx - pptx - xlsx - pdf - png - jpg DocumentLocalUploadRequest: type: object properties: blob: type: array items: description: The actual file being uploaded. type: string format: binary bucketId: type: integer fileName: type: string fileType: $ref: '#/components/schemas/DocumentType' metadata: type: object callbackData: type: string callbackUrl: type: string IngestResponse: type: object properties: ingest: type: object properties: processId: type: string status: type: string ProcessStatusResponse: type: object properties: ingest: type: object properties: processId: type: string progress: type: object properties: complete: type: object properties: documents: type: array items: $ref: '#/components/schemas/DocumentResponse' total: type: integer errors: type: object properties: documents: type: array items: $ref: '#/components/schemas/DocumentResponse' total: type: integer processing: type: object properties: documents: type: array items: $ref: '#/components/schemas/DocumentResponse' total: type: integer status: type: string statusMessage: type: string InventorySearchResponse: type: array items: $ref: '#/components/schemas/InventoryItem' ProjectDeleteResponse: type: object properties: message: type: string ProjectListResponse: type: object properties: projects: type: array items: $ref: '#/components/schemas/ProjectDetail' BucketDeleteResponse: type: object properties: message: type: string BucketListResponse: type: object properties: buckets: type: array items: $ref: '#/components/schemas/BucketDetail' DocumentDeleteResponse: type: object properties: message: type: string DocumentListResponse: type: object properties: documents: type: array items: $ref: '#/components/schemas/DocumentResponse' DocumentLookupResponse: type: object properties: documents: type: array items: $ref: '#/components/schemas/DocumentResponse' ApiKeyManagementListResponse: type: object properties: apiKey: description: The API key for the user. type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key security: - ApiKeyAuth: []