api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "listings": {
          "description": "Listings returned for this page.",
          "items": {
            "description": "A marketplace listing in search results.",
            "properties": {
              "categoryId": {
                "description": "Marketplace category identifier when available.",
                "nullable": true,
                "type": "string"
              },
              "deliveryTypes": {
                "description": "Delivery options reported for the listing.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "id": {
                "description": "Stable marketplace listing identifier.",
                "minLength": 1,
                "type": "string"
              },
              "location": {
                "description": "Location summary for the listing.",
                "properties": {
                  "city": {
                    "description": "City name when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "cityPageId": {
                    "description": "Location page identifier when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "displayName": {
                    "description": "Human-readable location label when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "state": {
                    "description": "State or region when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "city",
                  "state",
                  "displayName",
                  "cityPageId"
                ],
                "type": "object"
              },
              "price": {
                "description": "Displayed price for the listing.",
                "properties": {
                  "amount": {
                    "description": "Numeric price amount when available.",
                    "nullable": true,
                    "type": "number"
                  },
                  "amountWithOffsetInCurrency": {
                    "description": "Price amount with currency offset when available.",
                    "nullable": true,
                    "type": "number"
                  },
                  "formattedAmount": {
                    "description": "Formatted price label when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "formattedAmount",
                  "amount",
                  "amountWithOffsetInCurrency"
                ],
                "type": "object"
              },
              "primaryPhoto": {
                "description": "Primary photo for the listing.",
                "properties": {
                  "id": {
                    "description": "Primary photo identifier when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "url": {
                    "description": "Primary photo URL when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "url"
                ],
                "type": "object"
              },
              "status": {
                "description": "Listing status flags.",
                "properties": {
                  "isHidden": {
                    "description": "Whether the listing is hidden when available.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "isLive": {
                    "description": "Whether the listing is live when available.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "isPending": {
                    "description": "Whether the listing is pending when available.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "isSold": {
                    "description": "Whether the listing is sold when available.",
                    "nullable": true,
                    "type": "boolean"
                  },
                  "isViewerSeller": {
                    "description": "Whether the viewer is the seller when available.",
                    "nullable": true,
                    "type": "boolean"
                  }
                },
                "required": [
                  "isHidden",
                  "isLive",
                  "isPending",
                  "isSold",
                  "isViewerSeller"
                ],
                "type": "object"
              },
              "storyKey": {
                "description": "Story key metadata when available.",
                "nullable": true,
                "type": "string"
              },
              "storyType": {
                "description": "Story type metadata when available.",
                "nullable": true,
                "type": "string"
              },
              "strikethroughPrice": {
                "description": "Strikethrough or original price when available.",
                "nullable": true,
                "properties": {
                  "amount": {
                    "description": "Numeric price amount when available.",
                    "nullable": true,
                    "type": "number"
                  },
                  "amountWithOffsetInCurrency": {
                    "description": "Price amount with currency offset when available.",
                    "nullable": true,
                    "type": "number"
                  },
                  "formattedAmount": {
                    "description": "Formatted price label when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "formattedAmount",
                  "amount",
                  "amountWithOffsetInCurrency"
                ],
                "type": "object"
              },
              "title": {
                "description": "Listing title.",
                "minLength": 1,
                "type": "string"
              },
              "url": {
                "description": "Canonical public listing URL when available.",
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "id",
              "url",
              "title",
              "price",
              "strikethroughPrice",
              "location",
              "primaryPhoto",
              "categoryId",
              "deliveryTypes",
              "status",
              "storyType",
              "storyKey"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "location": {
          "description": "Location parameters evaluated for this response.",
          "properties": {
            "lat": {
              "description": "Latitude evaluated for this search.",
              "type": "number"
            },
            "lng": {
              "description": "Longitude evaluated for this search.",
              "type": "number"
            },
            "radiusKm": {
              "description": "Search radius in kilometers when provided.",
              "nullable": true,
              "type": "number"
            }
          },
          "required": [
            "lat",
            "lng",
            "radiusKm"
          ],
          "type": "object"
        },
        "page": {
          "description": "Pagination information for the current response.",
          "properties": {
            "hasMore": {
              "description": "Whether another page of listings can be requested.",
              "type": "boolean"
            },
            "nextCursor": {
              "description": "Cursor to pass in the next request when another page is available; otherwise null.",
              "nullable": true,
              "type": "string"
            }
          },
          "required": [
            "nextCursor",
            "hasMore"
          ],
          "type": "object"
        },
        "query": {
          "description": "Search query string evaluated for this response.",
          "type": "string"
        },
        "totalListings": {
          "description": "Number of listings returned in this response.",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "query",
        "location",
        "listings",
        "totalListings",
        "page"
      ],
      "type": "object"
    },
    "meta": {
      "description": "Metadata describing the request and billing outcome.",
      "properties": {
        "cached": {
          "description": "True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.",
          "type": "boolean"
        },
        "creditsCharged": {
          "description": "Credits charged for this request.",
          "minimum": 0,
          "type": "integer"
        },
        "requestId": {
          "description": "Unique request identifier for tracing this API call.",
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Public API version that served the response.",
          "enum": [
            "v1"
          ],
          "type": "string"
        }
      },
      "required": [
        "requestId",
        "creditsCharged",
        "version"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "type": "object"
}