Introduction

Listings API

Overview

Org-scoped sellable catalogue. Required on create: catalog_id, title, price, details (schema from catalog type). Public reads use CATALOG_ORG_ID; writes require Directory JWT with the listing service.

Integration guide: Listings service docs

OpenAPI v0.2.0 · source openapi/listings.json

OpenAPI 3.0.0 · v0.2.0 · 16 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/health"

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/v1/health"

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Catalog

Catalog type definitions (built-in and custom) that listings reference via catalog_id.

get/v1/catalog-types

List catalog types

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/v1/catalog-types"

Org-defined catalog types for this organisation. Create types with POST before listing create.

Operation ID: listCatalogTypes

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—

Responses

200
Catalog types
application/json

post/v1/catalog-types

Create catalog type

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/listings/v1/catalog-types"

Defines a new catalog type (server-assigned UUID) and field schema for listing `details`. Label must be unique per org (case-insensitive).

Operation ID: createCatalogType

Request body(required)

application/jsonCatalogTypeCreate

Responses

201
Catalog type created
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — idempotency conflict or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

get/v1/catalog-types/{id}

Get catalog type

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/v1/catalog-types/example-id"

Operation ID: getCatalogType

Parameters

Name	In	Type	Description
id*	path	string (uuid)	UUID of a catalog type from `GET /v1/catalog-types` (create with POST first).

Responses

200
Catalog type
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

patch/v1/catalog-types/{id}

Update catalog type

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/listings/v1/catalog-types/example-id"

Updates label or fields.

Operation ID: updateCatalogType

Parameters

Name	In	Type	Description
id*	path	string (uuid)	UUID of a catalog type from `GET /v1/catalog-types` (create with POST first).

Request body(required)

application/jsonCatalogTypePatch

Responses

200
Catalog type updated
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — idempotency conflict or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

delete/v1/catalog-types/{id}

Delete catalog type

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/v1/catalog-types/example-id"

Deletes a catalog type when no listings reference it.

Operation ID: deleteCatalogType

Parameters

Name	In	Type	Description
id*	path	string (uuid)	UUID of a catalog type from `GET /v1/catalog-types` (create with POST first).

Responses

200
Deleted
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — idempotency conflict or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

Listings

Sale and hire catalogue.

get/v1/listings

List listings

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/v1/listings"

Operation ID: listListings

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—
q	query	string	—
catalog_id	query	string (uuid)	—
catalog_type	query	string (uuid)	Use `catalog_id`.
status	query	string	—
for_sale	query	boolean	—
for_hire	query	boolean	—

Responses

200
Listings
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/listings

Create listing

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/listings/v1/listings"

Operation ID: createListing

Request body(required)

application/jsonListingCreate

Responses

201
Listing created
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — idempotency conflict or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

get/v1/listings/by-slug/{slug}

Get listing by slug

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/v1/listings/by-slug/example-id"

Operation ID: getListingBySlug

Parameters

Name	In	Type	Description
slug*	path	string	—

Responses

200
Listing
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

get/v1/listings/{id}

Get listing

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/v1/listings/example-id"

Operation ID: getListing

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Listing
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

patch/v1/listings/{id}

Update listing

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/listings/v1/listings/example-id"

Operation ID: updateListing

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonListingPatch

Responses

200
Listing updated
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — idempotency conflict or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

patch/v1/listings/{id}/status

Update listing status

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/listings/v1/listings/example-id/status"

Sets draft, published, sold, or withdrawn. Use this instead of PATCH /v1/listings/{id} for status changes.

Operation ID: updateListingStatus

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonListingStatusUpdate

Responses

200
Listing status updated
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — idempotency conflict or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/listings/{id}/photos

Add listing photo

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/listings/v1/listings/example-id/photos"

Operation ID: addListingPhoto

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonListingPhotoCreate

Responses

201
Photo added
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — idempotency conflict or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

delete/v1/listings/{id}/photos/{photoId}

Remove listing photo

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/v1/listings/example-id/photos/example-id"

Operation ID: deleteListingPhoto

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—
photoId*	path	string (uuid)	—

Responses

200
Photo removed
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — idempotency conflict or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

Audit

Immutable change log for this service.

get/v1/audit

Audit trail

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/listings/v1/audit"

Operation ID: listAudit

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—

Responses

200
Audit events
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json