Connect your agent

Your Conflict Gauge API key lets an AI agent read the editions of your plan for you: Claude, Microsoft Copilot, a script or any tool that can send a web request. It takes three steps. ChatGPT connects by signing in, with no key, and Claude can too. Developers can go straight to the code.

1. Make a key

Sign in and open your account. Under API key, choose Make a key. The key starts cgk_ and is shown once, so copy it then.

2. Give it to your agent

Follow the section for your assistant below, with your key in place of YOUR_KEY. Keep the key out of anything you share: it opens your plan.

3. Ask for this week's edition

Ask your agent: "What does this week's Conflict Gauge edition show?" It reads the list of your editions, then the newest one, and answers from its figures.

Assistants

The connector's tools list the editions, read one, give a figure's data and search the editions. Its address is https://conflictgauge.com/mcp.

Claude

This works in claude.ai, Claude Desktop and Claude in Excel. Open Settings, then Customize, then Connectors, and choose Add, then Add custom connector. Enter https://conflictgauge.com/mcp as the address, then choose one of these:

With your key: under authentication, choose No sign-in, even though the dialog may mark Sign in now as Detected. Under Request headers, add Authorization with the value Bearer YOUR_KEY.
With one-click sign-in: choose Sign in now, sign in with the link we mail you and allow Claude to read your editions. You need no key for this, and you can remove the connection on your account page. Not yet tested by us.

Claude Code

Add Conflict Gauge as a connector with one command:

claude mcp add --transport http conflict-gauge https://conflictgauge.com/mcp --header "Authorization: Bearer YOUR_KEY"

ChatGPT

This needs a paid ChatGPT plan, and it is not tested by us. ChatGPT connects by signing in, so it uses no key.

In ChatGPT on the web, open Settings, then Apps (Apps and Connectors in some versions), then Advanced settings, and turn on Developer Mode.
Back under Apps, choose Create.
Give it a name, enter https://conflictgauge.com/mcp as the address and choose OAuth as the authentication.
Sign in with the link we mail you and allow ChatGPT to read your editions.
In a new chat, choose the + button, then More, and pick the app.

ChatGPT changes these menus, so yours may differ. You can remove the connection on your account page. If you try ChatGPT, Codex or ChatGPT's computer use and it does not work, tell us what happened. We have not tested these ourselves. Leave your key out of the report.

Microsoft Copilot

Not tested by us. Copilot connects through Copilot Studio only, which needs a work or school account with a Copilot Studio licence. Personal Microsoft 365 and the consumer Copilot app cannot add a connector of this kind. In Copilot Studio, open your agent, then:

Choose Tools, then Add a tool, then Model Context Protocol.
Enter https://conflictgauge.com/mcp as the URL.
Under Authentication, choose API key, with Type Header and the name Authorization.
When it asks for the value, enter Bearer YOUR_KEY.

If it does not work, tell us what happened. Leave your key out of the report.

Any agent with a shell or fetch tool

I subscribe to Conflict Gauge: Iran, a weekly data edition. My API key is YOUR_KEY.
To read it, send the header "Authorization: Bearer YOUR_KEY" with every request, and never put the key in an address.
1. GET https://conflictgauge.com/editions.json. It lists the editions my key reads, newest first.
2. GET https://conflictgauge.com followed by the edition_json address of the first edition. It is the whole edition as JSON: its sections and its findings, each with a headline, the figure, how it was read, caveats and the path of its data file.
3. A figure's CSV is at https://conflictgauge.com/editions/<label>/paid/ followed by its data path.
Report what the figures measure, not causes. Cite every figure as "Source: Conflict Gauge: Iran (conflictgauge.com)" with the edition's date.

Other assistants

Put this in the assistant's custom instructions. It works where the assistant can call a web address with a header, for example through an action or a code tool with web access. Where it cannot, use a script from the next section.

When I ask about Conflict Gauge, read it from https://conflictgauge.com/editions.json with the header "Authorization: Bearer YOUR_KEY". Take the first edition in the list and fetch its edition_json address on https://conflictgauge.com with the same header. Answer from its findings: each has a headline, the figure and how it was read. Say what the figures measure, never causes, and cite "Source: Conflict Gauge: Iran (conflictgauge.com)" with the edition's date.

For developers

Each block reads your key from the environment variable CG_API_KEY, so the key stays out of your code. Set it first: export CG_API_KEY="YOUR_KEY" in a shell, or $env:CG_API_KEY = "YOUR_KEY" in PowerShell.

Python

This needs nothing beyond Python itself. It lists your editions, saves the newest edition.json, prints the edition's title and the headline of each finding, then saves every figure CSV in a folder. edition.json has no executive summary: the findings' headlines are the short version.

import json
import os
import pathlib
import urllib.request

