Get StartedLoginTutorials

API Endpoints

Use our API endpoints to interact with various parts of the VectorShift platform.

You can use the API to query for and work with various VectorShift objects. For instance, we provide endpoints for running Pipelines and Chatbots.

All API endpoints support passing in the Api-Key field within the HTTP headers or as a query parameter for your API key. Each API key is associated with a unique user, so make sure the API key you are using is that of a user profile you intend to use.

Each endpoint should be called with the domain name https://api.vectorshift.ai. For instance, the endpoint /api/chatbots/run is https://api.vectorshift.ai/api/chatbots/run in full.

API calls are rate-limited to 250/minute for non-Enterprise subscriptions.

Agents (Beta)

For background information on Agents, see here.

Agent JSON Representation

Here are relevant fields in the JSON representation of an Agent:

  • id: The ID of the Agent.

  • name: The name of the Agent.

  • task: A description of the Agent's task.

  • description: A description of the Agent.

  • tools: An array of tools used by the Agent. containing a name, description, type, id, and a parameters array. Each parameter has a name, description, and type.

  • llm: The LLM on which the Agent is based.

  • framework: The agentic framework used.

  • inputs: An array of input objects. Each input is keyed by its name, and has a name and type field, containing its name and an input type string.

  • outputs: An array of output objects. The format is the same as above.

POST /api/agents/add

Add a new Agent for a user. The Agent can either be new (where the id field is None), or an existing Agent to be updated (where the id field should contain the ID of the existing Agent).

Parameters:

  • agent: The string representation of a JSON with the Agent data. See above for the structure of an agent JSON. For adding an Agent, some fields are different. The framework field is not required, and the tools should be an array of strings corresponding to the tools (the valid choices of strings are those displayed in the no-code creator).

Response: The JSON of the added Agent if the Agent was successfully added, and None otherwise.

GET /api/agents/fetch

Fetch a particular Agent.

Parameters:

  • (Optional) agent_id: The ID of the Agent. You can use a combination of agent_name, username, and org_name in place of agent_id if preferred.

  • (Optional) agent_name, username, org_name: The Agent name, username, and organization name associated with the Agent you want to run. If the Agent you are looking to run is not associated with an organization, you can omit org_name. At least one of agent_id and agent_name should be provided. If both are provided, agent_id is used to search for the Chatbot.

Response: A JSON representation of the Agent.

POST /api/agents/run

Run an Agent.

Parameters:

  • agent_id: The ID of the Agent.

  • inputs: A JSON representation of an array of inputs to the Agent. Should take the form of a dictionary of input names, as defined for the Agent, to their values.

Response: A JSON-encoded dictionary of Agent output names to their values.

Automations (Beta)

For background information on Automations, see here. We are currently building out more API endpoints for working with Automations.

Automation JSON Representation

Here are relevant fields in the JSON representation of an Automation:

  • id: The ID of the Automation.

  • name: The name of the Automation.

  • description: A description of the Automation.

  • app: The name of the Integration used by the Automation on VectorShift, containing id and name fields.

  • event: A string describing the particular event with the Integration that triggers the Automation.

  • trigger: Details on the particular event that specify when the Automation should be triggered.

  • record: Additional data associated with the Automation, such as pre-set values.

  • pipeline: The Pipeline that is run by the Automation. Structured as a Pipeline JSON object.

  • mappings: An array of mappings from Automation input names to Pipeline inputs.

  • endpoint: The Integration endpoint called by the Automation.

GET /api/automations/list

Retrieve all automations owned by a user.

Parameters: None.

Response: A JSON array of Automation objects owned by the user.

/api/automations/fetch

Fetch a particular Automation.

Parameters:

  • (Optional) automation_id: The ID of the Automation.

  • (Optional) automation_name: The name of the Automation. At least one of automation_id and automation_name should be provided. If both are provided, automation_id is used to search for the Automation.

Response: A JSON representation of the Automation.

DELETE /api/automations/delete/{automation_id}

Delete a particular Automation.

Parameters: None. The ID of the automation should be specified in the endpoint.

Response: A JSON with an acknowledged field indicating if the delete operation was successful.

GET /api/automations/events/{app_id}

Retrieve an array of all events associated with an Integration.

Parameters: None. The ID of the Integration associated with the Automation should be passed in to the endpoint (through the variable app_id).

