Brand protection · UK
PagesEsc
Observations, not verdicts
API · Agency plan

A read-only JSON API for Agency workspaces. Pull every ad seen on your brands' searches into a warehouse, a dashboard or your client reporting, with the same numbers as your pages.

Calls
10
Answers
JSON
Limit
120 a minute
Plan
Agency

Start

A key, then a call.
  1. 1 / 03

    Make a key

    An owner or admin opens the workspace's API tab and makes a key, named for the tool that will use it. The key is shown once: copy it then.

  2. 2 / 03

    Keep it secret

    Put it in your tool's settings or an environment variable, never in a page's code. Anyone holding it reads the workspace.

  3. 3 / 03

    Call

    Send it as a Bearer token. Revoking it on the API tab stops it at the next call.

The address

Every call is a GET under this address.
https://api.godotoro.com/v1/api

Every call sends

Authorization: Bearer gdt_…

A key is gdt_ and 40 letters and digits.

The calls

Every call.

GET/workspace

The workspace

The key's workspace: its name, plan, allowance and how much of it is in use.

Parameters

No parameters.

Other answers 401, 402, 429

Request

curl -H "Authorization: Bearer $GODOTORO_KEY" \
  "https://api.godotoro.com/v1/api/workspace"

Answer, shortened

{
  "workspace": {
    "slug": "northwind",
    "name": "Northwind Digital",
    "plan": "agency",
    "status": "active",
    "allowance": {
      "brands": 15,
      "keywords": 500,
      "cadence": "hourly"
    },
    "used": {
      "brands": 3,
      "keywords": 42
    }
  }
}

GET/brands

Covered brands

The brands the workspace covers, by name, each with its own keywords.

Parameters

No parameters.

Other answers 401, 402, 429

Request

curl -H "Authorization: Bearer $GODOTORO_KEY" \
  "https://api.godotoro.com/v1/api/brands"

Answer, shortened

{
  "brands": [
    {
      "domain": "example-shop.co.uk",
      "name": "Example Shop",
      "aliases": [],
      "addedAt": "2026-06-02T09:14:00.000Z",
      "keywords": [
        {
          "query": "example shop student discount",
          "addedAt": "2026-06-02T09:20:00.000Z"
        }
      ]
    }
  ]
}

GET/brands/{domain}/summary

A brand's numbers

The brand report's numbers for the window, the same figures the brand's report and the Overview show: other advertisers on its searches, ads showing its address, sites listing its codes, what's new and open marks.

Parameters

domainRequiredstring
A brand the workspace covers, by its address.
daysOptional7 · 30 · 90
The window: 7, 30 or 90 days to now. 7 when left out.

Other answers 400, 401, 402, 404, 429

Request

curl -H "Authorization: Bearer $GODOTORO_KEY" \
  "https://api.godotoro.com/v1/api/brands/example-shop.co.uk/summary?days=7"

Answer, shortened

{
  "brand": {
    "domain": "example-shop.co.uk",
    "name": "Example Shop"
  },
  "window": {
    "days": 7,
    "to": "2026-10-19T09:00:00.000Z"
  },
  "dataSince": "2026-03-02",
  "lastCheckedAt": "2026-10-19T09:00:00.000Z",
  "advertisers": 4,
  "voucherSites": 2,
  "changes": {
    "newBidders": 1,
    "newAddressAdvertisers": 0,
    "codesAppeared": 1,
    "codesWent": 0
  },
  "address": {
    "lookedUp": true,
    "others": 2,
    "shopping": 1
  },
  "codes": {
    "checked": true,
    "listedOn": 3,
    "of": 12
  },
  "openMarks": 2,
  "checks": 168
}

GET/brands/{domain}/sightings

Every ad seen

Each ad seen on the brand's searches, the public ones and the workspace's keywords, as the CSV has them: newest first, 500 to a page. London days and time bands, never exact times. Codes in the ads' text are masked.

Parameters

domainRequiredstring
A brand the workspace covers, by its address.
sinceOptionalYYYY-MM-DD
The first London day, YYYY-MM-DD. 30 days ago when left out; 395 days ago at the earliest.
untilOptionalYYYY-MM-DD
The last London day, YYYY-MM-DD. Today when left out.
queryOptionalstring
One query's key: discount_code, voucher_code, promo_code, bare, or custom:<your keyword>.
advertiserOptionalstring
One advertiser, by its address.
cursorOptionalstring
The next of the page before.

Other answers 400, 401, 402, 404, 429

Request

curl -H "Authorization: Bearer $GODOTORO_KEY" \
  "https://api.godotoro.com/v1/api/brands/example-shop.co.uk/sightings?since=2026-10-01"

Answer, shortened

