Beladed mark Beladed Docs
Help Sign in Create account

Beladed Ads API

Track Interaction

beta

Track Interaction through the reviewed Beladed Ads contract.

POST/api/ads/placement/interact/{placementId}
curl --request POST 'https://api.beladed.dev/api/ads/placement/interact/id_demo_001' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "interactionData": {
    "type": "click",
    "position": {
      "x": 364,
      "y": 45
    },
    "userId": "id_demo_001",
    "timestamp": "2025-08-28T12:00:00Z"
  }
}'

Parameters

placementIdpathrequired

string — The placementId for this request.

Example: id_demo_001

Request body

Requestapplication/json
Schema
{
  "type": "object",
  "properties": {
    "interactionData": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "position": {
          "type": "object",
          "properties": {
            "x": {
              "type": "integer"
            },
            "y": {
              "type": "integer"
            }
          }
        },
        "userId": {
          "type": "string"
        },
        "timestamp": {
          "type": "string"
        }
      }
    }
  }
}
{
  "interactionData": {
    "type": "click",
    "position": {
      "x": 364,
      "y": 45
    },
    "userId": "id_demo_001",
    "timestamp": "2025-08-28T12:00:00Z"
  }
}

Responses

200The request succeeded.
Responseapplication/jsonClient handling: raw JSON
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string"
        }
      }
    },
    "requestId": {
      "type": "string"
    }
  }
}
{
  "data": {
    "id": "id_demo_001",
    "status": "available"
  },
  "requestId": "req_demo_001"
}

Errors

400invalid_request

The request did not satisfy the documented contract.

404not_found

The requested public or account-owned resource was not found.

429rate_limited

Retry after the current product limit resets.

Reliability

Idempotency
No public Idempotency-Key guarantee is declared; use a stable client reference and confirm resource state before retrying.
Pagination
Not applicable.
Rate limit
Subject to current account, product, and abuse-protection limits. Honor Retry-After when returned.
Webhook events
No related public event is declared.

Contract provenance

This operation is published from reviewed route, handler, and test contracts. Internal implementation paths remain private.

Contract owner
Beladed Ads API team
Verification
Route and collection reviewed
Reviewed
2026-07-12
Mark this page
Share details
Type to search the complete public documentation catalog.