API Reference

BigBlueRiver provides APIs for:

String processing
Numeric computation
LLM Chat management
Vector database management
Rational database management
Kartra membership platform management

To get API heartbeat or version, click HERE

While this documentation shows examples of our APIs based on the Adalo No-Code platform, any coding platform can use the APIs.

This documentation uses, "API Base URL" instead of "endpoint". Their meanings are the same.

String API

Words

Returns the number of words (character groups seperated by a space) in a string.

Example

"Surf looks good! Let's go surfing." ➔ 6

API Base URL

https://bigblueriver.com:8000/string/words

Parameters

Name	Type	Description	Required
`string`	String	String to be conversed	Yes

Outputs

Name	Type	Description
`words`	Integer	Words in string

Length

Returns the length (number of characters) in a string.

Example

"This is awesome!" ➔ 16

API Base URL

https://bigblueriver.com:8000/string/length

Parameters

Name	Type	Description	Required
`string`	String	String to be conversed	Yes

Outputs

Name	Type	Description
`length`	Integer	Length of string

Uppercase

Makes all letters in the string uppercase.

Example

"This is awesome :)" ➔ "THIS IS AWESOME :)"

API Base URL

https://bigblueriver.com:8000/string/uppercase

Parameters

Name	Type	Description	Required
`string`	String	String to be converted	Yes

Outputs

Name	Type	Description
`string`	String	String after conversion

Lowercase

Makes all letters in the string lowercase.

Example

"This is awesome :)" ➔ "this is awesome :)"

API Base URL

https://bigblueriver.com:8000/string/lowercase

Parameters

Name	Type	Description	Required
`string`	String	String to be converted	Yes

Outputs

Name	Type	Description
`string`	String	String after conversion

Tail

Returns a specific number of ending characters from a string.

Example

"Mississippi", 3 ➔ "ppi"

API Base URL

https://bigblueriver.com:8000/string/tail

Parameters

Name	Type	Description	Required
`string`	String	String to be processed	Yes
`length`	Integer	Number of characters	Yes

Outputs

Name	Type	Description
`string`	String	String after conversion

Numeric API

Random

Returns a random generated string.

Example

4, alpha, lower ➔ "ikxi"
5, alpha, upper ➔ "IKXI"
5, alpha, mixed ➔ "IkXi"
5, numeric ➔ "35891"
6, alphanumeric, mixed ➔ "3Z8xTd"

API Base URL

https://bigblueriver.com:8000/random

Parameters

Name	Type	Description	Required	Default
`length`	Integer	Number of number and/or characters	Yes	4
`type`	String	alpha, numeric, alphanumeric	Yes	numeric
`case`	String	Alpha case: lower, upper, mixed	Yes, if alpha	lower

Outputs

Name	Type	Description
`result`	String	Random generated string
`status`	String	Status code: 200 OK, 400 ERROR

Artifical Intelligence

Chat

Returns the Large Language Models (LLM) response, and potentially much more.

It can be as simple as getting a users request and your OpenAI api_key, making the BBR API Chat request and in response you receive the LLM response.

But, there is much more to help guide the AI:

State its identify; "You are a Senior Financial Analyst". Use the, ai_identify parameter.
Provide instructions to provide response specifics; "Limit your response to 50 words". Use the, llm_instructions parameter.
Conversational AIs maintain short-term memory, providing a simulated listening AI experience. You can control how many words the AI can remember during each conversation.
- Setting the llm_max_history_words parameter to a value greater than zero enables AI short-term memory.
- There is a practical limit both in terms of LLM prompt limit and also cost. Each words equates roughly to a token is the usual LLM unit of cost. Also, each LLM has a maximum number of tokens it can receive as input plus the output.
- Useful llm_max_history_words begins at around 200 and the cost/benefit tends to peak at around 2000 words.
- Depending on your expected input and output tokens, most applications work well when the llm_max_history_words is to around 80% of the maximum LLM input plus output token limit.
AI accurary and usefullness can be improved by providing relevant pages from a document such as book, article, blog post,report or transcription.
- This is commonaly referred to as, Retrieval Augmented Generation or simply RAG.
- The documents are vectorized, then stored in a Vector Database (VDB), which requires a specialized algorithm provided a vendor such as OpenAI or Cohere.
- You must load the documents in a VDB before you can reference them. This is detailed in the below section, Vector Database.
- A user's request must also be vectorized for the VDB to search for the most relevant pages and return these pages as text. Think of this process like a response from a Google search; user textual request ➔ Google magic ➔ textual response referring to a web page.
- Vectorization, which is commonally called embedding, requires an API key from their vendor.
- There are many VDBs available, some are free and some require an API key their vendor. By default, BBR uses free VDB called, ChromaDB. While the ChromaDB VDB store is free, the embedding enabling both storing and retreiving relevant pages requires a vendor such as OpenAI and Cohere.
- It is common to use the same vendor for both embedding and LLM use. For example, you can use the same OpenAI API key for parameters llm_vendor_api_key and vdb_embed_api_key.

