Requests and Responses (LP Classic)

This documentation is for LiquidPlanner Classic:

General RESTful API Resources and Methods

For background on RESTful APIs in general, see Wikipedia or another suitable reference.

HTTP Methods

If you want toThen you should
fetch all instances of a resourceGET /api/v1/resource
fetch a single instance of the resourceGET /api/v1/resource/:id
create a new resourcePOST /api/v1/resource
update an existing resourcePUT /api/v1/resource/:id
delete an existing resourceDELETE /api/v1/resource/:id

If your HTTP client does not implement the PUT and DELETE methods, then you can use a POST with an additional parameter named _method and a value of either PUT or DELETE.

For example, to delete a task using the POST method rather than the DELETE method, do:

% curl -X POST

HTTP Status Codes

Check the HTTP status code of responses from the API to determine whether your request was processed successfully.

Success Codes

Status CodeResult
200 OKsuccessful read, update, or delete
201 Createdsuccessful create

Error or Exception Codes

Status CodeResult
400 Bad Requestunrecognized or invalid request URL
401 Unauthorizedcredentials not provided or are incorrect
422 Unprocessable Entityunsuccessful create, update, or delete; syntactic or validation error
404 Not Foundrecord does not exist, or you do not have permission to access it
500 Internal Server Errorunexpected error; you've likely found a bug in LiquidPlanner
501 Not Implementedyou asked for an API version that is not implemented (either because it does not exist, or it has been deprecated)
503 Service UnavailableAPI is disabled globally, or your account is throttled; check the error in the response body

Error Responses

Response Body

When returning an error, the response body contains details of the error represented as a JSON hash.

For example, requesting an invalid task id results in the following error response:

% curl
  "type": "Error",
  "error": "NotFound",
  "message": "Record not found (or you don't have permission to access it)."
 Status: 404 Not Found

Hash Keys of an Error Response

typethe literal string "Error"
errorspecific kind of error, e.g. "NotFound" or "BadRequest"
messagedescriptive or explanatory message

Writing via the API

Many, but not all, resources can be created or modified via the API. As a general rule, things that you can create or edit inside the “Projects” tab in the Web UI (tasks, projects, documents, comments, etc.) are also writable via the API.

On the other hand, administrative resources (members, workspace settings, activities, etc.) are in general not writable via the API.

When creating or modifying a resource, the payload should always be a JSON hash with a single root attribute: the lower-case name of the resource you are writing (except when dealing with the convenience methods, specified below). The value of that attribute should be a hash of all the attributes you’d like to write.

Create an item using POST, and update an item using PUT.

Resource Parameter

When creating or updating a resource, the API requires a request parameter with the same name as the resource (in the singular form), whose value is a hash of the resource’s attributes.

Putting together the HTTP methods, resource nesting, and the resource parameter, we have the following:

If you want toThen you shouldToWith a parameter
Create a TaskPOST/api/v1/workspaces/:workspace_id/taskstask = ...hash
Create a Comment on a TaskPOST/api/v1/workspaces/:workspace_id/tasks/:task_id/commentscomment = ...hash
Update a FolderPUT/api/v1/workspaces/:workspace_id/folders/:folder_idfolder = ...hash

You can reference the available resources at: