Skip to content

API Documentation

The BinStack API is extremely simple to use. Requests can be sent via GET or POST, and responses are sent in JSON. POST requests are strongly recommended over GET for security reasons (i.e. GET request data, including API keys and plaintext passwords, is saved in server logs and browser history with little to no protection). You should only use GET requests for debugging purposes or if (for some awful reason) it is not possible to use POST for your use case.

Request Structure

The API is typically located at http(s)://binstack-url/api.php.

All requests to the API must include a username and password argument corresponding to a valid user account. They must also include an action. The action specifies the type of request. Other arguments may or may not be needed, depending on the action specified. See the table below for valid actions and parameters.

Response Structure

Responses to well-formed requests will have a status field containing the string OK or ERROR.
If status is ERROR, there will also be a field named msg containing a human-readable localized error message suitable for display to the user.
If status is OK, there may or may not be additional fields sent, depending on the action.

If the request is not well-formed (missing required arguments, invalid API key, or invalid action), the API will send a 4xx HTTP code and a JSON string, such as "400 Bad Request", "403 Unauthorized", or "404 Not Found: the requested action is not available.".


Action Additional Arguments Description
ping None Used to check if the server is online and responding. Responds with {"status":"OK"}.