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).