openapi: 3.0.0 servers: - description: GroundX Base URL url: https://api.groundx.ai/api info: description: This is an OpenAPI description of the GroundX APIs version: "1.0.0" title: GroundX API contact: email: support@groundx.ai license: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' paths: /v1/inventory: get: summary: searches inventory operationId: searchInventory description: | By passing in the appropriate options, you can search for available inventory in the system parameters: - in: query name: searchString description: pass an optional search string for looking up inventory required: false schema: type: string - in: query name: skip description: number of records to skip for pagination schema: type: integer format: int32 minimum: 0 - in: query name: limit description: maximum number of records to return schema: type: integer format: int32 minimum: 0 maximum: 50 responses: '200': description: search results matching criteria content: application/json: schema: type: array items: $ref: '#/components/schemas/InventoryItem' '400': description: bad input parameter post: summary: adds an inventory item operationId: addInventory description: Adds an item to the system responses: '201': description: item created '400': description: 'invalid input, object invalid' '409': description: an existing item already exists requestBody: content: application/json: schema: $ref: '#/components/schemas/InventoryItem' description: Inventory item to add /v1/project/{projectId}: get: summary: Look up an existing project description: This endpoint allows you to retrieve a specific project by projectId. operationId: getProjectById parameters: - in: path name: projectId required: true description: The ID of the project to retrieve. schema: type: string responses: '200': description: Successful retrieval of project content: application/json: schema: $ref: '#/components/schemas/ProjectResponse' put: summary: Update an existing project description: This endpoint allows you to update an existing project. operationId: updateProject parameters: - in: path name: projectId required: true description: The ID of the project to update. 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: summary: Delete an existing project description: This endpoint allows you to delete your existing projects. operationId: deleteProject parameters: - in: path name: projectId required: true description: The ID of the project to delete. schema: type: string responses: '200': description: Successful deletion of project content: application/json: schema: type: object properties: message: type: string /v1/project: get: summary: Look up existing projects description: This endpoint allows you to retrieve your existing projects. operationId: getProjects responses: '200': description: Successful retrieval of projects content: application/json: schema: type: object properties: projects: type: array items: $ref: '#/components/schemas/ProjectDetail' post: summary: Create a project description: This endpoint allows you to initialize a new project. operationId: createProject 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' # Bucket API paths /v1/bucket/{bucketId}: get: summary: Look up an existing bucket description: Look up a bucket by its bucketId. operationId: getBucketById parameters: - in: path name: bucketId required: true description: The ID of the bucket to retrieve. 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: summary: Update an existing bucket description: Update the configurations of an existing bucket. operationId: updateBucket parameters: - in: path name: bucketId required: true description: The ID of the bucket to update. 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: summary: Delete an existing bucket description: Deletes a bucket by bucketId. operationId: deleteBucket parameters: - in: path name: bucketId required: true description: The ID of the bucket to delete. schema: type: integer responses: '200': description: Bucket successfully deleted content: application/json: schema: type: object properties: message: type: string '400': description: Invalid bucket ID '401': description: Permission denied /v1/bucket: get: summary: Look up existing buckets description: Look up existing buckets associated with your account. operationId: getBuckets responses: '200': description: Look up success content: application/json: schema: type: object properties: buckets: type: array items: $ref: '#/components/schemas/BucketDetail' '401': description: Permission denied post: summary: Create a bucket description: Create a new bucket for your content. operationId: createBucket 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: summary: Look up an existing document 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: summary: Delete documents parameters: - name: documentId in: path required: true schema: type: string responses: 200: description: Documents successfully deleted content: application/json: schema: type: object properties: message: type: string 400: description: Invalid document ID 401: description: Permission denied /v1/ingest/documents: get: summary: Look up all existing documents responses: 200: description: Look up success content: application/json: schema: type: object properties: documents: type: array items: $ref: '#/components/schemas/DocumentResponse' 401: description: Permission denied post: summary: Upload hosted documents to GroundX requestBody: content: application/json: schema: $ref: '#/components/schemas/DocumentUploadRequest' 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/{id}: get: summary: Look up existing documents by processId, bucketId, or projectId parameters: - name: id in: path required: true schema: type: string responses: 200: description: Look up success content: application/json: schema: type: object properties: documents: type: array items: $ref: '#/components/schemas/DocumentResponse' 401: description: Permission denied /v1/ingest/{processId}: get: summary: Look up document processing status by processId 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: summary: Setup Custom Pre-Processor description: Initializes a custom pre-processor that can be applied to your content and search queries. operationId: setupCustomPreprocessor 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: summary: Delete Custom Pre-Processor description: Deletes existing custom pre-processors that you own or manage. operationId: deleteCustomPreprocessor 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: summary: Query pre-processors description: Look up existing pre-processors your account has access to, including those you have created yourself. operationId: queryPreprocessors parameters: - in: query name: preprocess description: An array of preprocessor IDs 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: summary: Perform a search query of your content description: Search and retrieve relevant content from a project with projectId. operationId: searchContent parameters: - in: path name: projectId required: true description: The ID of the project to search within. schema: type: string - in: query name: n description: Number of results 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: SearchRequest: type: object properties: search: type: object properties: query: type: string description: The search query nextToken: type: string description: Token to retrieve the next set of paginated results SearchResponse: type: object properties: search: type: object properties: count: type: integer description: Total results results: type: array items: $ref: '#/components/schemas/SearchResultItem' query: type: string description: The search query score: type: number description: Top result relevance score text: type: string description: Combined text from results nextToken: type: string description: For paginated results SearchResultItem: type: object properties: chunkId: type: string description: Unique system generated ID for the chunk documentId: type: string description: Unique system generated ID for the document metadata: type: object description: Document and chunk level metadata score: type: number description: Result relevance score sourceUrl: type: string description: Document source URL text: type: string description: Text from result PreprocessorSetupRequest: type: object properties: name: type: string description: A human readable name for your pre-processor script: type: array items: type: string description: An array of GroundedScript commands description: type: string description: A human readable description for your pre-processor PreprocessorSetupResponse: type: object properties: preprocess: type: object properties: preprocessors: type: array items: type: object properties: id: type: string description: preprocessor ID PreprocessorDeleteRequest: type: object properties: preprocessors: type: array items: type: string description: An array of preprocessor IDs PreprocessorResponse: type: object properties: preprocess: type: object properties: preprocessors: type: array items: type: object properties: id: type: string description: preprocessor ID status: type: string enum: - ok - error - warning status_message: type: string description: human readable status description 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 DocumentUploadRequest: type: object properties: documents: type: array items: type: object properties: bucketId: type: integer sourceUrl: type: string callbackData: type: string callbackUrl: type: string metadata: type: object type: type: string enum: - txt - docx - pptx - xlsx - pdf - png - jpg DocumentLocalUploadRequest: type: object properties: documents: type: array items: type: object properties: blob: type: string format: binary description: The actual file being uploaded. bucketId: type: integer fileName: type: string fileType: type: string enum: - txt - docx - pptx - xlsx - pdf - png - jpg 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key security: - ApiKeyAuth: []