List the listings in your API scope (cursor-paginated).

GET

/v1/listings

Returns a cursor-paginated page of the listings the authenticated key may read (owner or writer access). Ordered by an immutable (created_at, id) tuple. Pass nextCursor back as cursor to page forward. Page size defaults to 50 and is clamped to [1, 100].

Authorizations

• bearerAuth

Parameters

Query Parameters

limit

integer format: int32

default: 50 >= 1 <= 100

Page size. Defaults to 50; values are clamped to the range [1, 100].

cursor

string

An opaque pagination token from a prior page’s nextCursor. Treat as a black box.

Responses

200

A page of listings.

A cursor-paginated page of listings.

object

items

required

Array<object>

The public projection of a listing. A curated, additive-only subset of internal fields.

object

id

required

The listing’s unique id.

string format: uuid

publicId

required

The listing’s public slug.

string

title

required

string

address

required

string

city

required

string

country

required

string

zipCode

required

string

district

string

nullable

timezone

required

IANA timezone identifier.

string

active

required

boolean

maxPeopleInListing

integer format: int32

nullable

maxVehicles

integer format: int32

nullable

allowPets

boolean

nullable

createdAt

required

When the listing was created (ISO-8601, UTC). The cursor ordering key.

string format: date-time

nextCursor

Opaque token for the next page, or null on the last page.

string

nullable

400

The request was malformed — an invalid cursor (INVALID_CURSOR) or a failed parameter validation (VALIDATION_ERROR, with field-level errors[]).

The single error envelope for every public-surface error response.

object

code

required

A stable, enumerated error code. Branch on this, never on message.

string

Allowed values: UNAUTHENTICATED FORBIDDEN RESOURCE_NOT_FOUND INVALID_CURSOR VALIDATION_ERROR PAYLOAD_TOO_LARGE RATE_LIMITED IDEMPOTENCY_KEY_REUSED

message

required

A human-readable description. May change without a contract break.

string

correlationId

required

A per-response id for support correlation.

string format: uuid

errors

Present only for VALIDATION_ERROR — the field-level validation failures.

Array<object>

One field-level validation failure.

object

field

required

The rejected field or query parameter name.

string

issue

required

What was wrong with it.

string

401

The API key is missing, malformed, revoked, or expired (UNAUTHENTICATED).

The single error envelope for every public-surface error response.

object

code

required

A stable, enumerated error code. Branch on this, never on message.

string

Allowed values: UNAUTHENTICATED FORBIDDEN RESOURCE_NOT_FOUND INVALID_CURSOR VALIDATION_ERROR PAYLOAD_TOO_LARGE RATE_LIMITED IDEMPOTENCY_KEY_REUSED

message

required

A human-readable description. May change without a contract break.

string

correlationId

required

A per-response id for support correlation.

string format: uuid

errors

Present only for VALIDATION_ERROR — the field-level validation failures.

Array<object>

One field-level validation failure.

object

field

required

The rejected field or query parameter name.

string

issue

required

What was wrong with it.

string

429

The per-key rate limit was exceeded (RATE_LIMITED). Retry after the interval in Retry-After.

The single error envelope for every public-surface error response.

object

code

required

A stable, enumerated error code. Branch on this, never on message.

string

Allowed values: UNAUTHENTICATED FORBIDDEN RESOURCE_NOT_FOUND INVALID_CURSOR VALIDATION_ERROR PAYLOAD_TOO_LARGE RATE_LIMITED IDEMPOTENCY_KEY_REUSED

message

required

A human-readable description. May change without a contract break.

string

correlationId

required

A per-response id for support correlation.

string format: uuid

errors

Present only for VALIDATION_ERROR — the field-level validation failures.

Array<object>

One field-level validation failure.

object

field

required

The rejected field or query parameter name.

string

issue

required

What was wrong with it.

string

Headers

Retry-After

integer format: int32

Integer seconds to wait before retrying (RFC 7231 delta-seconds form, always >= 1).