Asepha Docs
Welcome to the Asepha API documentation. This API enables the development of healthcare AI applications, particularly those that deal with unstructured data. Before diving into the endpoints, let's familiarize ourselves with some common terms you will encounter throughout this documentation.
Agent: You can imagine an agent being a specialized verison of chatgpt. You can give custom instructions and upload a collection of files and websites to an agent. These resources that serve as a reference source for generating answers. An agent will also refer to the uploaded documents and consider the instructions when generating an answer.
File: Text-based data, in PDF or TXT format, that is stored in an agent’s documents. Files are the primary units from which answers are generated.
Website: A URL reference that contains information used in a resource group for generating answers.
Grounded Generation: The process of generating answers or information that are factually accurate and backed by reliable sources, such as documents or websites, specified in resource groups.
Answer Generation: The process of producing a grounded, fact-based answer based on the content of the selected resource groups. This is often achieved using machine learning algorithms.
Note: This API is in the alpha phase, so endpoints and behavior might change as it evolves.
"https://api.asepha.dev"
All API requests must include an Authorization header with a bearer token to verify your identity and grant access to the API. The header should be formatted as follows:
headers = {
"Authorization": f"Bearer {TOKEN}"
}
Replace {TOKEN} with your personal API token, which can be obtained from your account page after creating an account.
Resource Groups serve as collections of documents and websites used to generate grounded answers. These resource groups are selectable by users when generating answers, ensuring that Asepha only references the chosen sets of information.
Create a new resource group by providing its name, description, and optional file or website references.
- HTTP Method: POST
- Endpoint: /v1/resource-groups
Request Body Parameters:
- name: string (required)
- instruction: string (required)
- files: array of binary (optional, PDF/TXT only, max file size TBD)
- websites: array of string (optional, base URLs)
Response Fields
- success: boolean
- message: string
Request Example:
url = /v1/resource-groups/create
data = {
"name": "Resource Group Name",
"description": "Description of the resource group",
"websites": ["https://example.com", "https://anotherexample.com"]
}
files = [
("files", ("fileX", open("test.txt", "rb"))),
("files", ("fileY", open("test.txt", "rb")))
]
response = requests.post(url, headers=headers, data=data, files=files)
Response Example:
{
"success": true,
"message": "Resource group 'MedicalResearch' successfully created."
}
HTTP Status Codes:
- 201 Created: Successfully created a new resource group.
- 400 Bad Request: The request was invalid or missing required parameters (e.g., name or description).
- 409 Conflict: A resource group with the specified name already exists.
- 413 Payload Too Large: The uploaded files exceed the maximum allowed size.
- 500 Internal Server Error: Unexpected server error.
List all available resource groups.
- HTTP Method: GET
- Endpoint: /v1/resource-groups
Response Fields:
- list: array of object (name and description)
Request Example:
url = "https://api.asepha.dev/v1/resource-groups"
response = requests.get(url, headers=headers)
Response Example:
[
{"name": "MedicalResearch", "instruction": "Group containing medical research papers"},
{"name": "Pharmaceuticals", "instruction": "Group containing pharmaceutical studies"}
]
HTTP Status Codes:
- 200 OK: Successfully retrieved the list of resource groups.
- 401 Unauthorized: The client is not authenticated.
- 403 Forbidden: The client is authenticated but does not have permission to perform this operation.
- 500 Internal Server Error: Unexpected server error.
Retrieve detailed information about a specific resource group.
- HTTP Method: GET
- Endpoint: /v1/resource-groups/{name}
Response Fields:
- resource_group: object (name, instruction, websites , processed_files , processing_files)
Request Example:
url = "https://api.asepha.dev/v1/resource-groups/MedicalResearch"
response = requests.get(url, headers=headers)
Response Example:
{
"name": "MedicalResearch",
"instruction": "MedicalResearch model instruction set",
"websites": ["MedicalResearch"],
"processed_files":[ "MeningitisPaper"],
"processing_files": ["BrainTumor", "SpinalCordDiagram",]
}
HTTP Status Codes:
- 200 OK: Successfully retrieved the specified resource group.
- 401 Unauthorized: The client is not authenticated.
- 403 Forbidden: The client is authenticated but does not have permission to perform this operation.
- 404 Not Found: The specified resource group does not exist.
- 500 Internal Server Error: Unexpected server error.
Update an existing resource group's model instruction set.
- HTTP Method: PATCH
- Endpoint: /v1/resource-groups/{name}
Request Body Parameters:
- instruction: string (required)
Response Fields:
- success: boolean
- message: string
Request Example:
url = "https://api.asepha.dev/v1/resource-groups/MedicalResearch"
payload = {
"description": "Group containing updated medical research papers"
}
# Payload in json field
response = requests.patch(url, json=payload, headers=headers)
Response Example:
{
"success": true,
"message": "Resource group 'MedicalResearch' description successfully updated."
}
HTTP Status Codes:
- 200 OK: Successfully updated the specified resource group.
- 400 Bad Request: The client is not authenticated.
- 401 Unauthorized: The client is not authenticated.
- 403 Forbidden: The client is authenticated but does not have permission to perform this operation.
- 404 Not Found: The specified resource group does not exist.
- 500 Internal Server Error: Unexpected server error.
Delete an existing resource group by its name.
- HTTP Method: DELETE
- Endpoint: /v1/resource-groups/{name}
Response Fields:
- success: boolean
- message: string
Request Example:
url = "https://api.asepha.dev/v1/resource-groups/MedicalResearch"
response = requests.delete(url, headers=headers)
Response Example:
{
"success": true,
"message": "Resource group 'MedicalResearch' description successfully deleted."
}
HTTP Status Codes:
- 204 No Content: Successfully deleted the specified resource group.
- 401 Unauthorized: The client is not authenticated.
- 403 Forbidden: The client is authenticated but does not have permission to perform this operation.
- 404 Not Found: The specified resource group does not exist.
- 500 Internal Server Error: Unexpected server error.
Documents can be either files or websites containing relevant information for answer generation. Asepha automatically processes these documents when added to a resource group.
Upload one or more documents into an existing resource group. This operation is performed asynchronously. You can check the status of the uploaded documents by referring to the
Retrieve Document Information endpoint.
- HTTP Method: POST
- Endpoint: /v1/resource-groups/{resource_group_name}/documents
- Asynchronous: Yes
Request Body Parameters:
- files: array of binary (optional, PDF/TXT only, max file size TBD per file)
- websites: array of string (optional, base URLs)
Initial Response Fields:
- success: boolean
- documents: array of object (type and identifier)
- message: string
Request Example:
# Upload a PDF and a website URL
files = {'file1': ('file1.pdf', open('file1.pdf', 'rb'))}
websites = ["https://www.example.com"]
resource_group_name = 'medical_data'
response = requests.post(
f"https://api.asepha.dev/v1/resource-groups/{resource_group_name}/documents",
files=files,
json={'websites': websites},
headers=headers
)
Response Example:
{
"success": true,
"documents": [
{"type": "file", "identifier": "file1"},
{"type": "website", "identifier": "www.example.com"}
],
"message": "Documents successfully uploaded to 'medical_data' resource group. It is an asynchronous operation; please refer to the Retrieve Document Information endpoint for status."
}
HTTP Status Codes:
- 201 Created: Successfully initiated document upload; processing asynchronously.
- 400 Bad Request: Invalid request parameters, such as unsupported file types or exceeded file sizes.
- 401 Unauthorized: Missing or invalid authentication token.
- 404 Not Found: The specified resource group does not exist.
- 429 Too Many Requests: Rate limit exceeded.
- 500 Internal Server Error: Unexpected server error.
Retrieve information about a specific document within a resource group.
- HTTP Method: GET
- Endpoint: /v1/resource-groups/{resource_group_name}/documents/{document_name}
Response Fields:
- success: boolean
- info: object (type , name , status, optionally url)
- message: string
Request Example:
resource_group_name = 'medical_data'
document_name = 'file1'
response = requests.get(f"https://api.asepha.dev/v1/resource-groups/{resource_group_name}/documents/{document_name}", headers=headers)
Response Example:
{
"success": true,
"info": {
"type": "file",
"name": "file1",
"status": "processed",
"url": "https://storage.asepha.dev/file1.pdf"
},
"message": "Successfully retrieved information for document 'file1' in resource group 'medical_data'."
}
HTTP Status Codes:
- 200 OK: Successfully retrieved document information.
- 400 Bad Request: Invalid request parameters.
- 401 Unauthorized: Missing or invalid authentication token.
- 404 Not Found: The specified document or resource group does not exist.
- 500 Internal Server Error: Unexpected server error.
Remove a document from a resource group.
- HTTP Method: DELETE
- Endpoint: /v1/resource-groups/{resource_group_name}/documents/{document_name}
Response Fields:
- success: boolean
- message: string
Request Example:
resource_group_name = 'medical_data'
document_name = 'file1'
response = requests.delete(f"https://api.asepha.dev/v1/resource-groups/{resource_group_name}/documents/{document_name}", headers=headers)
Response Example:
{
"success": true,
"message": "Successfully deleted document 'file1' from resource group 'medical_data'."
}
HTTP Status Codes:
- 204 No Content: Document successfully deleted.
- 400 Bad Request: Invalid request parameters.
- 401 Unauthorized: Missing or invalid authentication token.
- 404 Not Found: Specified document or resource group does not exist.
- 500 Internal Server Error: Unexpected server error.
Generate a grounded answer based on specified resource groups and parameters.
- HTTP Method: POST
- Endpoint: /v1/answer/generation
Request Body Parameters:
- query: string (required)
- resources: array of string (required, e.g. ["drugs", "conditions", "custom_group"] )
- answer_type: string (optional, "concise" or "detailed")
- instructions: string (optional)
- streaming: boolean (optional, default: false )
Request Example:
query = "What are the side effects of aspirin?"
resources = ["drugs", "conditions", "medical_data"]
answer_type = "detailed"
instructions = "Provide citations when possible."
streaming = False
response = requests.post(
"https://api.asepha.dev/v1/answer/generation",
json={
'query': query,
'resources': resources,
'answer_type': answer_type,
'instructions': instructions,
'streaming': streaming
},
headers=headers
)
Response Example:
- Note: Streaming or non-streaming responses containing generated answers based on the chosen resource groups.
{
"success": true,
"answer": "The side effects of aspirin include upset stomach, heartburn, ...",
"citation": ["www.pubmed.gov/article1", "www.website.com", "class_notes.txt"]
"message": "Successfully generated a detailed answer for the query 'What are the side effects of aspirin?' using the specified resource groups."
}
HTTP Status Codes:
- 201 Created: Successfully initiated answer generation; processing asynchronously if the streaming flag is true.
- 400 Bad Request: Invalid request parameters, such as invalid query or resources.
- 401 Unauthorized: Missing or invalid authentication token.
- 429 Too Many Requests: Rate limit exceeded.
- 500 Internal Server Error: Unexpected server error.