Response: A JSON-encoded array of possible events associated with the Integration.

GET /api/automations/triggers

Retrieve an array of all triggers associated with an Integration.

Parameters:

  • app_id: The ID of the Integration associated with the Automation.

  • event: The particular event associated with the Integration.

Response: A JSON-encoded array of possible triggers associated with the Integration event.

Chatbots

For background information on Chatbots, see here.

Chatbot JSON Representation

Here are relevant fields in the JSON representation of a Chatbot:

  • id: The ID of the Chatbot.

  • name: The name of the Chatbot.

  • description: A description of the Chatbot.

  • pipeline: The Pipeline that the Chatbot is built upon. Structured as a Pipeline JSON object.

  • input: A singleton map of an input to the input details, an object with name and type fields.

  • output: A singleton map of an output to the output details, an object with name and type fields.

  • deployed: A boolean flag indicating whether or not the Chatbot has been deployed.

/api/chatbots/fetch

Fetch a particular Chatbot.

Parameters:

  • (Optional) chatbot_id: The ID of the Chatbot you want to run. You can use a combination of chatbot_name, username, and org_name in place of chatbot_id if preferred.

  • (Optional) chatbot_name: The Chatbot name associated with the Chatbot you want to run. You can use chatbot_id in place of this parameter if preferred. At least one of chatbot_id and automation_name should be provided. If both are provided, chatbot_id is used to search for the Chatbot.

Response: A JSON representation of the Chatbot. 

POST https://api.vectorshift.ai/api/chatbots/run

Run a Chatbot.

Parameters:

  • input: A string with your input message.

  • (Optional) chatbot_id: The ID of the Chatbot you want to run. You can use a combination of chatbot_name, username, and org_name in place of chatbot_id if preferred.

  • (Optional) chatbot_name, username, org_name: The Chatbot name, username, and organization name associated with the Chatbot you want to run. If the Chatbot you are looking to run is not associated with an organization, you can omit org_name. At least one of chatbot_id and chatbot_name should be provided. If both are provided, chatbot_id is used to search for the Chatbot.

  • (Optional) conversation_id: The conversation ID associated with the conversation you want to continue. If empty, your call will generate a new conversation with no conversation history. If you pass a conversation ID, the Chatbot will continue the conversation from where it left off and write the new responses to the conversation history.

  • (Optional) stream: A boolean flag indicating whether or not to stream the response.

  • (Optional) is_twilio: A boolean flag indicating whether or not the Chatbot is used with Twilio.

Response: The response will be returned as a JSON object with the following keys and values:

  • output: The output message from the Chatbot.

  • conversation_id: The conversation ID to which your input and the Chatbot's output were written.

Integrations

For background information on Integrations, see here.

Integration JSON Representation

Here are relevant fields in the JSON representation of an Integration:

  • id: The ID of the Integration.

  • name: The name of the Integration.

  • description: A description of the Integration.

  • type: The type of Integration.

  • params: A mapping of integration type-specific parameter fields to their values.

  • integration_data: Additional metadata provided as part of the integration type. May not be present for some integration types.

GET /api/integrations/list

Retrieve all integrations owned by a user.

Parameters: None.

Response: A JSON-encoded array of integration objects owned by the user, following the general structure described above .

POST /api/integrations/sync-metadata

Sync provided metadata for an Integration.

Parameters:

  • integration_id: The ID of the Integration to sync.

Response: A JSON-encoded array of Integration items representing parts of the metadata changed by the sync. Each item is represented as an object including the fields name, parent_id, integrationID, and integrationName.

POST /api/integrations/sync

Sync all data (e.g. files) related to an Integration.

Parameters:

  • integration_id: The ID of the Integration to sync.

Response: The ID of the Integration synced if successful.

GET /api/integrations/get-item-ids

Retrieve the IDs for items related to an Integration (e.g. files).

Parameters:

  • integration_id: The ID of the Integration from which to retrieve items.

Response: A JSON-encoded array of Integration items corresponding to all items associated with the Integration. Each item is represented as an object including the fields name, parent_id, integrationID, and integrationName.

Pipelines

For background information on Pipelines, see here.

Pipeline JSON Representation

