OnBriefing API documentation

https://onbriefing.com/api/v1

Authorization: Bearer obk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -X POST https://onbriefing.com/api/v1/campaigns \
  -H "Authorization: Bearer $ONBRIEFING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer 2026: launch",
    "brand": "Brand X",
    "rulesText": "The video must be at least 30s long, show the product in use, say the promo code SUMMER26 out loud and use #BrandXSummer and #ad in the caption. Competitors must not be mentioned."
  }'

curl -X POST https://onbriefing.com/api/v1/campaigns/$CAMPAIGN_ID/verifications \
  -H "Authorization: Bearer $ONBRIEFING_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://www.tiktok.com/@creator/video/7300000000000000001"] }'

curl https://onbriefing.com/api/v1/verifications/$VERIFICATION_ID \
  -H "Authorization: Bearer $ONBRIEFING_KEY"

const BASE = "https://onbriefing.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.ONBRIEFING_KEY}`,
  "Content-Type": "application/json",
};

async function api(path, init = {}) {
  const res = await fetch(BASE + path, { ...init, headers });
  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
  return body;
}

const campaign = await api("/campaigns", {
  method: "POST",
  body: JSON.stringify({ name: "Pilot", brand: "Brand X", rulesText: BRIEF }),
});

const { outcomes } = await api(`/campaigns/${campaign.id}/verifications`, {
  method: "POST",
  body: JSON.stringify({ urls: VIDEO_URLS }),
});

const ids = outcomes.filter((o) => o.status === "queued").map((o) => o.id);

async function waitFor(id) {
  for (;;) {
    const v = await api(`/verifications/${id}`);
    if (v.status === "COMPLETED" || v.status === "FAILED") return v;
    await new Promise((r) => setTimeout(r, 30_000));
  }
}

const reports = await Promise.all(ids.map(waitFor));

import os, time, requests

BASE = "https://onbriefing.com/api/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['ONBRIEFING_KEY']}"

campaign = s.post(f"{BASE}/campaigns", json={
    "name": "Pilot", "brand": "Brand X", "rulesText": BRIEF,
}).json()

outcomes = s.post(f"{BASE}/campaigns/{campaign['id']}/verifications",
                  json={"urls": VIDEO_URLS}).json()["outcomes"]

for o in outcomes:
    if o["status"] != "queued":
        continue
    while True:
        v = s.get(f"{BASE}/verifications/{o['id']}").json()
        if v["status"] in ("COMPLETED", "FAILED"):
            print(v["videoUrl"], v["status"], v["verdict"])
            break
        time.sleep(30)

QUEUED → DOWNLOADING → TRANSCRIBING → ANALYZING → COMPLETED
                                                     ↘ FAILED

POST /api/v1/campaigns
{
  "name": "Summer 2026: launch",
  "brand": "Brand X",
  "rulesText": "The video must be at least 30s long, show the product in use and mention the promo code SUMMER26."
}

{
  "id": "cm8x1a2b3c4d5e6f7g8h9i0j",
  "orgId": "cm7o...",
  "name": "Summer 2026: launch",
  "brand": "Brand X",
  "rulesText": "The video must be at least 30s long, show the product in use and mention the promo code SUMMER26.",
  "active": true,
  "archivedAt": null,
  "hasWebhook": false,
  "webhookUrl": null,
  "createdAt": "2026-10-09T14:00:00.000Z",
  "updatedAt": "2026-10-09T14:00:00.000Z"
}

{
  "id": "cm8x1a2b3c4d5e6f7g8h9i0j",
  "name": "Summer 2026: launch",
  "hasWebhook": true,
  "webhookUrl": "https://your-app.com/webhooks/onbriefing",
  "verificationCount": 128,
  ...
}

PATCH /api/v1/campaigns/cm8x1a2b3c4d5e6f7g8h9i0j
{ "webhookUrl": "https://your-app.com/webhooks/onbriefing" }

{
  "id": "cm8x1a2b3c4d5e6f7g8h9i0j",
  "hasWebhook": true,
  "webhookUrl": "https://your-app.com/webhooks/onbriefing",
  "webhookSecret": "9f2c6b1e...64 hex characters"
}

POST /api/v1/campaigns/cm8x1a2b3c4d5e6f7g8h9i0j/verifications
{
  "urls": [
    "https://www.tiktok.com/@creator1/video/7300000000000000001",
    "https://www.instagram.com/reel/ABC123/",
    "https://www.youtube.com/shorts/dQw4w9WgXcQ",
    "https://example.com/video"
  ]
}

{
  "outcomes": [
    { "url": "https://www.tiktok.com/@creator1/video/7300000000000000001", "status": "queued", "id": "cm8x9z..." },
    { "url": "https://www.instagram.com/reel/ABC123/", "status": "duplicate" },
    { "url": "https://www.youtube.com/shorts/dQw4w9WgXcQ", "status": "insufficient_credits", "detail": "..." },
    { "url": "https://example.com/video", "status": "invalid", "detail": "Host não permitido: example.com. Aceitos: TikTok, Instagram e YouTube." }
  ]
}