Example

The most basic and common LLM interaction, consisting of a user request and a LLM API key:

"What do you see?",   "", "",    , , "sk-8Tmvb5j", "", "", "", "", "" ➔  "As an AI, I do not have biological eyes."

AI identity added to enhance response:

"What is grisaille", "You are an oil painter.", "", 0, , "sk-8Tmvb5j", "", "", "", "", "" ➔  "A form of underpainting."

LLM instruction added to furture guide the AI response:

"What is grisaille", "You are an oil painter.", "Limit your reponse to only 1 word.", 0, , "sk-8Tmvb5j", "", "", "", "", "" ➔  "underpainting"

LLM short-term memory added to better simulate a conversation:

"Can you see color?", "", "", 500, , "sk-8Tmvb5j", "", "", "", "", "" ➔  "As I mentioned before, I cannot see."

LLM short-term memory, AI identify and LLM instruction:

"Do you use grisaille?", "You are an oil painter.", "Limit your reponse to 25 words.", 500, , "sk-8Tmvb5j", "", "", "", "", "" ➔  "As I mentioned before, I am an AI and cannot paint."

Simplest yet powerful RAG example. You must have previouly loaded documents into your VDB.

"Summerize the context", "", "", 0, "OpenAI" , "sk-8Tmvb5j", "ChromaDB", "", "", "OpenAI", "sk-8Tmvb5j" ➔ "A conversation about..."

API Base URL

https://bigblueriver.com:8000/chat

Parameters

Name	Type	Description	Required	Default
`request`	String	Chat request. Usually raw user input.	Yes	"What do you see?"
`ai_identify`	String	AI identity	No	No default value
`llm_instructions`	String	LMM guidence instructions	No	No default value
`llm_max_history_words`	Integer	LLM maximum number of chat history words	No	0: no history used
`llm_vendor`	String	LLM vendor, (OpenAI, Cohere)	No	"OpenAI"
`llm_model_name`	String	LLM model name	No, Yes	No: OpenAI: gpt-4, Yes: otherwise specify
`llm_model_tempature`	String	LLM model tempature	No	0.10, OpenAI: 0.0 to 1.0
`llm_vendor_api_key`	String	LLM API key, which you must acquire	Yes	No default value
`rag_vdb_storage_vendor`	String	VDB vendor (ChromaDB, Oracle, MySQL)	No, Yes	"" is not using RAG. Required if using RAG (1)
`rag_vdb_name`	String	VDB database name	No	"" results in BBR determined VDB name
`rag_vdb_collection_name`	String	VDB database collection name	No	"" results in the default, "General"
`rag_vdb_embed_vendor`	String	VDB embedding vendor	No	"OpenAI"
`rag_vdb_embed_api_key`	String	VDB database name	No, Yes	Required if using RAG (2)

Outputs

Name	Type	Description
`response`	String	LLM chat response text
`input_tokens`	String	Number of tokens sent to LLM
`output_tokens`	String	Number of tokens returned from LLM
`rag_vdb_tokens`	String	Number of tokens embeeded
`status`	String	Status code: `200 OK`, `400 ERROR`

Notes

(1) If doing Retrieval Augmented Generation (RAG), a VDB vendor must be provided. Choose, ChromaDB unless you have a reason for using chosen something else.
(2) As discussed in the introduction above, both the users' request and the documents to be stored in the VDB must be embedded/vectorized, which requires a specialized vendor algorithm, which also requires an API key.

Tail