BASE = "https://conflictgauge.com"
KEY = os.environ["CG_API_KEY"]


def get(path):
    headers = {"Authorization": "Bearer " + KEY}
    request = urllib.request.Request(BASE + path, headers=headers)
    with urllib.request.urlopen(request) as response:
        return response.read()


editions = json.loads(get("/editions.json"))["editions"]
for edition in editions:
    print(edition["label"], edition["title"])

latest = editions[0]
folder = pathlib.Path("conflict-gauge") / latest["label"]
folder.mkdir(parents=True, exist_ok=True)
data = get(latest["edition_json"])
(folder / "edition.json").write_bytes(data)

document = json.loads(data)
print(document["edition"]["title"])
for finding in document["findings"]:
    print("-", finding["headline"])

for address in latest["csv"]:
    target = folder / address.split("/paid/")[1]
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_bytes(get(address))
print("Saved", len(latest["csv"]), "CSV files in", folder)

Python with pandas

This loads one figure's CSV from the newest edition into a DataFrame.

import json
import os
import urllib.request

import pandas as pd

BASE = "https://conflictgauge.com"
HEADERS = {"Authorization": "Bearer " + os.environ["CG_API_KEY"]}

request = urllib.request.Request(BASE + "/editions.json", headers=HEADERS)
with urllib.request.urlopen(request) as response:
    latest = json.load(response)["editions"][0]

address = next(a for a in latest["csv"] if a.endswith("/figures.csv"))
# The last line of a CSV read with a key is its fingerprint, so it is left out here.
frame = pd.read_csv(BASE + address, storage_options=HEADERS, skipfooter=1, engine="python")
print(frame.head())

curl

The same three calls: the list, an edition, a figure. Take the addresses from the list. In PowerShell, write curl.exe and $env:CG_API_KEY.

curl -fsS -H "Authorization: Bearer $CG_API_KEY" https://conflictgauge.com/editions.json
curl -fsS -H "Authorization: Bearer $CG_API_KEY" https://conflictgauge.com/editions/2026-w18/paid/edition.json -o edition.json
curl -fsS -H "Authorization: Bearer $CG_API_KEY" https://conflictgauge.com/editions/2026-w18/paid/figures.csv -o figures.csv

A scheduled pull

Editions are released on Monday at 06:00 Amsterdam time. Save this as cg_pull.py in your home folder. It fetches an edition only if its label is new, so its first run fetches them all and a later run fetches only what has been released since. Each lands in a conflict-gauge folder beside the script.

import json
import os
import pathlib
import urllib.request

BASE = "https://conflictgauge.com"
KEY = os.environ["CG_API_KEY"]
HERE = pathlib.Path(__file__).resolve().parent / "conflict-gauge"


def get(path):
    headers = {"Authorization": "Bearer " + KEY}
    request = urllib.request.Request(BASE + path, headers=headers)
    with urllib.request.urlopen(request) as response:
        return response.read()


for edition in json.loads(get("/editions.json"))["editions"]:
    target = HERE / edition["label"] / "edition.json"
    if target.exists():
        continue
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_bytes(get(edition["edition_json"]))
    print("Saved", edition["label"])

Then run it every Monday. Both lines below use your machine's clock, so change the time if it is not on Amsterdam time.

With cron, keep the line export CG_API_KEY="YOUR_KEY" in the file .cg_api_key in your home folder, readable by you alone:

15 6 * * 1 . "$HOME/.cg_api_key" && python3 "$HOME/cg_pull.py"

With Windows Task Scheduler, run setx CG_API_KEY "YOUR_KEY" once, then:

schtasks /Create /TN "Conflict Gauge pull" /SC WEEKLY /D MON /ST 06:15 /TR "cmd /c cd /d %USERPROFILE% && python cg_pull.py"

Reference

Address

Every address starts https://conflictgauge.com. Send the key in the Authorization header of every request, as Bearer and the key, and never in an address.

What a key reads

/editions.json: the editions your key reads, newest first. Each has its label, its kind, its title, its window, the address of its edition.json and the address of each figure CSV under csv.
/editions/<label>/paid/edition.json: the whole edition as structured data.
The figure CSVs listed under csv.

When a request is refused

401: the key is missing, mistyped or revoked. Check the header, or make a new key on your account page.
403: the key works, but your plan does not cover that file.

How often to ask

A new edition arrives once a week, so a script only needs to ask after the Monday release. The daily limit on a key is on /api.

What an agent may do

An agent may read and summarise Conflict Gauge for the subscriber it works for, on any plan; passing edition content to other people's users or customers needs the team plan or a licence. Using these figures has the details, and the API page says more about what a key reads.

Credit

Cite every figure as "Source: Conflict Gauge: Iran (conflictgauge.com)" with the edition's date.

No key yet? A key comes with every plan: subscribe.