{
  "items": [
    {
      "id": "cm8x9z...",
      "videoUrl": "https://www.tiktok.com/@creator1/video/7300000000000000001",
      "platform": "TIKTOK",
      "status": "COMPLETED",
      "verdict": "APPROVED",
      "finalVerdict": null,
      "errorCode": null,
      "createdAt": "2026-10-09T14:01:00.000Z",
      "completedAt": "2026-10-09T14:04:12.000Z"
    }
  ],
  "nextCursor": "cm8x9y..."
}

let cursor = null;
do {
  const qs = new URLSearchParams({ status: "COMPLETED", ...(cursor ? { cursor } : {}) });
  const page = await api(`/campaigns/${campaignId}/verifications?${qs}`);
  for (const item of page.items) handle(item);
  cursor = page.nextCursor;
} while (cursor);

{
  "id": "cm8x9z...",
  "campaignId": "cm8x1a2b3c4d5e6f7g8h9i0j",
  "videoUrl": "https://www.tiktok.com/@creator1/video/7300000000000000001",
  "platform": "TIKTOK",
  "status": "COMPLETED",
  "verdict": "REJECTED",
  "finalVerdict": null,
  "summary": "Shows the product and uses the hashtag, but doesn't mention the code and runs 22s.",
  "contentCategories": ["REVIEW", "DEPOIMENTO"],
  "errorCode": null,
  "error": null,
  "createdAt": "2026-10-09T14:01:00.000Z",
  "startedAt": "2026-10-09T14:01:05.000Z",
  "completedAt": "2026-10-09T14:04:12.000Z",
  "findings": [
    {
      "ruleText": "Say the promo code SUMMER26 out loud",
      "scope": "VERIFIABLE",
      "status": "FAIL",
      "severity": "MAJOR",
      "rationale": "The code doesn't appear in the transcript or on-screen text.",
      "confidence": 0.86,
      "evidence": [
        { "type": "ABSENT", "note": "Full transcript and on-screen text; no mention of SUMMER26.",
          "frameIndex": null, "timestampMs": null, "quote": null, "field": null, "value": null }
      ]
    },
    {
      "ruleText": "Use #BrandXSummer in the caption",
      "scope": "VERIFIABLE",
      "status": "PASS",
      "severity": "MAJOR",
      "rationale": "The hashtag is in the caption.",
      "confidence": 0.97,
      "evidence": [
        { "type": "METADATA", "field": "hashtags", "value": "brandxsummer, ad",
          "frameIndex": null, "timestampMs": null, "quote": null, "note": null }
      ]
    }
  ]
}

POST https://your-app.com/webhooks/onbriefing
Content-Type: application/json
X-OnBriefing-Event: verification.completed
X-OnBriefing-Signature: sha256=5d41402abc4b2a76b9719d911017c592...

{
  "event": "verification.completed",
  "verification": {
    "id": "cm8x9z...",
    "campaignId": "cm8x1a2b3c4d5e6f7g8h9i0j",
    "videoUrl": "https://www.tiktok.com/@creator1/video/7300000000000000001",
    "platform": "TIKTOK",
    "status": "COMPLETED",
    "verdict": "REJECTED",
    "summary": "Shows the product and uses the hashtag, but doesn't mention the code and runs 22s.",
    "contentCategories": ["REVIEW"],
    "errorCode": null,
    "completedAt": "2026-10-09T14:04:12.000Z",
    "findings": [
      { "ruleText": "Say the promo code SUMMER26 out loud", "scope": "VERIFIABLE",
        "status": "FAIL", "severity": "MAJOR",
        "rationale": "The code doesn't appear in the transcript.", "confidence": 0.86 }
    ]
  }
}

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();

app.post(
  "/webhooks/onbriefing",
  express.raw({ type: "application/json" }), // raw body, not parsed
  (req, res) => {
    const expected = createHmac("sha256", process.env.ONBRIEFING_WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");
    const received = String(req.get("X-OnBriefing-Signature") ?? "").replace("sha256=", "");

    const valid =
      expected.length === received.length &&
      timingSafeEqual(Buffer.from(expected), Buffer.from(received));
    if (!valid) return res.sendStatus(401);

    const { event, verification } = JSON.parse(req.body);
    // Respond fast; process in the background.
    queue.add({ event, verification });
    res.sendStatus(200);
  },
);

import { createHmac, timingSafeEqual } from "node:crypto";

export async function POST(request: Request) {
  const raw = await request.text();
  const expected = createHmac("sha256", process.env.ONBRIEFING_WEBHOOK_SECRET!).update(raw).digest("hex");
  const received = (request.headers.get("x-onbriefing-signature") ?? "").replace("sha256=", "");

  if (expected.length !== received.length ||
      !timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    return new Response("invalid signature", { status: 401 });
  }

  const { event, verification } = JSON.parse(raw);
  // ...
  return new Response(null, { status: 200 });
}

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["ONBRIEFING_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/onbriefing")
def onbriefing_webhook():
    raw = request.get_data()  # raw body
    expected = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    received = request.headers.get("X-OnBriefing-Signature", "").removeprefix("sha256=")
    if not hmac.compare_digest(expected, received):
        abort(401)

    payload = request.get_json()
    # ...
    return "", 200

{ "error": "Cole o briefing da campanha. É ele que define o que será verificado.", "field": "rulesText" }