API Reference

Deploy and execute your functions via a standardized RESTful interface.

Execution Endpoint

POST https://api.matesst.com/api/v2/:functionName

Replace :functionName with the name of the function you wish to execute.

Headers

Header	Value	Description
Authorization	Bearer ${API_SECRET}	Your application secret key
Content-Type	application/json	Required for JSON body

Request Body

The request body must be a JSON object with the following fields:

Field	Type	Required	Description
params	Array	Yes	List of input arguments for the function.
nargout	Number	Yes	Number of return values expected from the function.
instanceId	String	No	ID of the algorithm machine to use.

Understanding instanceId

• Load Balancing: If instanceId is omitted, Matesst will use a machine from the shared pool (IDs starting with instance-) using a complex load balancing algorithm.
• Dedicated Instance: You can specify a custom string as instanceId. If this ID doesn't exist, Matesst will automatically spawn a temporary dedicated machine that operates independently of the shared load balancing pool. This ensures your processes are protected from preemption or resource contention by other requests, especially in high-concurrency scenarios.
• Performance Optimization: Reusing the same instanceId for subsequent requests avoids cold start times, as the machine stays "warm" for that specific ID.

Example Request

{
  "params": [1, 2],
  "nargout": 1,
  "instanceId": "instance-0"
}

---

Response Structure

Matesst returns a JSON object containing the execution results.

Field	Type	Description
results	any	The return values from your function.
status	String	Status of the request (e.g., "success", "error").

Result Wrapping Rules

• Single Number with nargout = 1: If the function returns a single number and nargout is set to 1, it is returned directly in the results field.
• Otherwise: The results are always wrapped in a nested array structure. The outer array length corresponds to nargout.
  • Example: If nargout = 1 and the function returns an array [1, 2, 3], the results field will be [[1, 2, 3]].

Example: Single Number

{
  "results": 7,
  "status": "success"
}

Example: Complex Data (unique function)

When calling functions that return multiple vectors (like unique), each output is wrapped according to its dimensions. Note the difference between the row vector (first result) and column vectors (second and third results).

Request:

{
  "params": [[9, 2, 2, 9, 5]],
  "nargout": 3
}

Response:

{
  "results": [
    [[2, 5, 9]], // Output 1: Unique values (Row vector)
    [[2], [5], [1]], // Output 2: Indices ia (Column vector)
    [[3], [1], [1], [3], [2]] // Output 3: Reverse indices ic (Column vector)
  ],
  "status": "success"
}

---

Error Handling

If the execution fails, Matesst returns a non-200 status code with a JSON body describing the error.

Field	Type	Description
error	String	A brief summary of the error type.
message	String	Detailed error information, often including the stack trace.

Example Error Response

{
  "error": "Execution Error",
  "message": "Too many input arguments.\n"
}