{"openapi":"3.1.0","info":{"title":"Link Building API","version":"1.0.0","description":"A link marketplace with an API-first buying flow. Discover publisher inventory with verified third-party metrics, place structured link orders, and poll their status. Keys are created at https://linkbuildingapi.com/settings/api-keys with scopes: read (discovery + reading your orders), order (buyer actions), fulfill (publisher actions). Rate limit: 120 requests/minute per key."},"servers":[{"url":"https://linkbuildingapi.com/api/v1"}],"webhooks":{"orderEvent":{"post":{"summary":"Order event notification","description":"If your account has a webhook URL configured (Settings), every order event you are a party to is POSTed to it. Headers: X-LBA-Event (event type) and X-LBA-Signature (sha256=<hex HMAC-SHA256 of the raw body, keyed with your signing secret>). One attempt, 10s timeout, no retries; poll GET /orders/{orderId} as the source of truth. Events: order.created, order.accepted, order.rejected, order.published, order.completed, order.auto_completed, order.cancelled, order.expired, ping.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","examples":["order.published"]},"sent_at":{"type":"string","format":"date-time"},"your_role":{"type":"string","enum":["buyer","publisher"]},"order":{"$ref":"#/components/schemas/Order"}}}}}},"responses":{"200":{"description":"Return any 2xx quickly to acknowledge."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key, e.g. lbk_live_..."}},"schemas":{"Site":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["live"]},"title":{"type":["string","null"]},"summary":{"type":["string","null"],"description":"Neutral one-line description (LLM-written)"},"language":{"type":["string","null"]},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"metrics":{"type":["object","null"],"properties":{"domain_rating":{"type":["number","null"],"description":"Ahrefs DR, 0-100"},"domain_authority":{"type":["number","null"],"description":"Moz DA, 0-100"},"spam_score":{"type":["number","null"],"description":"Moz spam score, higher is worse"},"organic_traffic":{"type":["number","null"],"description":"Ahrefs est. monthly organic"},"organic_keywords":{"type":["number","null"]},"referring_domains":{"type":["number","null"]},"checked_at":{"type":"string","format":"date-time"}}},"publisher":{"type":["string","null"],"description":"Publisher slug"},"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["guest_post","link_insertion","homepage_link","profile_link"]},"price_cents":{"type":"integer"},"currency":{"type":"string"},"link_type":{"type":"string","enum":["dofollow","nofollow","sponsored","ugc"]},"max_links":{"type":"integer","description":"Max target/anchor pairs per order"},"min_word_count":{"type":["integer","null"]},"content_by":{"type":"string","enum":["publisher","buyer","either"],"description":"Who writes the article. 'buyer' means you must attach content when ordering."},"content_fee_cents":{"type":["integer","null"],"description":"Surcharge when the publisher writes"},"turnaround_days":{"type":"integer"},"sponsored_label":{"type":"boolean"},"restricted_niches":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}}}},"added_at":{"type":"string","format":"date-time"}}},"Offer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["guest_post","link_insertion","homepage_link","profile_link"]},"price_cents":{"type":"integer"},"currency":{"type":"string"},"link_type":{"type":"string","enum":["dofollow","nofollow","sponsored","ugc"]},"max_links":{"type":"integer","description":"Max target/anchor pairs per order"},"min_word_count":{"type":["integer","null"]},"content_by":{"type":"string","enum":["publisher","buyer","either"],"description":"Who writes the article. 'buyer' means you must attach content when ordering."},"content_fee_cents":{"type":["integer","null"],"description":"Surcharge when the publisher writes"},"turnaround_days":{"type":"integer"},"sponsored_label":{"type":"boolean"},"restricted_niches":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}}},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ref_code":{"type":"string","examples":["LB-7F3K2M"]},"status":{"type":"string","enum":["pending","accepted","rejected","published","completed","cancelled","expired"]},"site_id":{"type":"string","format":"uuid"},"offer_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"price_cents":{"type":"integer"},"currency":{"type":"string"},"content_source":{"type":"string","enum":["buyer","publisher"]},"content_format":{"type":["string","null"],"enum":["html","markdown",null]},"instructions":{"type":["string","null"]},"published_url":{"type":["string","null"]},"rejection_reason":{"type":["string","null"]},"late_days":{"type":["integer","null"],"description":"Days past due when published; null = on time"},"created_at":{"type":"string","format":"date-time"},"accepted_at":{"type":["string","null"],"format":"date-time"},"due_at":{"type":["string","null"],"format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":"string","format":"date-time","description":"Pending orders expire here (7 days)"},"auto_complete_at":{"type":["string","null"],"format":"date-time"},"items":{"type":"array","items":{"type":"object","properties":{"target_url":{"type":"string"},"anchor_text":{"type":"string"}}}},"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"actor":{"type":"string","enum":["buyer","publisher","system","admin"]},"data":{},"at":{"type":"string","format":"date-time"}}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"paths":{"/sites":{"get":{"summary":"List orderable sites","description":"Live sites only. All filters are optional query params. Sites include their offers[], each defining the exact order shape.","security":[{"bearerAuth":[]}],"parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"Exact taxonomy value, see /categories"},{"name":"type","in":"query","schema":{"type":"string","enum":["guest_post","link_insertion","homepage_link","profile_link"]}},{"name":"link_type","in":"query","schema":{"type":"string","enum":["dofollow","nofollow","sponsored","ugc"]}},{"name":"content_by","in":"query","schema":{"type":"string","enum":["publisher","buyer","either"]}},{"name":"min_dr","in":"query","schema":{"type":"number"}},{"name":"min_traffic","in":"query","schema":{"type":"number"}},{"name":"max_price","in":"query","schema":{"type":"integer"},"description":"Cents"},{"name":"language","in":"query","schema":{"type":"string"},"description":"Two-letter code"},{"name":"publisher","in":"query","schema":{"type":"string"},"description":"Publisher slug"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Domain contains"},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"From next_cursor of the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}},"next_cursor":{"type":["string","null"]}}}}}}}}},"/sites/{siteId}":{"get":{"summary":"Site detail with offers (the order shape)","security":[{"bearerAuth":[]}],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"site":{"$ref":"#/components/schemas/Site"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/publishers":{"get":{"summary":"Publisher directory","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"}}}},"/publishers/{slug}":{"get":{"summary":"Publisher profile + live sites","security":[{"bearerAuth":[]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/categories":{"get":{"summary":"Category taxonomy with live-site counts","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"}}}},"/orders":{"post":{"summary":"Place an order (scope: order)","description":"Validates against the offer shape: items count must be 1..max_links; content is required when the offer has content_by=buyer (inline markdown or html up to 256 KB), and must be omitted when content_by=publisher. The publisher has 7 days to respond before the order expires.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["site_id","offer_id","items"],"properties":{"site_id":{"type":"string","format":"uuid"},"offer_id":{"type":"string","format":"uuid"},"items":{"type":"array","minItems":1,"items":{"type":"object","required":["target_url","anchor_text"],"properties":{"target_url":{"type":"string","format":"uri"},"anchor_text":{"type":"string","maxLength":200}}}},"content":{"type":["object","null"],"properties":{"format":{"type":"string","enum":["markdown","html"]},"body":{"type":"string","description":"The full article, max 256 KB"}}},"instructions":{"type":["string","null"]}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}}}}}},"404":{"description":"Site/offer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Shape mismatch (too_many_links, content_required, ...)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List your orders (scope: read)","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","accepted","rejected","published","completed","cancelled","expired"]}},{"name":"role","in":"query","schema":{"type":"string","enum":["buyer","publisher"]},"description":"Default: both sides"},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/orders/{orderId}":{"get":{"summary":"Order detail + event timeline (the polling endpoint)","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"}}}}}},"404":{"description":"Not found"}}}},"/orders/{orderId}/accept":{"post":{"summary":"Accept a pending order (publisher, scope: fulfill)","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"422":{"description":"Wrong status"}}}},"/orders/{orderId}/reject":{"post":{"summary":"Reject a pending order (publisher, scope: fulfill)","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"}}}},"/orders/{orderId}/publish":{"post":{"summary":"Submit the live URL (publisher, scope: fulfill)","description":"Late deliveries (past due_at) are recorded on the order as late_days.","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["published_url"],"properties":{"published_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"OK"}}}},"/orders/{orderId}/cancel":{"post":{"summary":"Cancel while still pending (buyer, scope: order)","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/orders/{orderId}/complete":{"post":{"summary":"Confirm delivery (buyer, scope: order)","description":"Published orders auto-complete after 7 days if you do nothing.","security":[{"bearerAuth":[]}],"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}}