Resources API Request and Response

Authentication

The Resources API requires authentication for all requests. For detailed information about authentication methods and requirements, please see the Authentication section of the API documentation.

Required Headers

All requests to the Resources API must include the following headers:

Header	Description	Required	Example
X-Spaaza-Chain-ID	Numeric Chain ID for the request	Yes	1743
X-Spaaza-API-version	API version (minimum 1.6.1)	Yes	1.6.1
X-Spaaza-Session-User-ID	User ID for authentication	Yes	{your user ID}
X-Spaaza-Session-Key	Session key for authentication	Yes	{your key}
X-Spaaza-Response-Recursion-Level	Response detail level (0-4, default 3)	Optional	3
Content-Type	Content type for POST/PATCH/PUT requests	For POST/PATCH	application/json

Responses

Resources API endpoints return payloads in JSON format as follows:

• Single Resource Retrieval: Returns a JSON object representing the resource in accordance with the OpenAPI specification of the resource.
• Multiple Resource Retrieval: Returns a JSON object containing an array of resources along with pagination metadata.

For more detailed information about API response formats, status codes, and data structures, please see the Responses section of the API documentation.

Response Recursion Levels

The Resources API supports configurable response detail levels through the X-Spaaza-Response-Recursion-Level header. This controls how much detail is included in API responses, particularly for nested objects and relationships.

Recursion Level Values

• Level 0: Minimal response with only basic identifiers
• Level 1: Basic properties without nested objects
• Level 2: Includes some nested object properties
• Level 3: Default level with comprehensive property details
• Level 4: Maximum detail including all available properties

Usage

Include the X-Spaaza-Response-Recursion-Level header in your requests to specify the desired detail level:

curl -X GET https://{API hostname}/resources/{resource name}/{id} \
  -H "X-Spaaza-Response-Recursion-Level: 2" \
  # ... other headers

Note that, in the case of nested resources, the recursion level applies recursively to related resources as well and the remaining recursion level value is "carried" down the object tree. For example, if you request recursion level 3 for a resource, Resource 1, and a nested resource in Resource 1 has a recursion level of 2, then that nested resource will be returned with recursion level of (3 - 2 = 1).

If not specified, the default recursion level of 3 is used.

Versioning

For information about API versioning and version compatibility, please see the Versioning section of the API documentation.

Possible Error Responses

The following error codes are specific to or commonly returned by the Resources API. Errors are listed in ascending order by code number.

Resources API-specific errors

These errors are unique to the Resources API:

Code	Name	HTTP Status	Description
533	missing_parameter	400	A required parameter or header is missing (for example a missing X-Spaaza-Chain-ID header).
534	invalid_parameter	400	A parameter is invalid, such as an incorrect Content-Type, an invalid JSON body, or an unrecognised filter.
539	unknown_resource_type	400	The resource type in the URL path is not recognised.
540	resource_type_not_properly_configured	400	The requested resource type is not properly configured on the server.
541	resource_already_exists	400	A POST request attempted to create a resource that already exists (matched by identifier).
542	schema_error	400	An error occurred while generating or processing the OpenAPI schema.
543	parameter_validation_error	400	One or more parameters failed validation against the OpenAPI schema, or pagination/sort values are out of range.
544	resource_not_found	404	The requested resource was not found, or the authenticated user does not have permission to access it.
545	invalid_endpoint	400	The endpoint path or method is invalid (for example, the API version is below 1.6.1 or the HTTP method is not supported for this path).

General errors applicable to the Resources API

These errors are shared across the Spaaza API and may also be returned by the Resources API:

Code	Name	HTTP Status	Description
6	no_valid_session	401	Authentication is missing or the session is not valid.
68	permission_denied_or_non_existent	403	The authenticated user does not have sufficient permissions for the requested chain or resource.
408	saving_object_error	400	An error occurred while saving the resource. The request may contain data that cannot be persisted.
419	parameter_invalid	400	A parameter value is in an incorrect format (for example, text search or geospatial parameters).
424	access_denied	403	Access to the requested chain or resource is denied for this user.
462	parameter_mismatch	400	Identifier parameters in a PATCH or PUT request resolve to a different resource than the one being updated.

For a complete list of all error codes across the Spaaza API, please see the Error and Warning Codes page.