Download OpenAPI specification:Download
The Totalum API allows you to consume create and modify all totalum data. With this API, you can automate common tasks such as creating, updating, and deleting resources, as well as retrieving information about your current project. The API uses standard HTTP methods, such as GET, POST, PATCH, and DELETE, and returns data in JSON format.
Whether you're a developer looking to use Totalum as your backend or integrate Totalum with other software, the Totalum API is the perfect solution.
Are you a javascript, typescript or nodejs user? If is the case take a look at totalumApiSdk here. I recommend to use the sdk because is easy to use as the library autocomplete the methods.
This API returns the following HTTP status codes in response to API requests:
Status Code | Description |
---|---|
200 OK | The request was successful and the response includes the requested data. |
400 Bad Request | The request was invalid, and the response includes a problem-details object. |
401 Unauthorized | The API key provided was missing or invalid. |
403 Forbidden | The API key provided does not have access to the requested resource. |
404 Not Found | The requested resource could not be found on the server. |
429 Too Many Requests | The rate limit has been exceeded, and the response includes details. |
500 Internal Server Error | An unexpected error occurred. |
503 Service Unavailable | The server is currently unable to handle the request due to a temporary overload or scheduled maintenance. |
In addition to the HTTP status code, each response from the API includes a problem-details object that provides more information about the error, if applicable. This object includes a title and a detail field that describe the error, and may also include additional information such as a traceId
that is used to uniquely identify the request.
The rate limit depends of what resource are you calling and what plan you have, this API has a rate limit of:
If you exceed the API rate limit, the API will return a 429 Too Many Requests HTTP status code and a JSON response with the information about.
This pagination is only for get crud and filter endpoints, for the rest of the api, the pagination is no needed and dones't exists
The API uses a combination of page
and limit
query parameters to paginate returned data. By default, the API returns up to 50 results per request. To retrieve additional pages, you can specify the page
and limit
parameters in your API request.The limit
, specifies the items per page, and the page
specifies the page. page
starts from 0
To access this API, you must include an API key in the api-key
header of your API requests. The API key is used to authenticate and authorize your API requests. You can generate and manage your API keys from the Totalum Api keys.
curl -X $METHOD \
-H "Accept: application/json" \
-H "api-key: $TOTALUM_API_KEY" \
$URL
It is important to keep your API keys secure and to only use them in server-side applications. Do not include API keys in client-side code that is not inside totalum, as this can compromise the security of your API keys. If you suspect that your API key has been compromised, you can delete it from the Totalum api key manager.
Get all users that can login to this totalum project
curl --request GET \ --url https://api.totalum.app/api/v1/user/ \ --header 'api-key: REPLACE_KEY_VALUE'
[- {
- "name": "John Doe",
- "password": "password123!",
- "role": "user",
- "access": {
- "pages": {
- "2k34nk26n234kn54453": {
- "read": true,
- "write": false
}, - "lk34l5k43l5k34543": {
- "read": true,
- "write": true
}
}, - "customPages": {
- "234hv23jh4j234g23j4": {
- "read": true
}
}, - "types": {
- "634h6j4h365jh45j45": {
- "read": true,
- "write": true
}
}
}
}
]
Create new user that can login to this totalum project
name required | string |
email required | string <email> |
password required | string <password> |
role required | string Enum: "admin" "manager" "user" |
object pages, customPages and types, are a hashmap with the ids of pages and types (for check ids go to Totalum configuration page) |
{- "name": "John Doe",
- "password": "password123!",
- "role": "user",
- "access": {
- "pages": {
- "2k34nk26n234kn54453": {
- "read": true,
- "write": false
}, - "lk34l5k43l5k34543": {
- "read": true,
- "write": true
}
}, - "customPages": {
- "234hv23jh4j234g23j4": {
- "read": true
}
}, - "types": {
- "634h6j4h365jh45j45": {
- "read": true,
- "write": true
}
}
}
}
curl --request GET \ --url https://api.totalum.app/api/v1/user/current \ --header 'api-key: REPLACE_KEY_VALUE'
{- "name": "John Doe",
- "password": "password123!",
- "role": "user",
- "access": {
- "pages": {
- "2k34nk26n234kn54453": {
- "read": true,
- "write": false
}, - "lk34l5k43l5k34543": {
- "read": true,
- "write": true
}
}, - "customPages": {
- "234hv23jh4j234g23j4": {
- "read": true
}
}, - "types": {
- "634h6j4h365jh45j45": {
- "read": true,
- "write": true
}
}
}
}
Get user by id
id required | string Example: 5f9b3b3b3b3b3b3b3b3b3b3b User ID |
curl --request GET \ --url https://api.totalum.app/api/v1/user/{id} \ --header 'api-key: REPLACE_KEY_VALUE'
{- "name": "John Doe",
- "password": "password123!",
- "role": "user",
- "access": {
- "pages": {
- "2k34nk26n234kn54453": {
- "read": true,
- "write": false
}, - "lk34l5k43l5k34543": {
- "read": true,
- "write": true
}
}, - "customPages": {
- "234hv23jh4j234g23j4": {
- "read": true
}
}, - "types": {
- "634h6j4h365jh45j45": {
- "read": true,
- "write": true
}
}
}
}
Edit user by id
id required | string |
name required | string |
email required | string <email> |
password required | string <password> |
role required | string Enum: "admin" "manager" "user" |
object pages, customPages and types, are a hashmap with the ids of pages and types (for check ids go to Totalum configuration page) |
{- "name": "John Doe",
- "password": "password123!",
- "role": "user",
- "access": {
- "pages": {
- "2k34nk26n234kn54453": {
- "read": true,
- "write": false
}, - "lk34l5k43l5k34543": {
- "read": true,
- "write": true
}
}, - "customPages": {
- "234hv23jh4j234g23j4": {
- "read": true
}
}, - "types": {
- "634h6j4h365jh45j45": {
- "read": true,
- "write": true
}
}
}
}
Delete user by id
id required | string |
curl --request DELETE \ --url https://api.totalum.app/api/v1/user/{id} \ --header 'api-key: REPLACE_KEY_VALUE'
Get all data structures (all tables database structure)
curl --request GET \ --url https://api.totalum.app/api/v1/data-structure/ \ --header 'api-key: REPLACE_KEY_VALUE'
Get columns values of a page
id required | string |
type required | string |
ids | any |
{- "ids": "an array of items ids (an array of strings)"
}
Get an item by id
typeId required | string The name of the table type you want to get the data. Example: |
id required | string The id of the item you want to get |
curl --request GET \ --url https://api.totalum.app/api/v1/crud/{typeId}/{id} \ --header 'api-key: REPLACE_KEY_VALUE'
{ }
Edit an item by id
typeId required | string The name of the table type you want to edit the data. Example: |
id required | string The id of the item you want to edit |
set the properties and values of the item type you want to edit
additional property | string or number or boolean or string |
{- "property1": "string",
- "property2": "string"
}
Delete an item by id
typeId required | string The name of the table type you want to delete the data. Example: |
id required | string The id of the item you want to delete |
curl --request DELETE \ --url https://api.totalum.app/api/v1/crud/{typeId}/{id} \ --header 'api-key: REPLACE_KEY_VALUE'
Get items of an table
typeId required | string The name of the table type you want to get the data. Example: |
filter | string Example: (Optional) JSON Filter query in string format |
object (Optional) Sort by property, put 'propertyName': 1 or -1 | |
object (Optional) pagination | |
returnCount | boolean (Optional) set true if you want to get the number of total results of this query |
curl --request GET \ --url 'https://api.totalum.app/api/v1/crud/{typeId}?filter=[{"or": [{"status": "active"}, {"age": {"gte": 18, "lte": 60}}], "category": {"regex": "^tech", "options": "i"}, "createdDate": {"gt": "2023-01-01"}}]&sort=SOME_OBJECT_VALUE&pagination=SOME_OBJECT_VALUE&returnCount=SOME_BOOLEAN_VALUE' \ --header 'api-key: REPLACE_KEY_VALUE'
[- {
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "_id": "string",
- "additionalProperties": "string"
}
]
Crete new item
typeId required | string The name of the table type you want to create the data. Example: |
set the required properties of the item type you want to create
additional property | string or number or boolean or string |
{- "property1": "string",
- "property2": "string"
}
Get items with nested properties
set the nested query for the items you want to get
object (NestedQuery) |
{- "nestedQuery": {
- "property1": {
- "tableFilter": {
- "filter": [
- {
- "or": [
- {
- "property1": 0,
- "property2": 0
}
], - "additionalProperties": 0
}
], - "sort": {
- "property1": 1,
- "property2": 1
}, - "pagination": {
- "limit": 0,
- "page": 0
}
}, - "propertyName": "string",
- "property1": { },
- "property2": { }
}, - "property2": {
- "tableFilter": {
- "filter": [
- {
- "or": [
- {
- "property1": 0,
- "property2": 0
}
], - "additionalProperties": 0
}
], - "sort": {
- "property1": 1,
- "property2": 1
}, - "pagination": {
- "limit": 0,
- "page": 0
}
}, - "propertyName": "string",
- "property1": { },
- "property2": { }
}
}
}
get many to many relation items of an item
typeId required | string the table name of the element you want to get references, for example if you have 2 tables linked with many to many, one is |
id required | string the id of the item you want to get the many to many references |
propertyName required | string the property name that have the many to many reference between the tables |
filter | string Example: (Optional) JSON Filter query in string format |
object (Optional) Sort by property, put 'propertyName': 1 or -1 | |
object (Optional) pagination |
curl --request GET \ --url 'https://api.totalum.app/api/v1/crud/{typeId}/{id}/{propertyName}?filter=[{"or": [{"status": "active"}, {"age": {"gte": 18, "lte": 60}}], "category": {"regex": "^tech", "options": "i"}, "createdDate": {"gt": "2023-01-01"}}]&sort=SOME_OBJECT_VALUE&pagination=SOME_OBJECT_VALUE' \ --header 'api-key: REPLACE_KEY_VALUE'
[- {
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "_id": "string",
- "additionalProperties": "string"
}
]
Add new item referenced in many to many
typeId required | string The name of the table type you want to add the many to many reference. Example: |
id required | string The id of the item you want to add as many to many reference |
The needed data for adding a many-to-many item between tables
propertyId required | string The identifier for the property. |
referenceId required | string The id for the item that we will add the reference. |
{- "propertyId": "string",
- "referenceId": "string"
}
Delete many to many reference
typeId required | string The name of the table type you want to drop the many to many reference. Example: |
id required | string The id of the item you want to drop the many to many reference |
The needed data for delete a many-to-many reference item between tables. ALERT: THIS DOESN'T DELETE THE ITEM, IT ONLY DELETE THE REFERENCE BETTWEEM ITEMS, SO FINALLY, THE ITEMS STILL BE HERE BUT WITHOUT REFERENCE BETTWEEN THEM.
propertyId required | string The identifier for the property. |
referenceId required | string The id for the item that we will add the reference. |
{- "propertyId": "string",
- "referenceId": "string"
}
Delete the object with id equal to id, but also delete all children elements referenced in page structure levels
typeId required | string |
id required | string |
pageId required | string |
curl --request DELETE \ --url https://api.totalum.app/api/v1/crud/{typeId}/{id}/{pageId}/subelements \ --header 'api-key: REPLACE_KEY_VALUE'
Get an object with full historical updates of the item
objectId required | string the item id that we want to get modification historic |
curl --request GET \ --url https://api.totalum.app/api/v1/updates-record/{objectId} \ --header 'api-key: REPLACE_KEY_VALUE'
idPage required | string |
query | string |
idsOfMultipleNodesToSearch | string |
returnCount | string |
curl --request GET \ --url 'https://api.totalum.app/api/v1/filter/{idPage}/?query=SOME_STRING_VALUE&idsOfMultipleNodesToSearch=SOME_STRING_VALUE&returnCount=SOME_STRING_VALUE' \ --header 'api-key: REPLACE_KEY_VALUE'
[- {
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "_id": "string",
- "additionalProperties": "string"
}
]
DEPRECATED, PLEASE NOT USE IT
returnCount | string |
typeIdToGet | any |
variables | any |
customMongoFilter | any |
pagination | any |
rootTypeId | any |
sort | any |
{- "typeIdToGet": "any",
- "variables": "any",
- "customMongoFilter": "any",
- "pagination": "any",
- "rootTypeId": "any",
- "sort": "any"
}
Do a custom mongodb aggregation query
customMongoQuery | string your custom mongodb aggregation query in string format |
type | string The table name you want to start to do the mongodb aggregation query |
{- "customMongoQuery": " [ { $match: { \"price\": {$gte: 10} } }, // Join the data_product with data_provider using provider as the linking _id { $lookup: { from: \"data_provider\", // we add the prefix \"data_\" to the table name localField: \"provider\", foreignField: \"_id\", as: \"provider\" // Now storing the result directly in the \"proveedor\" field } }, { $match: { \"provider.name\": \"John\" } }, // Simplify the proveedor to be an object instead of an array { $addFields: { \"proveedor\": { $arrayElemAt: [\"$proveedor\", 0] } } } ]",
- "type": "client"
}
{ }
Upload a new file to cloud, in the code snippets is missing the part of upload the form-data, so don't forget to add it
File to be uploaded
file | string <binary> The file to upload in binary (in blob format). |
fileName | string The name of the file. |
curl --request POST \ --url https://api.totalum.app/api/v1/files/upload \ --header 'api-key: REPLACE_KEY_VALUE' \ --header 'content-type: multipart/form-data'
"yourFile-t3t43t34t.png"
Do ocr of the image and return the result with the text
fileName | string The file name id of an image (png, jpg, etc.) upload to totalum |
{- "fileName": "your-file-234234324.png"
}
{ }
Do ocr of the pdf and return the result with the text
fileName | string The file name id of a pdf upload to totalum |
{- "fileName": "your-file-234234324.pdf"
}
{ }
Scan the invoice and return a json with the invoice details
fileName | string The file name id of invoice document uploaded to totalum in image or pdf format |
options | object The options for the scan |
{- "fileName": "your-file-234234324.pdf",
- "options": { }
}
{ }
Scan a custom document (image or pdf) and return a json with custom values of the document
fileName | string The file name id of document uploaded to totalum in image or pdf format |
properties | object The properties in json schema format that you want to get from the document. You can the properties with your custom names and descriptions |
options | object The options for the scan |
{- "fileName": "your-file-234234324.pdf",
- "properties": {
- "name": {
- "type": "string",
- "description": "The name of the person"
}, - "age": {
- "type": "number",
- "description": "The age of the person"
}, - "date": {
- "type": "string",
- "format": "date",
- "description": "The date of the document"
}
}, - "options": { }
}
{ }
Get the url for download a file of totalum
fileName required | string Example: your-file-name-id.pdf the file name id of a file opload to totalum |
curl --request GET \ --url https://api.totalum.app/api/v1/files/download/{fileName} \ --header 'api-key: REPLACE_KEY_VALUE'
Delete a file with name equals to fileName param
fileName required | string |
curl --request DELETE \ --url https://api.totalum.app/api/v1/files/{fileName} \ --header 'api-key: REPLACE_KEY_VALUE'
curl --request GET \ --url https://api.totalum.app/api/v1/data-deleted/ \ --header 'api-key: REPLACE_KEY_VALUE'
Get data deleted by id
id required | string |
curl --request GET \ --url https://api.totalum.app/api/v1/data-deleted/{id} \ --header 'api-key: REPLACE_KEY_VALUE'
Undo item deleted by id
objectId required | string |
curl --request PUT \ --url https://api.totalum.app/api/v1/data-deleted/undo-delete-object/{objectId} \ --header 'api-key: REPLACE_KEY_VALUE'
Get backup file url ready to download from backupFileName
backupFileName required | string |
curl --request GET \ --url https://api.totalum.app/api/v1/backup/{backupFileName} \ --header 'api-key: REPLACE_KEY_VALUE'
Get current Totalum project info
curl --request GET \ --url https://api.totalum.app/api/v1/organization/ \ --header 'api-key: REPLACE_KEY_VALUE'
Edit current Totalum project info
name | any |
profilePhoto | any |
userCategories | any |
showTutorial | any |
{- "name": "any",
- "profilePhoto": "any",
- "userCategories": "any",
- "showTutorial": "any"
}
Generate a pdf from pdfTemplateId and input variables
id required | string The id of the pdf template you want to use to generate the pdf |
variables | object The variables in JSON format that you want to use in the pdf template. Can be a JSON of any format and of any deep |
name | string The name of the pdf file that will be generated |
{- "variables": "{\"your-variable\": \"your-value\"}",
- "name": "yourFile.pdf"
}
"string"
Create a openai gpt completion (DEPRECATED, use chat-completion)
curl --request POST \ --url https://api.totalum.app/api/v1/openai/completion \ --header 'api-key: REPLACE_KEY_VALUE'
Create a chatgpt completion
The openai chat completion object, for more info see https://platform.openai.com/docs/api-reference/completions/create
{ }
{ }
Generate an image from a propt
The openai image generation object, for more info see https://platform.openai.com/docs/api-reference/completions/create
{ }
"string"
curl --request GET \ --url https://api.totalum.app/api/v1/integrations/get-tables \ --header 'api-key: REPLACE_KEY_VALUE'
[- {
- "id": "string",
- "label": "string"
}
]
Get the properties structure of a table
id | string the tableId of the table you want to get the structure |
usage | string Example: usage=filter should be one of the following words 'filter' (for return the fields of a table that is posible to filter) or 'create' (for return the fields that you can fill for create a record) or 'edit' (for return the fields that you can fill for edit a record) or 'files' (For return the fields that are file type from a table) or 'read' (for return the fields that you can read from a table record) |
curl --request GET \ --url 'https://api.totalum.app/api/v1/integrations/get-table-structure?id=SOME_STRING_VALUE&usage=filter' \ --header 'api-key: REPLACE_KEY_VALUE'
[- {
- "name": "string",
- "label": "string",
- "type": "string",
- "required": true,
- "value": "string",
- "spec": [
- {
- "name": "string",
- "label": "string",
- "type": "string"
}
]
}
]
Get new created records from a table based on a filter
tableId required | string |
limit | string The limit of new created records that match your filter that you want to get |
Array of objects (integrationFilter) |
{- "filter": "[{'field': '423423f2', 'value': 'Jack' },{'field': '42334233s', 'value': 'Jones' }]"
}
[- {
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "_id": "string",
- "additionalProperties": "string"
}
]
Delete one or multiple records based on a filter
tableId required | string |
limit | string The limit of records that match your filter that you want to delete |
Array of objects (integrationFilter) |
{- "filter": "[{'field': '423423f2', 'value': 'Jack' },{'field': '42334233s', 'value': 'Jones' }]"
}
Update one or multiple records of a table based on a filter
tableId required | string |
limit | string The limit of records that match your filter that you want to update |
Array of objects (integrationFilter) | |
Array of objects (integrationFilter) |
{- "filter": "[{'field': '423423f2', 'value': 'Jack' },{'field': '42334233s', 'value': 'Jones' }]",
- "newProperties": "[{'field': '423423f2', 'value': 'Jack' },{'field': '42334233s', 'value': 'Jones' }]"
}
Search records from a table based on a filter
tableId required | string |
limit | string The limit of records that match your filter that you want to get |
Array of objects (integrationFilter) |
{- "filter": "[{'field': '423423f2', 'value': 'Jack' },{'field': '42334233s', 'value': 'Jones' }]"
}
[- {
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "_id": "string",
- "additionalProperties": "string"
}
]
Upload a file to totalum and link file with one or more records based on a filter
table | string The tableId where you want to link the file |
file_field | string The propertyId of the file field where you want to link the file |
filter | string Example: filter=W3snZmllbGQnOiAnNDIzNDIzZjInLCAndmFsdWUnOiAnSmFjaycgfSx7J2ZpZWxkJzogJzQyMzM0MjMzcycsICd2YWx1ZSc6ICdKb25lcycgfV0= Filter the records to link the file,The filter object string should be in base64, you should transform an string like this: '[{'field': '423423f2', 'value': 'Jack' },{'field': '42334233s', 'value': 'Jones' }]' to base64, where field is the propertyId and value is the value of the property you want to filter |
limit | string The limit of records that you want to link the file |
File to be uploaded
file | string <binary> The file to upload in binary (in blob format). |
fileName | string The name of the file. |
curl --request POST \ --url 'https://api.totalum.app/api/v1/integrations/upload-file?table=SOME_STRING_VALUE&file_field=SOME_STRING_VALUE&filter=SOME_STRING_VALUE&limit=SOME_STRING_VALUE' \ --header 'api-key: REPLACE_KEY_VALUE' \ --header 'content-type: multipart/form-data'
Get last deleted records from a table
tableId required | string |
limit | number The limit of deleted records that match your filter that you want to get |
Array of objects (integrationFilter) |
{- "filter": "[{'field': '423423f2', 'value': 'Jack' },{'field': '42334233s', 'value': 'Jones' }]"
}
[- {
- "createdAt": "2019-08-24T14:15:22Z",
- "updatedAt": "2019-08-24T14:15:22Z",
- "_id": "string",
- "additionalProperties": "string"
}
]