{"openapi":"3.1.0","info":{"title":"sponsor.ink API","version":"1.0.0","description":"REST API for the sponsor.ink guest post marketplace. Advertisers browse listings and place orders; publishers manage sites and fulfil placements. Escrow holds funds until the live URL is delivered.\n\nHuman-readable documentation: https:\/\/sponsor.ink\/api-docs\n\nAuthentication uses Laravel Sanctum personal access tokens (Bearer). API access requires admin approval after signup. Tokens are scoped with abilities per role.","contact":{"name":"sponsor.ink","url":"https:\/\/sponsor.ink\/contact"},"license":{"name":"Proprietary"}},"tags":[{"name":"Account","description":"Current user profile"},{"name":"Marketplace","description":"Browse active publisher listings (advertisers)"},{"name":"Orders","description":"Place and manage guest post orders"},{"name":"Sites","description":"Publisher site listings"},{"name":"Wallet","description":"Balance and transactions"}],"security":[{"bearerAuth":[]}],"paths":{"\/me":{"get":{"operationId":"getAccount","tags":["Account"],"summary":"Current account","description":"Returns the authenticated user. Requires `profile:read` ability.","responses":{"200":{"description":"Account details","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/User"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"}}}},"\/marketplace":{"get":{"operationId":"searchMarketplace","tags":["Marketplace"],"summary":"Search marketplace listings","description":"Paginated list of active publisher sites. Requires `marketplace:read` ability.","parameters":[{"$ref":"#\/components\/parameters\/search"},{"$ref":"#\/components\/parameters\/minDr"},{"$ref":"#\/components\/parameters\/maxPrice"},{"$ref":"#\/components\/parameters\/category"},{"$ref":"#\/components\/parameters\/language"},{"$ref":"#\/components\/parameters\/country"},{"$ref":"#\/components\/parameters\/linkType"},{"$ref":"#\/components\/parameters\/perPage"},{"$ref":"#\/components\/parameters\/page"}],"responses":{"200":{"description":"Paginated listings","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Site"}},"links":{"$ref":"#\/components\/schemas\/PaginationLinks"},"meta":{"$ref":"#\/components\/schemas\/PaginationMeta"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"}}}},"\/marketplace\/{site}":{"get":{"operationId":"getMarketplaceSite","tags":["Marketplace"],"summary":"Get one marketplace listing","description":"Returns a single active listing. `{site}` is the listing public id (32-character hex). Draft or paused sites return 404. Requires `marketplace:read` ability.","parameters":[{"$ref":"#\/components\/parameters\/siteId"}],"responses":{"200":{"description":"Listing details","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Site"}}}}}},"404":{"$ref":"#\/components\/responses\/NotFound"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"}}}},"\/orders":{"get":{"operationId":"listOrders","tags":["Orders"],"summary":"List orders","description":"Advertisers see orders they placed. Publishers see orders on their sites. Requires `orders:read` ability.","parameters":[{"$ref":"#\/components\/parameters\/perPage"},{"$ref":"#\/components\/parameters\/page"}],"responses":{"200":{"description":"Paginated orders","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Order"}},"links":{"$ref":"#\/components\/schemas\/PaginationLinks"},"meta":{"$ref":"#\/components\/schemas\/PaginationMeta"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"}}}},"\/orders\/{order}":{"get":{"operationId":"getOrder","tags":["Orders"],"summary":"Get order details","description":"Order detail with site, timeline events, and `meta.allowed_transitions` for the current user. Requires `orders:read` ability.","parameters":[{"$ref":"#\/components\/parameters\/orderId"}],"responses":{"200":{"description":"Order details","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Order"},"meta":{"type":"object","properties":{"allowed_transitions":{"type":"array","items":{"type":"string"}}}}}}}}},"404":{"$ref":"#\/components\/responses\/NotFound"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"}}}},"\/sites\/{site}\/orders":{"post":{"operationId":"placeOrder","tags":["Orders"],"summary":"Place an order","description":"Create a guest post order on an active listing. Price and commission lock at placement; wallet is debited immediately. Requires `orders:write` ability. Rate limit: 20 writes\/minute.","parameters":[{"$ref":"#\/components\/parameters\/siteId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PlaceOrderRequest"}},"multipart\/form-data":{"schema":{"allOf":[{"$ref":"#\/components\/schemas\/PlaceOrderRequest"},{"type":"object","properties":{"content_file":{"type":"string","format":"binary","description":"Optional article file (doc, docx, txt, md, html, pdf; max 5 MB). Use with type `provided`."}}}]}}}},"responses":{"201":{"description":"Order created","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Order"},"meta":{"type":"object","properties":{"allowed_transitions":{"type":"array","items":{"type":"string"}}}}}}}}},"422":{"$ref":"#\/components\/responses\/ValidationError"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/orders\/{order}\/transition":{"post":{"operationId":"transitionOrder","tags":["Orders"],"summary":"Change order status","description":"Move an order to the next allowed status. Publishers: pending\u2192accepted\/rejected, accepted\u2192in_progress, in_progress\/revision\u2192delivered (live_url required). Advertisers: pending\u2192cancelled, delivered\u2192completed\/revision. Requires `orders:write` ability.","parameters":[{"$ref":"#\/components\/parameters\/orderId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/OrderTransitionRequest"}}}},"responses":{"200":{"description":"Updated order","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Order"},"meta":{"type":"object","properties":{"allowed_transitions":{"type":"array","items":{"type":"string"}}}}}}}}},"403":{"$ref":"#\/components\/responses\/Forbidden"},"422":{"$ref":"#\/components\/responses\/ValidationError"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/orders\/{order}\/messages":{"post":{"operationId":"sendOrderMessage","tags":["Orders"],"summary":"Post a message on an order","description":"Adds a message to the order timeline. Requires `orders:write` ability.","parameters":[{"$ref":"#\/components\/parameters\/orderId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":5000}}}}}},"responses":{"201":{"description":"Message posted","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/OrderEvent"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/sites":{"get":{"operationId":"listSites","tags":["Sites"],"summary":"List your sites","description":"Returns sites owned by the authenticated publisher. Requires `sites:read` ability and publisher role.","parameters":[{"$ref":"#\/components\/parameters\/perPage"},{"$ref":"#\/components\/parameters\/page"}],"responses":{"200":{"description":"Paginated sites","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Site"}},"links":{"$ref":"#\/components\/schemas\/PaginationLinks"},"meta":{"$ref":"#\/components\/schemas\/PaginationMeta"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"}}},"post":{"operationId":"createSite","tags":["Sites"],"summary":"Create a site listing","description":"Creates a draft site listing for review. Requires `sites:write` ability and publisher role.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateSiteRequest"}}}},"responses":{"201":{"description":"Site created","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Site"}}}}}},"422":{"$ref":"#\/components\/responses\/ValidationError"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/sites\/{site}":{"get":{"operationId":"getSite","tags":["Sites"],"summary":"Get one of your sites","parameters":[{"$ref":"#\/components\/parameters\/siteId"}],"responses":{"200":{"description":"Site details","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Site"}}}}}},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"401":{"$ref":"#\/components\/responses\/Unauthorized"}}},"put":{"operationId":"updateSite","tags":["Sites"],"summary":"Update a site listing","parameters":[{"$ref":"#\/components\/parameters\/siteId"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateSiteRequest"}}}},"responses":{"200":{"description":"Updated site","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Site"}}}}}},"422":{"$ref":"#\/components\/responses\/ValidationError"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}},"delete":{"operationId":"deleteSite","tags":["Sites"],"summary":"Delete a site listing","parameters":[{"$ref":"#\/components\/parameters\/siteId"}],"responses":{"204":{"description":"Site deleted"},"403":{"$ref":"#\/components\/responses\/Forbidden"},"404":{"$ref":"#\/components\/responses\/NotFound"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"429":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/wallet":{"get":{"operationId":"getWallet","tags":["Wallet"],"summary":"Wallet balance and transactions","description":"Returns balance and paginated transaction history. Advertisers top up via Stripe Checkout on the web dashboard. Requires `wallet:read` ability.","parameters":[{"$ref":"#\/components\/parameters\/perPage"},{"$ref":"#\/components\/parameters\/page"}],"responses":{"200":{"description":"Wallet data","content":{"application\/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Wallet"},"meta":{"$ref":"#\/components\/schemas\/PaginationMeta"},"links":{"$ref":"#\/components\/schemas\/PaginationLinks"}}}}}},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"403":{"$ref":"#\/components\/responses\/Forbidden"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal access token from Profile (prefix `si_`). Requires approved API access."}},"parameters":{"siteId":{"name":"site","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{32}$"},"description":"Listing public id (32-character hex)"},"orderId":{"name":"order","in":"path","required":true,"schema":{"type":"string"},"description":"Order public id"},"search":{"name":"search","in":"query","schema":{"type":"string"},"description":"Domain or site name"},"minDr":{"name":"min_dr","in":"query","schema":{"type":"integer","minimum":0,"maximum":100},"description":"Minimum Ahrefs DR"},"maxPrice":{"name":"max_price","in":"query","schema":{"type":"number","minimum":0},"description":"Maximum provided-content price"},"category":{"name":"category","in":"query","schema":{"type":"string"},"description":"Category slug"},"language":{"name":"language","in":"query","schema":{"type":"string"},"description":"Language code (e.g. en)"},"country":{"name":"country","in":"query","schema":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 country code"},"linkType":{"name":"link_type","in":"query","schema":{"type":"string","enum":["dofollow","nofollow","sponsored"]}},"perPage":{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}},"page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}}},"schemas":{"User":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["advertiser","publisher","admin"]},"balance":{"type":"string","description":"Decimal string"},"email_verified_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"Site":{"type":"object","properties":{"id":{"type":"string","description":"Public id (32-char hex)"},"url":{"type":"string","format":"uri"},"domain":{"type":"string"},"name":{"type":["string","null"]},"description":{"type":["string","null"]},"language":{"type":"string"},"country":{"type":["string","null"]},"categories":{"type":"array","items":{"type":"string"}},"metrics":{"type":"object","properties":{"ahrefs_dr":{"type":["integer","null"]},"ahrefs_rd":{"type":["integer","null"]},"traffic_monthly":{"type":["integer","null"]}}},"pricing":{"type":"object","properties":{"content_provided":{"type":"string"},"content_written":{"type":["string","null"]}}},"turnaround_days":{"type":"integer"},"link_type":{"type":"string","enum":["dofollow","nofollow","sponsored"]},"max_links":{"type":"integer"},"publisher_rules":{"type":["string","null"]},"status":{"type":"string","description":"Only returned for site owner"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"type":{"type":"string","enum":["provided","written"]},"status":{"type":"string","enum":["pending","accepted","in_progress","delivered","revision","completed","rejected","cancelled","disputed"]},"brief":{"type":["string","null"]},"target_url":{"type":"string","format":"uri"},"anchor_text":{"type":["string","null"]},"content":{"type":["string","null"]},"live_url":{"type":["string","null"],"format":"uri"},"price":{"type":"string"},"commission_percent":{"type":"string"},"commission_amount":{"type":"string"},"publisher_amount":{"type":"string"},"accepted_at":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"site":{"$ref":"#\/components\/schemas\/Site"},"events":{"type":"array","items":{"$ref":"#\/components\/schemas\/OrderEvent"}}}},"OrderEvent":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"from_status":{"type":["string","null"]},"to_status":{"type":["string","null"]},"body":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"Wallet":{"type":"object","properties":{"balance":{"type":"string"},"transactions":{"type":"array","items":{"$ref":"#\/components\/schemas\/Transaction"}}}},"Transaction":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"amount":{"type":"string"},"balance_after":{"type":["string","null"]},"note":{"type":["string","null"]},"order_id":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"}}},"PlaceOrderRequest":{"type":"object","required":["type","target_url"],"properties":{"type":{"type":"string","enum":["provided","written"]},"target_url":{"type":"string","format":"uri","maxLength":255},"anchor_text":{"type":"string","maxLength":255},"brief":{"type":"string","maxLength":5000},"content":{"type":"string","maxLength":50000,"description":"Required for type `provided` unless content_file is sent"}}},"OrderTransitionRequest":{"type":"object","required":["to_status"],"properties":{"to_status":{"type":"string","enum":["pending","accepted","in_progress","delivered","revision","completed","rejected","cancelled","disputed"]},"note":{"type":"string","maxLength":2000},"live_url":{"type":"string","format":"uri","maxLength":255,"description":"Required when moving to delivered if not already set"}}},"CreateSiteRequest":{"type":"object","required":["url","language","price_content_provided","turnaround_days","link_type","max_links"],"properties":{"url":{"type":"string","format":"uri","maxLength":255},"name":{"type":"string","maxLength":255},"description":{"type":"string","maxLength":2000},"language":{"type":"string","maxLength":10},"country":{"type":"string","minLength":2,"maxLength":2},"categories":{"type":"array","items":{"type":"string"}},"ahrefs_dr":{"type":"integer","minimum":0,"maximum":100},"ahrefs_rd":{"type":"integer","minimum":0},"traffic_monthly":{"type":"integer","minimum":0},"price_content_provided":{"type":"number","minimum":1,"maximum":99999},"price_content_written":{"type":"number","minimum":1,"maximum":99999},"turnaround_days":{"type":"integer","minimum":1,"maximum":90},"link_type":{"type":"string","enum":["dofollow","nofollow","sponsored"]},"max_links":{"type":"integer","minimum":1,"maximum":10},"publisher_rules":{"type":"string","maxLength":2000}}},"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer"},"last_page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"}}},"PaginationLinks":{"type":"object","properties":{"first":{"type":["string","null"],"format":"uri"},"last":{"type":["string","null"],"format":"uri"},"prev":{"type":["string","null"],"format":"uri"},"next":{"type":["string","null"],"format":"uri"}}},"Error":{"type":"object","properties":{"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, revoked, or expired token","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Forbidden":{"description":"Wrong ability, role, or transition not allowed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"NotFound":{"description":"Unknown or inactive resource","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"ValidationError":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"RateLimited":{"description":"Too many requests","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}},"servers":[{"url":"https:\/\/sponsor.ink\/api\/v1","description":"Production API"}]}