Skip to main content

Ad Acknowledgment

The acknowledgment endpoint closes the ad cycle after your LLM has produced its final response. It must be called after every successful 200 response from the Ad Injection endpoint. Skipping it breaks the reporting cycle and affects publisher payout.

Endpoint​

POST https://api.adstract.ai/api/ad-injection/acknowledge/

Authentication​

All requests must include your API key in the X-Adstract-API-Key header. See Authentication for full details.

Request​

The request includes ad_response_id and llm_response:

{
  "ad_response_id": "55c59ce2-a31f-4ce4-95b3-f930fd9cd564",
  "llm_response": "Here is the full response text your LLM produced..."
}

See Acknowledgment Request Body for the full field reference and request shape.

Full request​

await fetch("https://api.adstract.ai/api/ad-injection/acknowledge/", {
  method: "POST",
  headers: {
    "X-Adstract-API-Key": "your-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ad_response_id: "55c59ce2-a31f-4ce4-95b3-f930fd9cd564",
    llm_response: llmResponse,
  }),
});

Response​

The response body has the same shape for all successful status codes.

  • ad_ack_id
  • status
  • success

The returned status can be:

  • ok
  • no_ad_used
  • recoverable_error
{
  "ad_ack_id": "55c59ce2-a31f-4ce4-95b3-f930fd9cd564",
  "status": "ok",
  "success": true
}

status can be ok, no_ad_used, or recoverable_error. success is true when the acknowledgment completes successfully with ok or no_ad_used, and false when the backend returns recoverable_error. See Acknowledgment Response Body for the response shape.

See Acknowledgment Status Codes for a full breakdown of every code returned by this endpoint.

When to call this endpoint​

Only call the acknowledgment endpoint when the Ad Injection endpoint returned 200. Responses with status 201 (rejected) or 202 (no fill) must not be acknowledged — attempting to do so will return 406.

const injectionResponse = await fetch("https://api.adstract.ai/api/ad-injection/start/", {
  method: "POST",
  headers: { "X-Adstract-API-Key": "your-api-key", "Content-Type": "application/json" },
  body: JSON.stringify({ prompt, request_context }),
});

let promptToUse;
let adResponseId = null;

if (injectionResponse.status === 200) {
  const data = await injectionResponse.json();
  promptToUse = data.enhanced_prompt;
  adResponseId = data.ad_response_id;
} else {
  promptToUse = prompt;
}

const llmResponse = await yourLLM(promptToUse);

if (adResponseId) {
  await fetch("https://api.adstract.ai/api/ad-injection/acknowledge/", {
    method: "POST",
    headers: { "X-Adstract-API-Key": "your-api-key", "Content-Type": "application/json" },
    body: JSON.stringify({ ad_response_id: adResponseId, llm_response: llmResponse }),
  });
}