Returns the maximum number of chat history dialogs based on either maximum number of dialogs or maximum number of words, whichever is less.

Large Language Models (LLMs) have limits on the number of words (technically tokens) they can process. If the limit is 4096, then the LLM input and output tokens sum absolutely must be less than 4096. If you want to increase the default of 2000 words, 2500 or 3000 is fine.

The chat/tail default values tend to provide a good user experience. It is unwise to set max_words greater than 80% of the LLM token limit.

Example

Suppose the chat_history chats/dialogs are:

USER: Hello. Is anything there?
ASSISTANT: Yes. Who is this?
USER: My name is Craig.
ASSISTANT: Nice to meet you Craig.
USER: What is 1+1
ASSISTANT: 1+1 is 2
USER: What time is it?
ASSISTANT: 12noon

If max_chats is 1 and max_words is 50000, the result would be:

{'result': 'USER: What is 1+1\nASSISTANT: 1+1 is 2\nUSER: What time is it?\nASSISTANT: 12noon'}

If max_chats is 2 and max_words is 5000, the result would be:

{'result': 'USER: What time is it?\nASSISTANT: 12noon'}

If max_chats is 10 and max_words is 10, the result would be:

{'result': 'USER: What time is it?\nASSISTANT: 12noon'}

API Base URL

https://bigblueriver.com:8000/chat/tail

Parameters

Name	Type	Description	Required	Default
`chat_history`	String	Chat history as described above	Yes	No default value
`max_chats`	Integer	Maximum number of chat dialogs to return	No	100
`max_words`	Integer	Maximum number of words to return	No	2000

Outputs

Name	Type	Description
`result`	String	Chat history after processing
`status`	String	Status code: 1: OK, 2: Not OK

Notes

Complete dialogs are returned, regardless of the parameter max_words.
If there is a problem processing, the entire chat_history is returned.

Vector Database

Fully Defined But Not Yet Fully Implemented

A Vector Database (VDB) manages vectors. Vectors are numeric arrays representing a sentence, document page, image or video segment.

One BBR vector database, contains zero or more document collections and each collection contains zero or more documents. Currenty, all documents are transformed into text, vectorized and loaded into the VDB.

Vectors are interesting:

VDBs not only store vectors, but are indexed for speedy retrieval.
VDBs can do contextual similarity searches, returning multiple document texts associated with a given prompt. The texts are actual text pages, not vectors.
VDBs are NOT Large Language Models (LLMs). They act independantly of LLMs but can be used together for a specific solution.
Data can be vectorized and stored using vendor ABC and used to build a prompt which will be sent to an LLM from vendor DEF.

A BBR Vector Database consist of a physical directory with multiple folders and files. The VDB name is composed of four segments:

The letters, "VDB".
Internal BBR VDB embedding identifer.
Eight digit identify code.
The last three characters of your OpenAI API key

An example VDB name is, VDB_01_75709444_b5j

It is easier for you, if you let BBR name your VDB. Otherwise, you must remember and specify the components in your API call.

Note: VDBs are automatically removed after nine months of no activity.

Does A Vector Database Exist

Check if the given VDB exists.

Not defined

What Is My Vector Database Name

Sometimes you need to know the name of your vector database.

BBR can determine your default VDB name, even if it has not been created yet.

Example

"",         , ""    ➔ "VDB_01_95714961_U03", "OK 200" (1)
"sk-8Tmvb5j", "01"  ➔ "VDB_01_75709444_b5j", "OK 200"
"sk-8Tmvb5j", ""    ➔ "VDB_01_75709444_b5j", "OK 200"
"",           "01"  ➔ "VDB_01_95714961_Uo3", "OK 200"

API Base URL

https://bigblueriver.com:8000/vdb/vdbname

Parameters

Name	Type	Description	Required	Default
`key`	String	A unique key. Remember your key.	No	Current open_api_key
`embed_model`	String	Embedding model	No	"01"

Outputs

Name	Type	Description
`vdb_name`	String	Full VDB name, tha can be used to reference the new VDB
`exists`	Bool	True or False. Not supported yet
`status`	String	Status code: `200 OK`, `400 ERROR`

Notes

(1) Default VDB will be created. This is the recommended default.

BBR Embedding Key	Embedding Model
`01`	OpenAI text-embedding-ada-002

