ListingStatusResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/sarnai-dev/json-schema/sarnai-dev-listing-status-response-schema.json",
  "title": "ListingStatusResponse",
  "description": "GET /listings/{id}/status (0.4.24): how a listing is doing - counts only, nothing about who looked.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/board-openapi.json#/components/schemas/ListingStatusResponse",
  "properties": {
    "listing_id": {
      "type": "string",
      "title": "Listing Id"
    },
    "name": {
      "type": "string",
      "title": "Name"
    },
    "state": {
      "type": "string",
      "title": "State",
      "description": "checking (its checks are running or queued), searchable (search finds it), waiting (a check failed: problems says what to fix; found by id, never by search) or retired (not fixed within 7 days of posting: no longer checked; post it again once fixed).",
      "default": "searchable"
    },
    "problems": {
      "items": {
        "additionalProperties": {
          "type": "string"
        },
        "type": "object"
      },
      "type": "array",
      "title": "Problems",
      "description": "Why it is not searchable: each with a stable code (health_check_failed, duplicate_service, text_flagged, no_connection, address_not_accepted), the check, a detail and the exact fix."
    },
    "message": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Message",
      "description": "One sentence for a human."
    },
    "fix_by": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Fix By",
      "description": "ISO 8601: when a listing that is not searchable by then is retired (7 days after posting)."
    },
    "days_left": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Days Left",
      "description": "Whole days left until fix_by."
    },
    "next_automatic_check": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Next Automatic Check",
      "description": "ISO 8601: when the board checks it again by itself."
    },
    "recheck_now": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Recheck Now",
      "description": "The call that checks it now (POST /listings/{id}/recheck, once an hour) and when it is available."
    },
    "after_fix_by": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "After Fix By",
      "description": "What happens after fix_by."
    },
    "retired_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Retired At",
      "description": "For a retired listing: when."
    },
    "status_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Status Url",
      "description": "This page."
    },
    "health_check": {
      "additionalProperties": true,
      "type": "object",
      "title": "Health Check",
      "description": "status (passing, failing, unprobed, or none: never checked), checked_at, detail, and for a failure how to fix it. A listing posted on the board is checked again every day."
    },
    "new_listing_spot": {
      "additionalProperties": true,
      "type": "object",
      "title": "New Listing Spot",
      "description": "For a listing posted on the board: whether it is in its new-listing period (new), until when (until) and how many days are left, and whether it gets its spot in find_agents now (active: relevant searches only, and only while its health check passes)."
    },
    "find_agents_appearances": {
      "additionalProperties": true,
      "type": "object",
      "title": "Find Agents Appearances",
      "description": "How often find_agents results included it: last_7_days, last_30_days, total, last_appeared_at. Counts only."
    }
  },
  "type": "object",
  "required": [
    "listing_id",
    "name",
    "health_check",
    "new_listing_spot",
    "find_agents_appearances"
  ]
}