Ads

All endpoints use the base URL /v1. Authenticated endpoints require a valid Bearer token in the Authorization header.

---

Ad Campaigns

List My Ads

GET /v1/ads

Returns all ad campaigns owned by the authenticated user.

Authentication: Required

Response 200 OK:

{
  "ads": [
    {
      "id": "uuid",
      "title": "Summer Sale Campaign",
      "content": "Check out our summer collection!",
      "budget": 500,
      "price_per_view": 0.05,
      "spent_budget": 120.50,
      "views_count": 2410,
      "status": "active",
      "media_url": "https://cdn.example.com/ads/summer-sale.jpg",
      "target_url": "https://example.com/summer",
      "created_at": "2025-06-01T09:00:00.000Z",
      "updated_at": "2025-06-10T14:00:00.000Z"
    }
  ]
}

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.

---

Create Ad

POST /v1/ads

Creates a new ad campaign. The ad is created with status set to draft, spent_budget set to 0, and views_count set to 0.

Authentication: Required

Request Body:

Field	Type	Required	Description
title	string	Yes	Ad campaign title.
content	string	Yes	Ad copy / description.
budget	number	Yes	Total budget for the campaign.
price_per_view	number	Yes	Cost deducted per impression.
media_url	string	No	URL to the ad creative (image or video).
target_url	string	No	URL the ad links to when clicked.

Request Example:

{
  "title": "Summer Sale Campaign",
  "content": "Check out our summer collection with 50% off!",
  "budget": 500,
  "price_per_view": 0.05,
  "media_url": "https://cdn.example.com/ads/summer-sale.jpg",
  "target_url": "https://example.com/summer"
}

Response 201 Created:

{
  "ad": {
    "id": "uuid",
    "user_id": "uuid",
    "title": "Summer Sale Campaign",
    "content": "Check out our summer collection with 50% off!",
    "budget": 500,
    "price_per_view": 0.05,
    "spent_budget": 0,
    "views_count": 0,
    "status": "draft",
    "media_url": "https://cdn.example.com/ads/summer-sale.jpg",
    "target_url": "https://example.com/summer",
    "created_at": "2025-06-12T08:00:00.000Z"
  }
}

Note

New ads are created with status: "draft". An admin must approve the ad (setting status to active) before it can be served. See the Admin Ads endpoints.

Errors:

Status	Description
400 Bad Request	Missing required fields (title, content, budget, or price_per_view).
401 Unauthorized	Missing or invalid Bearer token.

---

Serve Ad

GET /v1/ads/serve

Returns a random active ad that still has remaining budget (spent_budget < budget). Used to display ads to users. No authentication required.

Authentication: None (public)

Response 200 OK (ad available):

{
  "ad": {
    "id": "uuid",
    "title": "Summer Sale Campaign",
    "content": "Check out our summer collection with 50% off!",
    "media_url": "https://cdn.example.com/ads/summer-sale.jpg",
    "target_url": "https://example.com/summer"
  }
}

Response 200 OK (no ads available):

{
  "ad": null
}

---

Update Ad

PATCH /v1/ads/{id}

Updates an ad campaign. Only the ad owner can update their own ads.

Authentication: Required (owner only)

Path Parameters:

Parameter	Type	Required	Description
id	uuid	Yes	The ad’s unique ID.

Request Body:

Any ad fields can be updated:

Field	Type	Required	Description
title	string	No	Updated ad title.
content	string	No	Updated ad copy.
budget	number	No	Updated total budget.
price_per_view	number	No	Updated cost per impression.
media_url	string	No	Updated media URL.
target_url	string	No	Updated target URL.

Request Example:

{
  "title": "Summer Sale Campaign - Extended!",
  "budget": 750
}

Response 200 OK:

{
  "ad": {
    "id": "uuid",
    "title": "Summer Sale Campaign - Extended!",
    "budget": 750,
    "updated_at": "2025-06-15T10:00:00.000Z"
  }
}

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.
403 Forbidden	Authenticated user is not the owner of this ad.
404 Not Found	No ad exists with the given ID.

---

Delete Ad

DELETE /v1/ads/{id}

Deletes an ad campaign. Only the ad owner can delete their own ads.

Authentication: Required (owner only)

Path Parameters:

Parameter	Type	Required	Description
id	uuid	Yes	The ad’s unique ID.

Response 200 OK:

{
  "message": "Ad deleted"
}

Errors:

Status	Description
401 Unauthorized	Missing or invalid Bearer token.
403 Forbidden	Authenticated user is not the owner of this ad.
404 Not Found	No ad exists with the given ID.

---

Record Impression

POST /v1/ads/{id}/impression

Records a single ad impression. Increments views_count by 1 and adds price_per_view to spent_budget. If spent_budget exceeds or equals budget after the increment, the ad status is automatically set to paused.

Authentication: None (public)

Path Parameters:

Parameter	Type	Required	Description
id	uuid	Yes	The ad’s unique ID.

Response 200 OK:

{
  "message": "Impression recorded"
}

Note

When spent_budget reaches or exceeds budget, the ad’s status is automatically changed to paused and it will no longer be returned by the serve endpoint.

Errors:

Status	Description
404 Not Found	No ad exists with the given ID.

---

Reports

Submit Report

POST /v1/reports

Submits a report against a piece of content or a user. Reports are reviewed by administrators via the Admin Reports endpoints.

Authentication: Required

Request Body:

Field	Type	Required	Description
reportable_id	uuid	Yes	ID of the item being reported.
reportable_type	string	Yes	Type of the reported item. One of: post, user, product, comment.
reason	string	Yes	Reason for the report.
description	string	No	Additional details about the report.

Request Example:

{
  "reportable_id": "post-uuid",
  "reportable_type": "post",
  "reason": "Spam content",
  "description": "This post contains repeated spam links and irrelevant advertising."
}

Response 201 Created:

{
  "report": {
    "id": "uuid",
    "reporter_id": "uuid",
    "reportable_id": "post-uuid",
    "reportable_type": "post",
    "reason": "Spam content",
    "description": "This post contains repeated spam links and irrelevant advertising.",
    "status": "pending",
    "created_at": "2025-06-12T09:00:00.000Z"
  }
}

Errors:

Status	Description
400 Bad Request	Missing required fields or invalid reportable_type. Must be one of: post, user, product, comment.
401 Unauthorized	Missing or invalid Bearer token.