Brief

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/placementapi-com/json-schema/placementapi-com-brief-schema.json",
  "title": "Brief",
  "description": "A plan_links brief. Unknown fields are refused (400 unknown_field), not ignored: a quote built from a partly understood brief would name domains you did not choose.",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/placementapi-com-openapi.json#/components/schemas/Brief",
  "type": "object",
  "required": [
    "links"
  ],
  "additionalProperties": false,
  "properties": {
    "links": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "How many placements to plan."
    },
    "strategy": {
      "type": "string",
      "enum": [
        "cheapest",
        "fastest",
        "safest",
        "recommended"
      ],
      "default": "cheapest",
      "description": "Every strategy honours the same filters, quality gates, footprint cap and budget; cheapest is the default. fastest orders by turnaround, and safest prefers independently measured domains with real search traffic — those three change ordering only. recommended is additive and quality-first: measured-and-passed publishers before unmeasured ones, then the existing placement_score descending, with price (and offer id) only as deterministic ties and budget feasibility. In a deployment whose semantic layer runs in `rank` mode, recommended also reorders placements by a rank-usable judgment within the explicit demand/leader priorities; it omits nothing, and missing, failed or below-threshold evidence falls back to this same deterministic result and the same price. Its retrieval cut is a bounded quality proxy, not an exact global score ranking."
    },
    "budget_credits": {
      "type": "integer",
      "minimum": 1,
      "description": "Ceiling for the whole basket, in credits."
    },
    "placement_type": {
      "type": "string",
      "enum": [
        "guest_post",
        "niche_edit",
        "link_insert",
        "homepage_link",
        "media_placement"
      ]
    },
    "inventory_mode": {
      "$ref": "#/$defs/InventoryMode"
    },
    "dr_min": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "Minimum DR, 0-100. Matches the site's claimed DR, or the vendor's guaranteed minimum on blind inventory. Never the measured verified_dr, which is on a 0-1000 scale."
    },
    "rd_min": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum guaranteed Majestic referring domains. Only blind tiers sold on RD carry this guarantee; the RD and DR scales are never translated into each other."
    },
    "traffic_min": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum monthly traffic: measured where known, else claimed, else the blind guarantee floor."
    },
    "price_max": {
      "type": "integer",
      "minimum": 1,
      "description": "Maximum price per placement, USD minor units (cents)."
    },
    "price_min": {
      "type": "integer",
      "minimum": 1,
      "description": "Price floor, USD minor units. A quality filter, not a budget one: a price far below the going rate for the claimed DR is evidence the DR was bought."
    },
    "verified_only": {
      "type": "boolean",
      "default": false,
      "description": "Only domains measured independently AND passed. Stricter than excluding suspect domains, because it also drops the unmeasured."
    },
    "include_restricted": {
      "type": "boolean",
      "default": false,
      "description": "Gambling, adult and piracy sites are excluded unless topic/accepts names the vertical or this is true."
    },
    "plausibility_min_pct": {
      "type": "number",
      "minimum": 0,
      "maximum": 100,
      "description": "Keep only placements at or above this percentile of their own price band (placement type x inventory mode x claimed-DR decade). The measured form of price_min."
    },
    "supplier": {
      "type": "string",
      "maxLength": 64,
      "description": "Opaque supplier token taken from the prefix of any offer_id. Filters to one source without naming it. Real supplier names are not accepted and match nothing."
    },
    "topic": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Harmonised subject (e.g. finance, travel, health, technology). Repeatable; repeats are OR-ed."
    },
    "accepts": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Restricted vertical the placement must accept (crypto, gambling, cbd, vape, adult, dating, pharma, forex). Repeatable; repeats are AND-ed. An empty accepts array on an offer means UNKNOWN, not 'accepts nothing'."
    },
    "dr_max": {
      "type": "number",
      "minimum": 0,
      "maximum": 100
    },
    "geo": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "languages": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "include_suspect": {
      "type": "boolean",
      "default": false,
      "description": "Suspect domains are excluded unless asked for."
    },
    "prefer_demand": {
      "type": "boolean",
      "default": false,
      "description": "Order eligible placements by observed demand (distinct buyers in twelve months) before price."
    },
    "prefer_leaders": {
      "type": "boolean",
      "default": false,
      "description": "Order eligible placements by leader_links for the brief's topic before price. Give a topic so the right leaders count."
    },
    "exclude_domains_bought_for": {
      "type": "string",
      "maxLength": 2048,
      "description": "A target URL or domain. Domains this account already bought for it are left out (excluded.bought_for_target)."
    },
    "exclude_domains_linking_to": {
      "type": "string",
      "maxLength": 2048,
      "description": "A target URL or domain. Every domain in its backlink profile is left out (excluded.already_linking) and the response carries profile_hint. Fetches the profile if not cached (counts against the daily profile budget)."
    },
    "target_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "The page this plan is for. Remembered per target (campaign memory); the weekly brief and standing orders re-run it."
    },
    "max_per_domain": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "default": 1,
      "description": "Ten links from one site is one relationship."
    }
  },
  "$defs": {
    "InventoryMode": {
      "type": "string",
      "enum": [
        "named",
        "pre_approval",
        "blind"
      ],
      "description": "The most important field. 'named' = a specific, identified domain you can inspect before ordering. 'pre_approval' = the vendor proposes candidate domains and the buyer approves them BEFORE placement. 'blind' = a promise (e.g. DR50+, finance) where the domain is assigned at fulfilment with no veto. Only 'named' carries a site_id. Never present a pre_approval or blind offer as though a specific site were secured, and never price-compare a specification against a named domain as the same product."
    }
  }
}