Create New Vector Database (VDB)

Create a new vector database (VDB), which consists of a folder with sub-directories and files.

To create a VDB you have three naming choices.

Set all parameters to "" and the VDB will be created as described in above section, What Is My Vector Database Name. This is simpliest and lowest effort for you, so it is the default.
Set the VDB name as you desire. If the name has already been taken, you will need to choose another name.
Set the key and the emded_model and the VDB will be created as described in the above section, What Is My Vector Database Name.

Example

"",                    "",           ""   ➔ "VDB_01_95714961_Uo3", "OK 200" (1)
"VDB_01_75709444_b5j", "",           ""   ➔ "VDB_01_75709444_b5j", "OK 200"
"",                    "sk-8Tmvb5j", "01" ➔ "VDB_01_75709444_b5j", "OK 200"

API Base URL

https://bigblueriver.com:8000/vdb/createvdb

Parameters

Name	Type	Description	Required	Default
`vdb_name`	String	Your VDB identifying name	No	""
`key`	String	A unique key. Remember your key.	No	Current open_api_key
`embed_model`	String	Embedding model	No	"01"

Outputs

Name	Type	Description
`vdb_name`	String	Full VDB name, used to reference the new VDB
`status`	String	Status code: `200 OK`, `400 ERROR`, `300 WARNING`

Notes

(1) Recommended default
If the VDB already exists, a warning will be returned: 300 WARNING
The name must be alphanumeric only, containing no special characters or symbols.

BBR Embedding Key	Embedding Model
`01`	OpenAI text-embedding-ada-002

Create A New Collection

Create a collection in one of your existing vector databases.

If do not want multiple collections or are not sure about future requirements, take the default collection name of "General".

If the vector DB is not supplied one will be automatically created using the default parameters (key and embed_model) and the name returned.

Example

"",                    "",           "", ""          ➔ "OK 200" (1)
"",                    "",           "", "SB Zoning" ➔ "OK 200" (2)
"VDB_01_95714961_Uo3", "",           "", "SB Zoning" ➔ "OK 200"
"",                    "sk-8Tmvb5j", "", "SB Zoning" ➔ "OK 200"

API Base URL

https://bigblueriver.com:8000/vdb/createcollection

Parameters

Name	Type	Description	Required	Default
`vdb_name`	String	Full BBR VDB name	No	Do not enter unless non default name.
`key`	String	A unique key. Remember your key.	No	Current open_api_key
`embed_model`	String	Embedding model	No	"01"
`collection_name`	String	Collection name	No	"General"

Outputs

Name	Type	Description
`vdb_name`	String	Full BBR VDB name
`collection_name`	String	Collection name, used to reference the new collection
`status`	String	Status code: `200 OK`, `400 ERROR`, `300 WARNING`

Notes

(1) Recommended default.
(2) Recommended when using multiple collections.
If the collection already exists, a warning will be returned: 300 WARNING

Load Document Into VDB Collection

Load a single document file into a vector database collection.

Example

"", "", "", "",                "",             "txt", "loco septem..." ➔ 3, "OK 200"
"", "", "", "",                "2023 Meeting", "txt", "loco septem..." ➔ 3, "OK 200"
"", "", "", "Annual Meetings", "2023 Meeting", "txt", "loco septem..." ➔ 3, "OK 200"
"", "", "", "Annual Meetings", "",             "txt", "loco septem..." ➔ 3, "OK 200"
"VDB_01_95714961_Uo3", "sk-8Tmvb5j", "01", "Annual Meetings", "2023 Meeting", "txt", "loco septem..."  ➔ 3, "OK 200"

API Base URL

https://bigblueriver.com:8000/vdb/loaddoc

Parameters

Name	Type	Description	Required	Default
`vdb_name`	String	Full BBR VDB name	No	Do not enter unless non-default name.
`key`	String	A unique key. Remember your key.	No	Current open_api_key
`embed_model`	String	Embedding model	No	"01"
`collection_name`	String	Collection name	No	"General"
`document_name`	String	Name of document	No	"Document name not specified"
`document_type`	String	[txt,pdf]	Yes	No default value
`document_content`	String	Document content	Yes	No default value

Outputs