{
  "brand": {
    "domain": "example-shop.co.uk",
    "name": "Example Shop"
  },
  "since": "2026-10-01",
  "until": "2026-10-19",
  "sightings": [
    {
      "day": "2026-10-19",
      "timeBand": "out_of_hours",
      "night": false,
      "query": "example shop discount code",
      "queryKey": "discount_code",
      "advertiser": "deals.example",
      "advertiserName": "Deals Example",
      "kind": "voucher_site",
      "block": "top",
      "position": 1,
      "title": "Example Shop Codes – 20% Off Today",
      "description": "Use code SA•••• at checkout for 20% off.",
      "displayedUrl": "deals.example/example-shop",
      "paidBy": "Deals Example Ltd"
    }
  ],
  "next": "WzkxMjQsNDQwMTJd"
}

GET/alerts

Alerts

The workspace's alerts as its Alerts page lists them, newest first, 100 to a page: each with its words and the evidence behind it. Codes in them are masked.

Parameters

brandOptionalstring
Only this covered brand's, by its address.
kindOptionalnew_bidder · new_address_advertiser · top_position · code_new_provider · against_rules · code_leak · report_ready
Only alerts of this kind.
sinceOptionalYYYY-MM-DD
Only alerts from this London day on, YYYY-MM-DD.
cursorOptionalstring
The next of the page before.

Other answers 400, 401, 402, 404, 429

Request

curl -H "Authorization: Bearer $GODOTORO_KEY" \
  "https://api.godotoro.com/v1/api/alerts?since=2026-10-01"

Answer, shortened

{
  "alerts": [
    {
      "id": 812,
      "kind": "new_bidder",
      "brand": {
        "domain": "example-shop.co.uk",
        "name": "Example Shop"
      },
      "private": false,
      "occurredAt": "2026-10-18T21:04:00.000Z",
      "createdAt": "2026-10-18T21:06:12.000Z",
      "title": "New bidder on Example Shop: Deals Example",
      "lines": [
        "Deals Example seen bidding on ‘example shop discount code’ at 22:04 on 18 Oct, position 1 at the top.",
        "Not seen on Example Shop's searches in the 30 days before."
      ],
      "evidence": {
        "advertiser": {
          "domain": "deals.example",
          "name": "Deals Example"
        }
      }
    }
  ],
  "next": null
}

GET/brands/{domain}/marks

Marks against your rules

The marks made against the rules the workspace saved for the brand, open ones first, each with its evidence and notes: the same list as the brand's report. Ad text is answered with codes masked.

Parameters

domainRequiredstring
A brand the workspace covers, by its address.
statusOptionalopen · closed · new · looking · raised · resolved · allowed
open (new, looking or raised), closed (resolved or allowed), or one status. Every mark when left out.

Other answers 400, 401, 402, 404, 429

Request

curl -H "Authorization: Bearer $GODOTORO_KEY" \
  "https://api.godotoro.com/v1/api/brands/example-shop.co.uk/marks?status=open"

Answer, shortened

{
  "brand": {
    "domain": "example-shop.co.uk",
    "name": "Example Shop"
  },
  "rules": {
    "version": 3,
    "createdAt": "2026-09-01T10:00:00.000Z"
  },
  "counts": {
    "open": 1,
    "closed": 4
  },
  "marks": [
    {
      "id": 51,
      "rule": "brand_bidding",
      "advertiserKey": "domain:deals.example",
      "domain": "deals.example",
      "name": "Deals Example",
      "status": "new",
      "open": true,
      "firstSeenAt": "2026-10-12T20:00:00.000Z",
      "lastSeenAt": "2026-10-18T21:00:00.000Z",
      "searches": 9,
      "evidence": [],
      "notes": []
    }
  ]
}

GET/brands/{domain}/codes

Your codes, masked

The codes the workspace registered for the brand, masked, with where each was listed: sites listing it now and before, and ads that quoted it. Never a code in full.

Parameters

domainRequiredstring
A brand the workspace covers, by its address.

Other answers 401, 402, 404, 429

Request

curl -H "Authorization: Bearer $GODOTORO_KEY" \
  "https://api.godotoro.com/v1/api/brands/example-shop.co.uk/codes"

Answer, shortened

{
  "brand": {
    "domain": "example-shop.co.uk",
    "name": "Example Shop"
  },
  "figures": {
    "codes": 2,
    "private": 1,
    "open": 1,
    "removed": 0
  },
  "codes": [
    {
      "id": "4f0c9a52-7d0e-4c55-9a41-2b7f0f3f6d21",
      "code": "ST••••••",
      "label": "Staff discount",
      "private": true,
      "givenTo": "Staff",
      "validFrom": null,
      "validUntil": null,
      "addedAt": "2026-09-14T08:30:00.000Z",
      "removedAt": null,
      "open": true,
      "listedNow": [
        "Code Site Example"
      ],
      "listedBefore": [],
      "ads": 0,
      "foundOnRegistration": false,
      "lastSeenAt": "2026-10-18T06:00:00.000Z"
    }
  ]
}