Here are relevant fields to include in the JSON representation of a Pipeline:

  • id: The ID of the Pipeline.

  • name: The name of the Pipeline.

  • description: A description of the Pipeline's functionality.

  • nodes: An array of objects representing individual nodes in the pipeline. Each node contains the following fields: a string id, and data, an object containing node-specific data.

  • edges: An array of object representing edges (connections for data flow) between nodes. Each object has source, sourceHandle, target, and targetHandle fields, strings which represent the IDs of the nodes being connected and their specific inputs/outputs being connected.

  • inputs: A mapping of input names to objects describing the input name and type. Should be associated with input nodes included in the nodes array.

  • outputs: A mapping of output names to objects described as above. Should be associated with output nodes included in the nodes array.

  • username: The username of the user owning the Pipeline.

POST /api/pipelines/add

Add a new Pipeline for a user. The Pipeline must be new and have a unique name.

Parameters:

  • pipeline: A JSON representation of the Pipeline to add following the structure described above. The JSON should have a null id field.

Response: The JSON representing the added Pipeline's representation in the VectorShift platform if the add was successful.

GET /api/pipelines/fetch

Retrieve data for a specific Pipeline.

Parameters:

  • (Optional) pipeline_id: The ID of the Pipeline you want to fetch. You can use a combination of pipeline_name, username, and org_name in place of pipeline_id if preferred.

  • (Optional) pipeline_name, username, org_name: The Pipeline name, username, and organization name associated with the Pipeline you want to fetch. If the Pipeline you are looking to fetch is not associated with an organization, you can omit org_name. If the Pipeline is in My Pipelines, you can omit username. At least one of pipeline_id and pipeline_name should be provided. If both are provided, pipeline_id is used to search for the Pipeline.

Response: The JSON representing the particular Pipeline's representation in the VectorShift platform. This JSON will contain an additional field, shared_status, with a string value indicating if you own the Pipeline, can edit the Pipeline, or can only run the Pipeline.

POST /api/pipelines/run

Run a pipeline.

Parameters:

  • inputs: A JSON object with the input names associated with the Pipeline as the keys and the values for those respective inputs as the values.

  • (Optional) pipeline_id: The ID of the Pipeline you want to run. You can use a combination of pipeline_name, username, and org_name in place of pipeline_id if preferred.

  • (Optional) pipeline_name, username, org_name: The name, username, and organization name associated with the Pipeline you want to run. If the Pipeline you are looking to run is not associated with an organization, you can omit org_name. If the Pipeline is in My Pipelines, you can omit username. At least one of pipeline_id and pipeline_name should be provided. If both are provided, pipeline_id is used to search for the Pipeline.

Response: The response will be returned as a JSON object with the output names of the Pipeline as the keys and the values for those respective outputs as the values.

VectorStores

For background information on VectorStores, see here.

VectorStore JSON Representation

Here are relevant fields to include in the JSON representation of a VectorStore:

  • name: The name of the VectorStore.

  • description: A description for the VectorStore.

  • chunkSize: The size (in tokens) of each document retrieved when loading data from the VectorStore.

  • chunkOverlap: The overlap (in tokens) of consecutive document retrieved when loading data from the VectorStore.

  • isHybrid: A boolean flag indicating whether or not the VectorStore is hybrid (uses more than one search algorithm to execute queries).

POST /api/vectorstores/add

Add a new VectorStore for a user. The VectorStore must be new and have a unique name.

Parameters:

  • vectorstore: The JSON-encoded representation of the VectorStore to add, following the structure above.

Response: A JSON object with a field id indicating the ID of the newly-added VectorStore, if the add was successful.

POST /api/vectorstores/fetch

Retrieve data for a specific VectorStore.

Parameters:

  • (Optional) vectorstore_id: The ID of the VectorStore you want to fetch. You can use a combination of vectorstore_name, username, and org_name in place of pipeline_id if preferred.

  • (Optional) vectorstore_name, username, org_name: The name, username, and organization name associated with the VectorStore you want to fetch. If the VectorStore you are looking to fetch is not associated with an organization, you can omit org_name. If the VectorStore is owned by you, you can omit username. At least one of vectorstore_id and vectorstore_name should be provided. If both are provided, vectorstore_id is used to search for the VectorStore.

Response: The JSON representing the particular VectorStore's representation in the VectorShift platform. 

POST api/vectorstores/update-metadata

Update the metadata for a particular VectorStore.