Name	Type	Description
`pages`	Integer	Number of document pages successfully loaded
`status`	String	Status code: `200 OK`, `400 ERROR`

Notes

Similarity Search

Do a vector similarity search on one of your existing vector database collections.

Example

"VDB_01_8UpI5z_Craig2", "SB Zoning", "Zone 5", 10 ➔ "OK 200"
"VDB_01_8UpI5z_Craig2", "SB Zoning", "Water", 5 ➔ "OK 200"

API Base URL

https://bigblueriver.com:8000/vdb/simsearch

Parameters

Name	Type	Description	Required	Default
`vdb_name`	String	Full BBR VDB name	Yes	No default value
`collection_name`	String	Collection name	No	"General"
`search`	String	Search request text	Yes	No default value
`max_pages`	Integer	Maximum number of pages returned from search	No	3

Outputs

Not sure yet.

Notes

Rational Database

Not Yet Defined Nor Implemented

If you want to use the relational Database (RDB) APIs, please Contact Us and RDB credentials will be sent to you.

The SQL statement response will be in JSON format.

Note: VDBs are automatically removed after nine months of no activity.

SQL

You can submit these SQL statements: create table drop table select update delete insert

Returns the result of the SQL statement.

Example

"drop table activity", "ACME", "58Y8" ➔ "OK"
"create table activity (user_id char, activity_id date, activity_type char), "ACME", "58Y8"  ➔ "OK"
"select count(activity_type) from activity where user_id = 123", "ACME", "58Y8" ➔ "554"

API Base URL

https://bigblueriver.com:8000/rdb/sql

Parameters

Name	Type	Description	Required
`sql`	String	SQL statement	Yes
`username`	String	RDB username	Yes
`password`	String	RDB password	Yes
`connection`	String	RDB connect string	No

Outputs

Name	Type	Description
`string`	String	JSON result
`status`	String	`OK` or `Error`

Notes

No notes.

Kartra membership platform management

Kartra

Kartra API documentation

You will need to an API from Kartra, which will become a BigBlueRiver Query paraemter.

Returns an acknowdgement of a valid login.

Example

"craig@orapub.com", "abc123 ➔ "OK"

API Base URL

https://bigblueriver.com:8000/kartra/login

Parameters

Name	Type	Description	Required
`email`	String	Email of lead	Yes
`password`	String	Password of lead	Yes
`api_key`	String	Kartra API key	Yes

Outputs

Name	Type	Description
`result`	String	`OK` or `NOK`
`status`	String	`OK` or `Error`

Notes

No notes.

Membership Level

Returns the Kartra membership level

Example

"craig@orapub.com" ➔ "Advantage"

API Base URL

https://bigblueriver.com:8000/kartra/memberlevel

Parameters

Name	Type	Description	Required
`email`	String	Email of member	Yes
`api_key`	String	Kartra API key	Yes

Outputs

Name	Type	Description
`string`	String	Membership level
`status`	String	`OK` or `Error - Lead not found`

Notes

No notes.

Miscelaneous

Send Passcode Email

Use this API to send a passcode reset email.

Example

"katrina@abc.com", "craig@abc.com", "Passcode request", "12345", "8Tmvb5j" ➔ "OK 200"

API Base URL

https://bigblueriver.com:8000/email/passcodesend

Parameters

Name	Type	Description	Required	Default
`from`	String	"From" email	Yes	No default value
`to`	String	"To" or receiptant email	Yes	No default value
`subject`	String	Email submit	Yes	No default value
`passcode`	String	Passcode	Yes	No default value
`sendgrid_api_key`	String	Sendgrid API key	Yes	No default value

Outputs

Name	Type	Description
`status`	String	Status code: 200 OK, 400 ERROR

Notes

The body of the email is simply:

You are receiving this email because there was a password reset request.

Here is your passcode: 12345

API Reference

String API

Words

Length

Uppercase

Lowercase

Tail

Numeric API

Random

Artifical Intelligence

Chat

Tail

Vector Database

Does A Vector Database Exist

What Is My Vector Database Name

Create New Vector Database (VDB)

Create A New Collection

Load Document Into VDB Collection

Similarity Search

Rational Database

SQL

Kartra membership platform management

Kartra

Member Login Validation

Membership Level

Miscelaneous

Send Passcode Email