GET/brands/{domain}/packs

Evidence packs

The brand's evidence packs that still work, newest first, with each one's link. Whoever holds a link reads that pack, signed out, until it expires or is withdrawn.

Parameters

domainRequiredstring
A brand the workspace covers, by its address.

Other answers 401, 402, 404, 429

Request

curl -H "Authorization: Bearer $GODOTORO_KEY" \
  "https://api.godotoro.com/v1/api/brands/example-shop.co.uk/packs"

Answer, shortened

{
  "brand": {
    "domain": "example-shop.co.uk",
    "name": "Example Shop"
  },
  "packs": [
    {
      "id": "9b1d3c4e-0f6a-4d7e-8c2b-5a6f7e8d9c0b",
      "source": "mark",
      "status": "ready",
      "subject": {
        "kind": "mark",
        "rule": "brand_bidding"
      },
      "advertiser": {
        "name": "Deals Example",
        "domain": "deals.example"
      },
      "sightings": 6,
      "builtAt": "2026-10-18T10:00:00.000Z",
      "readyAt": "2026-10-18T10:01:30.000Z",
      "expiresAt": "2026-11-17T10:00:00.000Z",
      "link": "https://godotoro.com/p/…"
    }
  ]
}

GET/brands/{domain}/reports

Client reports

The brand's client reports that still work, newest first, with each one's link and PDF. A report is fixed when it's made, so its numbers read the same whenever it's opened. Whoever holds a link reads that report, signed out, until it expires or is withdrawn.

Parameters

domainRequiredstring
A brand the workspace covers, by its address.

Other answers 401, 402, 404, 429

Request

curl -H "Authorization: Bearer $GODOTORO_KEY" \
  "https://api.godotoro.com/v1/api/brands/example-shop.co.uk/reports"

Answer, shortened

{
  "brand": {
    "domain": "example-shop.co.uk",
    "name": "Example Shop"
  },
  "reports": [
    {
      "id": "4c2e8f1a-7b3d-4e5f-9a0b-1c2d3e4f5a6b",
      "period": {
        "kind": "last_month",
        "from": "2026-09-01",
        "to": "2026-09-30",
        "label": "September 2026"
      },
      "status": "ready",
      "monthly": true,
      "madeAt": "2026-10-01T06:00:12.000Z",
      "readyAt": "2026-10-01T06:01:40.000Z",
      "expiresAt": "2027-10-31T06:00:12.000Z",
      "link": "https://godotoro.com/r/…",
      "pdf": "https://api.godotoro.com/v1/reports/…/files/report.pdf"
    }
  ]
}

GET/openapi.json

This document

The API as OpenAPI 3.1. No key needed.

No key needed.

Parameters

No parameters.

Request

curl "https://api.godotoro.com/v1/api/openapi.json"

Paging

Long lists come in pages.

Sightings come 500 to a page and alerts 100, newest first. While there's more, an answer's next holds a cursor: pass it back as cursor, with the same other parameters, for the next page. On the last page next is null. A cursor is opaque: don't build or change one.

Sightings are read by London day: the last 30 days when since is left out, and 395 days back at most.

Limits

What it allows.
  • 120 calls a minute per key. Past that, 429 with Retry-After: the seconds to wait.
  • 10 live keys per workspace.
  • Read-only. Rules, packs, codes, reports and keys are made in the app, where roles and the plan are checked.
  • A call never starts a search: it reads what's already stored.

Errors

When a call is refused.
400invalid
A parameter isn't one the call takes: parameter names it. A cursor from another call, or one that was changed, is refused the same way.
401unauthorised
No key, a key we don't hold, or a revoked one. The answer carries WWW-Authenticate: Bearer.
402planpaused
plan: the workspace's plan doesn't include the API (plan names the one that does). paused: the workspace is paused until it has a plan again.
404not_found
The workspace doesn't cover a brand at that address, or the route isn't one the API serves.
429rate_limited
More than 120 calls in a minute with this key. Wait the seconds in Retry-After (and retryAfter) before the next.

What it says

The same rules as the site.
  • Observations with their dates: what Google UK showed for a search, which ads showed an address, where codes were listed. Never a finding about anyone.
  • Codes are masked everywhere: their first characters and their length, never in full.
  • Sightings carry London days and time bands, never exact times.
  • A key reads its own workspace: its keywords' sightings and the public searches for its brands, exactly what its members see. Nothing else.

OpenAPI

The same calls as an OpenAPI 3.1 document, for code generators and API clients. It needs no key.

https://api.godotoro.com/v1/api/openapi.json

The API comes with the Agency plan.