Machine Box APIs

Machine Box APIs are standard RESTful JSON/HTTP endpoints, making them very easy for developers of all levels.

/info endpoint

Box info screenshot

All boxes provide the /info endpoint which returns some basic details about the box:

GET /info
{
	"success": true,
	"name":    "tagbox",
	"version": 1,
	"build":   "27d1d38",
	"status":  "ready"
}
  • success - (boolean) Whether the /info request was successful or not
  • name - (string) The name of the box
  • version - (number) The version of the box
  • build - (string) The code that describes the exact build of the box (useful when reporting issues)
  • status - (string) The status of the box

Box status

Valid box status values include:

  • starting... - The box is starting up and will be ready shortly
  • ready - The box is ready to receive API calls (wait for this before making requests)
  • shutting down - The box is shutting down and will be unavailable soon

Once a box has shut down, the /info endpoint stops working, at this point the Interactive consoles will show unavailable.

success and error handling

All Machine Box APIs return a single JSON object that have a success field, and may have an error field, allowing you to write failure logic once, and reuse it.

For a successful response, you will get:

{
	"success": true,
	// some other data
}

If something goes wrong, success will be false and the error field will be provided explaining what happened:

{
	"success": false,
	"error": "url must be absolute"
}

Submitting files

If a box endpoint requires a file, you have two main ways of submitting one:

  • POST the file directly (like uploading from an HTML form)
  • Submit an absolute URL to a file, which will be downloaded and processed

The Interactive console for each box provides more details on how to do this in each case.