Listing Intelligence

POST https://kovca.io/api/v1/listings/check

Authenticate with your API key in the Authorization: Bearer header. Send JSON with Content-Type: application/json; bodies are limited to 16 KB.

The API checks one listing against the requirements, marketplace policy, and product facts you send. It never rewrites the listing, invents specifications, or publishes anything. A listing is never declared compliant with a policy you didn't send.

Request body

{
  "listing": {
    "title": "Acme TrailRunner Wireless Earbuds, Black",
    "description": "Lightweight wireless earbuds with active noise cancellation and up to 8 hours of playback per charge. The best earbuds ever made, guaranteed to never fail.",
    "category": "Headphones",
    "attributes": {
      "color": "Black",
      "battery_life": "8 hours",
      "connectivity": "Bluetooth 5.3"
    }
  },
  "requirements": {
    "required_attributes": [
      "color",
      "connectivity",
      "warranty"
    ],
    "title_max_length": 80
  },
  "facts": {
    "battery_life": "8 hours",
    "connectivity": "Bluetooth 5.3"
  }
}

Response

{
  "request_id": "req_Vk2pT9rQw4NbL8yH",
  "status": "improvements_needed",
  "recommended_action": "revise",
  "issues": [
    {
      "type": "missing_information",
      "method": "deterministic",
      "field": "listing.attributes.warranty",
      "explanation": "A required attribute is missing.",
      "evidence": [
        "requirements.required_attributes"
      ]
    },
    {
      "type": "unsupported_claim",
      "method": "model_assisted",
      "field": "listing.description",
      "explanation": "The description makes a claim that the supplied facts and attributes don't support.",
      "evidence": [
        "listing.description"
      ]
    }
  ],
  "missing_attributes": [
    "warranty"
  ],
  "suggested_improvements": [
    "Add the warranty attribute.",
    "Remove claims you can't support, or supply the facts that support them."
  ]
}

How a listing is checked

1. In code: required attributes, allowed categories, title and description lengths, prohibited terms (whole words), identifier check digits, all-caps titles, and attributes that differ from facts (units are normalized, so 750ml equals 750 ml).
2. Interpreted: whether the title and description describe the same product, whether the text contradicts the attributes or facts, whether claims are unsupported, whether the category fits (skipped when you send allowed_categories), and each rule in your policy.

Interpreted findings are issues only when the answer is clear; less certain findings are listed for review without suggestions. A listing with a description under 30 characters and no attributes isn't evaluated.

Statuses (first match wins)

• insufficient_information: Too little content to evaluate. Action: request_information.
• improvements_needed: At least one confirmed issue. Action: revise.
• requires_review: Only uncertain findings. Action: manual_review.
• ready: No issues found against what you supplied. Action: publish.

Issue types

• missing_information: A required attribute or category is missing, or the description is shorter than your minimum.
• contradictory_attributes: An attribute differs from a supplied fact, or the title or description contradicts the attributes or facts.
• title_description_mismatch: The title and description describe different products.
• unsupported_claim: The description makes an exaggerated, absolute, or guaranteed-outcome claim that the supplied facts and attributes don't support.
• category_mismatch: The category isn't in your allowed list, or doesn't fit the product.
• policy_issue: The text contains a prohibited term, or breaks (or may break) a rule in your marketplace policy. Rules are quoted exactly.
• formatting_issue: The title is too long or mostly capital letters, or a GTIN, UPC, or EAN has a wrong check digit.

With a marketplace policy

{
  "listing": {
    "title": "Vintage-style leather messenger bag",
    "description": "Handmade messenger bag in brown leather with a padded laptop sleeve. Contact me at seller@example.com for a discount.",
    "category": "Bags",
    "attributes": {
      "material": "Leather",
      "color": "Brown"
    }
  },
  "policy": {
    "text": "Listings must not include email addresses, phone numbers, or links to other websites. Listings must state the item's material."
  }
}

Code

curl https://kovca.io/api/v1/listings/check \
  -H "Authorization: Bearer $KOVCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "listing": {
    "title": "Acme TrailRunner Wireless Earbuds, Black",
    "description": "Lightweight wireless earbuds with active noise cancellation and up to 8 hours of playback per charge. The best earbuds ever made, guaranteed to never fail.",
    "category": "Headphones",
    "attributes": {
      "color": "Black",
      "battery_life": "8 hours",
      "connectivity": "Bluetooth 5.3"
    }
  },
  "requirements": {
    "required_attributes": [
      "color",
      "connectivity",
      "warranty"
    ],
    "title_max_length": 80
  },
  "facts": {
    "battery_life": "8 hours",
    "connectivity": "Bluetooth 5.3"
  }
}'

Errors

• 400 INVALID_REQUEST: a field is missing, too long, the wrong type, or not allowed. The message names the field.
• 413 PAYLOAD_TOO_LARGE: the body is larger than 16 KB.
• 401 UNAUTHORIZED, 429 RATE_LIMITED, 503 SERVICE_UNAVAILABLE, 504 TIMEOUT: see Errors and limits.

Limitations

• Completeness depends on your required_attributes. The API doesn't assume which attributes a product type needs.
• Claims are judged against the facts you supply, not external sources.
• A ready result means no issues were found against what you supplied, not compliance with every marketplace's rules.
• Request data is processed to produce the result and is not stored by Kovca.