Responses

The API responds to successful requests with HTTP status codes in the 200 range.

When you create a resource, the API will respond with a 201 Created status code and will include a Location header pointing to the created resource. The created resource will also be included in the response body.

When you update a resource, the API will include the updated resource in the response body.

When you delete a resource, the API will respond with a 204 No Content status code and the response body will be empty.

HTTP status codes

200 OK	The request completed successfully.
201 Created	A resource was successfully created.
204 No Content	The request completed successfully, no content is included in the response.
304 Not Modified	A resource was requested with an If-None-Match or If-Modified-Since header. The resource has not changed since it was last requested, so no content is included in the response.
400 Bad Request	The request was unsuccessful due to incorrect input.
401 Unauthorized	The request was disallowed (usually due to missing authentication credentials).
403 Forbidden	The request was disallowed (usually due to incorrect authentication credentials).
404 Not Found	The requested item was not found.
413 Request Entity Too Large	An item couldn't be created or updated due to the data being too large. See Limitations for maximum item data sizes.
415 Unsupported Media Type	The request media type was not set to application/json.
429 Too Many Requests	The rate limit has been reached. See Rate limiting for further information.
500+ Server Error	Something has gone wrong on jsonpad's servers.

Individual resources

When fetching an individual resource, or when updating or creating a resource, the resource will be returned wrapped in a JSON object containing a property named after the type of resource.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist/items/23928779684449152 \
	-u username:token \
	-H "Accept: application/json"

Example response
{
	"item": {
		"created": "2015-03-14T23:08:15+00:00",
		"data": {
			// Item data...
		},
		"id": "23928779684449152",
		"updated": "2015-03-14T23:08:15+00:00"
	}
}

The exception to this rule is when selecting an item's data using the /data endpoint, in which case only the item's data will be returned.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist/items/23928779684449152/data \
	-u username:token \
	-H "Accept: application/json"

Example response
{
	// Item data...
}

Lists of resources

When fetching lists of resources, the resources will be returned wrapped in a JSON object as an array, alongside properties describing the response.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist/items \
	-u username:token \
	-H "Accept: application/json"

Example response
{
	"descending": false,
	"items": [
		{
			"created": "2015-03-14T23:08:15+00:00",
			"data": {
				// Item data...
			},
			"id": "23928779684449152",
			"updated": "2015-03-14T23:08:15+00:00"
		},
		// Items continued...
	],
	"page": 1,
	"page_size": 50,
	"pages": 2,
	"sort": "index",
	"total": 100
}

descending	true if the results are in descending order, false if the results are in ascending order.
items	An array of items (this property will only be present in requests that return items).
lists	An array of lists (this property will only be present in requests that return lists).
events	An array of events (this property will only be present in requests that return events).
page	The current page number. See Pagination for further information.
page_size	The number of resources per page.
pages	The total number of pages.
sort	The current sort mode. See Sorting for further information.
total	The total number of resources.

In the case of items, an array containing just each item's data can be returned by using the /data endpoint.

Example request
$ curl https://jsonpad.io/api/v1.0/lists/testlist/items/data \
	-u username:token \
	-H "Accept: application/json"

Example response
[
	{
		// Item data...
	},
	// Items continued...
]

Empty fields

When a field is empty it will be set to null rather than being omitted. Array fields will be set to [] (an empty array).