API reference
Record types
List record types
This endpoint returns the available record types, e.g. movie
, organization
, person
, etc.
Response parameters
name
Name of the record type.
label
Label of the record type.
creatable
The record type supports operation create
.
updatable
The record type supports operation update
.
readable
The record type supports operation read
.
searchable
The record type supports operation search
.
searchesIn
The list of parameters to search by in the records of the record type.
deletable
The record type suuports operation delete
.
triggerable
The record type supports firing webhooks when a new event is logged.
The record type records the date and time of the event.
This endpoint retrieves available record types.
Access token for authorization.
GET /api/v3/recordTypes HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
{
"recordTypes": [
{
"name": "movie",
"label": "Movie",
"creatable": true,
"updatable": true,
"readable": true,
"searchable": true,
"searchesIn": [
"text"
],
"deletable": true
}
]
}
This endpoint retrieves JSON file of a record type.
Name of the record to work with.
Access token for authorization.
GET /api/v3/recordTypes/{name} HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
{
"recordParameters": [
{
"name": "id",
"label": "ID",
"mandatory": true,
"readable": true,
"updatable": true,
"refersTo": "organization",
"type": "text",
"nestedParameters": [
{
"name": "id",
"label": "ID",
"mandatory": true,
"readable": true,
"updatable": true,
"refersTo": "organization",
"type": "text",
"nestedParameters": [
"[Circular Reference]"
]
}
]
}
]
}
Retrieve a record type
This endpoint retrieves the JSON file of a record type. This JSON file contains the list of parameters available in the record type.
Response parameters
name
Name of the parameter.
label
Label of teh parameter.
mandatory
The parameter is mandatory.
readable
The parameter is returned in the response body when the record is fetched.
updatable
The parameter can be used to create/update a record.
refersTo
Name of the record type to which the parameter refers. Only available for the parameters of type ID.
type
JSON type of the parameter, e.g. text
, number
, array
.
nestedParameters
The parameters that are nested to the parameter.
Retrieves records. E.g. movies.
Type of the record to retrieve, e.g. movie.
The number of records to skip.
5
Access token for authorization.
POST /api/v3/{recordType}/query HTTP/1.1
Host: app-academy.make.com
authorization: text
Content-Type: application/json
Accept: */*
OK
{
"totalRecordsReturned": 5,
"records": [
{
"id": "1dca6a93fcf1",
"name": "Robert Downey Jr.",
"createdAt": "2023-04-13T17:04:47+00:00",
"updatedAt": "2023-04-13T17:04:47+00:00"
}
]
}
Records
Retrieves records. E.g. movies.
Type of the record to retrieve, e.g. movie.
The number of records to skip.
5
Access token for authorization.
POST /api/v3/{recordType}/query HTTP/1.1
Host: app-academy.make.com
authorization: text
Content-Type: application/json
Accept: */*
OK
{
"totalRecordsReturned": 5,
"records": [
{
"id": "1dca6a93fcf1",
"name": "Robert Downey Jr.",
"createdAt": "2023-04-13T17:04:47+00:00",
"updatedAt": "2023-04-13T17:04:47+00:00"
}
]
}
Filtering records
The search records endpoint supports chained filters. The filter is sent in body of the request.
{
"or":[
{
"and":[
{
"property": "name",
"startsWith": "R"
},
{
"property": "name",
"contains": "o"
}
]
},
{
"and":[
{
"property": "name",
"startsWith": "G"
},
{
"property": "name",
"contains": "w"
}
]
}
]
}
In addition to chained filters, records can be queried with single filters as well.
{
"and":[
{
"property": "name",
"startsWith": "R"
}
]
}
Supported operators for filtering
startsWith
endsWith
contains
equalsTo
Retrieve a record
Retrieves the record by its ID.
Type of the record to retrieve, e.g. movie.
ID of the record to work with.
Access token for authorization.
GET /api/v3/{recordType}/{id} HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
No content
Create a record
Creates a new record. E.g. a movie.
Type of the record to retrieve, e.g. movie.
Access token for authorization.
POST /api/v3/{recordType} HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
No content
Update a record
Updates the record by its ID.
Type of the record to retrieve, e.g. movie.
ID of the record to work with.
Access token for authorization.
PATCH /api/v3/{recordType}/{id} HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
No content
Delete a record
Deletes the record by its ID.
Type of the record to retrieve, e.g. movie.
ID of the record to work with.
Access token for authorization.
DELETE /api/v3/{recordType}/{id} HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
No content
Retrieves the list of files or folders.
ID of the parent to work with.
Identification of the page to retrieve.
Access token for authorization.
GET /api/v3/files HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
{
"totalPages": 2,
"items": [
{
"name": "test.txt",
"parent": "e4677852dffe",
"id": "dj789jdj344i",
"type": "folder"
}
]
}
Files/Folders
Retrieve files or folders
Retrieves the list of files or folders.
ID of the parent to work with.
Identification of the page to retrieve.
Access token for authorization.
GET /api/v3/files HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
{
"totalPages": 2,
"items": [
{
"name": "test.txt",
"parent": "e4677852dffe",
"id": "dj789jdj344i",
"type": "folder"
}
]
}
Download a file
Downloads a file.
ID of the record to work with.
Access token for authorization.
GET /api/v3/files/{id} HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
No content
Delete a file
Deletes a file.
ID of the record to work with.
Access token for authorization.
DELETE /api/v3/files/{id} HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
No content
Upload a file
The maximum size of a file one can upload to an upload session is 4 bytes. A single request within the upload session cannot exceed 1 byte. Example: If a file has 4 bytes, the file has to be split into 4 separate requests containing a block of data (bytes).
Step one: Open a slot for a file uplod
Open a slot for an upload session and save the file's name and the given file path where the file should be uploaded.
Only one slot can be open at a time. The slot can be open for max 1 minute. The session is dropped if the file upload is not finished by that time or if the upload session ends up with an error.
Creates a session ID for a file upload. Stores a file name and the final location of the file (full path to the folder is required).
Creates a session ID for a file upload. Stores a file name and the final location of the file (full path to the folder is required).
Access token for authorization.
/8c6e22b7f1a0/e4673b2dff5e/1dca6a93fcf1
test.txt
POST /api/v3/files/upload/openSlot HTTP/1.1
Host: app-academy.make.com
authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 72
{
"path": "/8c6e22b7f1a0/e4673b2dff5e/1dca6a93fcf1",
"fileName": "test.txt"
}
OK
{
"session_id": "e4677852dffe"
}
Step two: Upload the first block of data of the file
Upload the first block of data to an uplaod session.
Uploads the first block of data of a file.
Access token for authorization.
Session ID of the file upload.
application/octet-stream
application/octet-stream
raw(binary)
POST /api/v3/files/upload/start HTTP/1.1
Host: app-academy.make.com
authorization: text
session-id: text
content-type: text
Content-Type: application/octet-stream
Accept: */*
Content-Length: 13
"raw(binary)"
OK
{
"session_id": "e4677852dffe"
}
Step three: Upload the other blocks of data of the file
Append more data to an upload session.
Uploads the other blocks of data (bytes) of a file, except the last block of data.
Access token for authorization.
Session ID of the file upload.
application/octet-stream
application/octet-stream
Identification of the byte's order in the file to upload.
raw(binary)
POST /api/v3/files/upload/append HTTP/1.1
Host: app-academy.make.com
authorization: text
session-id: text
content-type: text
offset: 1
Content-Type: application/octet-stream
Accept: */*
Content-Length: 13
"raw(binary)"
OK
{
"session_id": "e4677852dffe"
}
Step four: Upload the last block of data of the file and close the session
Finish the upload session by uploading the last block (byte) of the file's data.
Uploads the last block of data a file and closes the session.
Access token for authorization.
Session ID of the file upload.
application/octet-stream
application/octet-stream
raw(binary)
POST /api/v3/files/upload/finish HTTP/1.1
Host: app-academy.make.com
authorization: text
session-id: text
content-type: text
Content-Type: application/octet-stream
Accept: */*
Content-Length: 13
"raw(binary)"
OK
{
"file_id": "test.txt"
}
Webhooks
Verification of the webhook
The Make Academy API version 3 uses a digital signature which is generated using the secret key entered when creating a webhook and the body of the webhook’s request. This data is contained within the Signature
header.
The header contains the SHA algorithm used to generate the signature. To verify that the request originates from the App Academy API, you'll need to compute the HMAC 256 using your secret key and the body and compare it to the signature contained in the header. The successful matching of these values ensures that the webhook's source is the App Academy API.
Example of computing HMAC 256 in JavaScript
import * as crypto from 'crypto';
function generateHMACSHA256(secretKey: string, data: string): string {
const hmac = crypto.createHmac('sha256', secretKey);
hmac.update(data);
return hmac.digest('hex');
}
const secretKey ='yourSecretKey';
const body ='yourBodyContent';
const hmacSHA256 = generateHMACSHA256(secretKey, body);
console.log(`HMAC-SHA256: ${hmacSHA256}`);
Responding to the webhook
When a webhook is attached, the verification payload is sent to the webhook. You must respond with the correct HTTP code:
200
for correct signature400
for incorrect signature
For the 400 code, you must respond with the following response:
Headers
"Content-type": "application/json"
Body
{
"message": "Invalid signature"
}
Webhook's payload
Payload parameters
eventType
The type of event that fired the webhook. Available types: verification
, create
, update
.
data
The body of the record type.
{
"eventType": "verification",
"data": {...}
}
Attach a webhook
Attaches a new webhook.
Access token for authorization.
POST /api/v3/webhooks HTTP/1.1
Host: app-academy.make.com
authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 53
{
"url": "text",
"secretKey": "text",
"recordType": "text"
}
OK
{
"hookId": "text",
"secretKey": "text"
}
Detach a webhook
Detaches an existing webhook.
ID of the record to work with.
Access token for authorization.
DELETE /api/v3/webhooks/{id} HTTP/1.1
Host: app-academy.make.com
authorization: text
Accept: */*
OK
No content
Last updated