API Response Formats

The API provides resource data in JSON (.json), XML (.xml) or CSV (.csv) data formats. The API sets the HTTP response code and content type according to the requested format and the success or failure of the query. The default format is JSON when none is indicated in the query. The API sets the HTTP content-disposition header with a filename of query.xml (or .json or .csv). Use the filename= option to specify a different name.

Response Envelope

The API sets five fields at the top level of the response.

success true or false
start_row Set according to the request.
num_rows The number of rows in the current response.
total_rows The number of available rows for paged queries.
msg An array containing the results of the query or an error string


The resources in the msg array contain nested hashes with the associated resources from the include= parameter.


The top level of the XML response document is an XML Response entity with success, id, start_row, num_rows and total_rows attributes. The resources are contained in an XML entity named as the plural of the requested model. The XML entities representing the query results contain nested XML entities with the associated resources from the include= parameter. Underscores in association and field names are replaced by hyphens (-) .


The CSV response format does not contain paging information (numrows, totalrows). The first row of the CSV response will be the column names. It does not contain a byte-order-mark. Use of the CSV format implies the tabular option. By default all columns of the model at the start of the query are displayed. Generally the CSV format does not work with the include= parameter; use criteria= (rma::criteria) and tabular= instead. The csv format cannot be use with queries that end in a service call.