1. Home
  2. Docs
  3. REST API

REST API

The Mind-Trace REST API allows you to interact with the Mind-Trace platform using standard HTTP requests. Almost everything that can be done using our online portal is available for use through this API.

The API uses well established patterns in REST API design. This means that we use standard HTTP verbs, status codes, encode requests and responses as JSON and use standard HTTP headers.

All requests should be made to the https://api.mind-trace.com/ endpoint for production applications. Resource paths such as /v1/experiments must include the version number and must be nouns and plural. Nesting of resources is only used sporadically, instead filter should be used to request child resources.

Please refer to our API specification on SwaggerHub for an overview of supported resources.

The content-type of requests and response is application/json unless otherwise specified.

Verbs

The following HTTP verbs are used within the Mind-Trace API:

  • GET: Return a single resource or a list of resources.
  • POST: Create a new resource.
  • PUT: Update an entire resource.
  • PATCH: Update fields of a resource.
  • DELETE: Remove a resource.

Not all verbs are supported on every endpoint.

Status codes

The following status codes are returned in case of success:

  • GET: 200 OK.
  • POST: 201 Created (or 202 Accepted in case of delayed execution)
  • PUT: 200 OK.
  • PATCH: 200 OK.
  • DELETE 204 No Content.

Status codes returned in case of failure:

  • 400 Bad request: Bad input parameter.
  • 401 Unauthorized: No, or invalid, credentials have been provided.
  • 403 Forbidden: The user does not have permission to perform this operation.
  • 404 Not found: Resource does not exist.
  • 405: Method not allowed: Resource does not support the specified verb.
  • 429: Too many requests: Rate limiting issue
  • 500: Internal Server Error: The request is valid, but the server is experiencing trouble.
  • 503: Service unavailable: The service is currently disabled.

Furthermore, in case of an error the API will return the following JSON response:

{
    "message": "Description of the problem in English."
}

Rate limiting

Certain resources within the Mind-Trace platform may be protected using rate limiters. This means that only a fixed number of requests can be made during a time window. Status code 429 will be returned for any requests that were denied because of rate limiting.

The following HTTP headers will be communicated in case rate limiting is in force:

  • RateLimit-Limit: The maximum number of requests that can be made in the currently active time window.
  • RateLimit-Remaining: The number of requests that can still be made in the currently active time window.
  • RateLimit-Reset: The number of seconds remaining until the quota resets.

Articles