Parameters:

  • vectorstore_id: The ID of the VectorStore to update.

  • list_of_item_ids: An array of IDs for documents in the VectorStore to be updated.

  • list_of_metadata: An array of objects containing metadata for the documents specified in list_of_item_ids to update. The lengths of list_of_item_ids and list_of_metadata should be equal.

  • keep_prev: Whether to keep the version of the updated documents with the previous metadata in the VectorStore.

Response: No data is returned from a successful call of this endpoint.

POST /api/vectorstores/update-selected-items

Update specific documents in a VectorStore associated with an Integration.

Parameters:

  • vectorstore_id: The ID of the VectorStore to update.

  • integration_id: The ID of the associated Integration to update documents from.

  • selected_items: The IDs of the documents to update.

  • select_all_items_flag: A boolean flag that specifies whether or not to update all documents associated with the Integration.

  • keep_prev: Whether to keep the version of the documents pre-update in the VectorStore.

Response: No data is returned from a successful call of this endpoint.

/api/vectorstores/load

Update documents into a VectorStore.

Parameters:

  • (Optional) vectorstore_id: The ID of the VectorStore you want to fetch.

  • (Optional) vectorstore_name: The name of with the VectorStore you want to fetch. At least one of vectorstore_id and vectorstore_name should be provided. If both are provided, vectorstore_id is used to search for the VectorStore.

  • document: A string or file, or a list of strings and files, to be uploaded as a document into the VectorStore.

  • document_name: The name to give the document(s) loaded into the VectorStore.

  • document_type: The type of the document(s) loaded into the VectorStore.

  • chunkSize: The size (in tokens) of each vector retrieved when loading data into the VectorStore.

  • chunkOverlap: The overlap (in tokens) of consecutive vectors retrieved when loading data into the VectorStore.

  • selected_items: An array of documents ot update in addition to loading the new document.

  • select_all_items_flag: A boolean flag that specifies whether or not to update all documents associated with the Integration in addition to loading the new document.

  • metadata: A mapping of metadata meant to be added to the new document.

  • metadata_by_item: An array of metadata to update for the associated documents in selected_items. The lengths of selected_items and list_of_metadata should be equal.

Response: A JSON object with a field documents, listing the new documents loaded into the VectorStore.

POST /api/vectorstores/query

Run a query on the VectorStore and return its results.

Parameters:

  • (Optional) vectorstore_id: The ID of the VectorStore you want to query.

  • (Optional) vectorstore_name: The name of with the VectorStore you want to query. At least one of vectorstore_id and vectorstore_name should be provided. If both are provided, vectorstore_id is used to search for the VectorStore.

  • query: A string query to the VectorStore.

  • (Optional) max_docs: The max number of documents to return from the query. Defaults to 5.

Response: A JSON containing the items in the VectorStore returned from the query. 

POST /api/vectorstores/list-documents

List all documents in a VectorStore.

Parameters:

  • (Optional) vectorstore_id: The ID of the VectorStore you want to return documents from.

  • (Optional) vectorstore_name: The name of with the VectorStore you want to return documents from. At least one of vectorstore_id and vectorstore_name should be provided. If both are provided, vectorstore_id is used to search for the VectorStore.

  • (Optional) max_docments: The max number of documents to list. Defaults to None.

Response: A JSON containing up to max_documents items in the VectorStore.

POST /api/vectorstores/share

Share a VectorStore with users.

Parameters:

  • vectorstore_id: The ID of the VectorStore to share.

  • shared_users: A list of usernames to share the VectorStore with.

Response: A JSON-encoded array of data for the new set of users the VectorStore is shared with.

POST /api/vectorstores/shared

Retrieve all shared VectorStores (for a user).

Parameters: None.

Response: A JSON-encoded array of objects each representing a VectorStore shared with the user owning the API key on the VectorShift platform.

POST /api/vectorstores/delete-documents

Delete documents from a VectorStore.

Parameters:

  • vectorstore_id: The ID of the VectorStore to delete documents from.

  • document_ids: The IDs of the documents to remove.

Response: An array of IDs for the removed documents.

POST /api/vectorstores/shared/remove

Remove user access from a VectorStore.

Parameters:

  • vectorstore_id: The ID of the VectorStore to revoke access to.

  • users_to_remove: A list of usernames to which access will be removed.

Response: No data is returned from a successful call of this endpoint.

PreviousUsageNextSDK

Last updated