Citadel game data API

curl

API=https://api.thecitadel.com
UA='MyFitTool/1.0 (me@example.com)'
FIT_STRING='<a fit string from the game>'

curl -A "$UA" "$API/v1/status"

# Conditional request: 304 with no body while the data is unchanged
etag=$(curl -s -D - -o /dev/null -A "$UA" "$API/v1/hulls" | tr -d '\r' | awk 'tolower($1) == "etag:" { print $2 }')
curl -i -A "$UA" -H "If-None-Match: $etag" "$API/v1/hulls"

# Turn an in-game fit string into a fit, then check it
curl -s -A "$UA" -H 'Content-Type: application/json' \
     -d "{ \"fitString\": \"$FIT_STRING\" }" "$API/v1/fits/import" |
  curl -A "$UA" -H 'Content-Type: application/json' -d @- "$API/v1/fits/evaluate"

JavaScript

Node 18 or later, as an ES module. Browsers send their own User-Agent and don't let you change it, so leave that header out in a web page; those calls get no warning.

const api = "https://api.thecitadel.com";
const headers = { "User-Agent": "MyFitTool/1.0 (me@example.com)" };
const fitString = "<a fit string from the game>";

const status = await fetch(`${api}/v1/status`, { headers }).then((r) => r.json());
console.log(status.build);

// Conditional request: 304 with no body while the data is unchanged.
const first = await fetch(`${api}/v1/hulls`, { headers });
const { hulls } = await first.json();
const again = await fetch(`${api}/v1/hulls`, {
  headers: { ...headers, "If-None-Match": first.headers.get("ETag") },
});
console.log(again.status); // 304

// Art: every item and hull has an `art` object of API-relative URLs.
console.log(`${api}${hulls[0].art.base}`);

// Turn an in-game fit string into a fit, then check it.
const post = (path, body) =>
  fetch(`${api}${path}`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  }).then((r) => r.json());
const { fit } = await post("/v1/fits/import", { fitString });
const result = await post("/v1/fits/evaluate", { fit });
console.log(result.valid, result.rating);

Python

Python 3, standard library only.

import json
import urllib.error
import urllib.request

API = "https://api.thecitadel.com"
USER_AGENT = "MyFitTool/1.0 (me@example.com)"
FIT_STRING = "<a fit string from the game>"


def call(path, body=None, headers=None):
    request = urllib.request.Request(API + path, headers={"User-Agent": USER_AGENT, **(headers or {})})
    if body is not None:
        request.data = json.dumps(body).encode()
        request.add_header("Content-Type", "application/json")
    try:
        with urllib.request.urlopen(request) as response:
            return response.status, response.headers, response.read()
    except urllib.error.HTTPError as error:
        if error.code != 304:
            raise
        return error.code, error.headers, b""


_, _, status = call("/v1/status")
print(json.loads(status)["build"])

# Conditional request: 304 with no body while the data is unchanged.
_, headers, _ = call("/v1/hulls")
code, _, _ = call("/v1/hulls", headers={"If-None-Match": headers["ETag"]})
print(code)  # 304

# Turn an in-game fit string into a fit, then check it.
_, _, imported = call("/v1/fits/import", {"fitString": FIT_STRING})
_, _, evaluated = call("/v1/fits/evaluate", {"fit": json.loads(imported)["fit"]})
result = json.loads(evaluated)
print(result["valid"], result["rating"])

C#

.NET 8, as a top-level program.

using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.thecitadel.com") };
http.DefaultRequestHeaders.UserAgent.ParseAdd("MyFitTool/1.0 (me@example.com)");
var fitString = "<a fit string from the game>";

var status = await http.GetFromJsonAsync<JsonElement>("/v1/status");
Console.WriteLine(status.GetProperty("build"));

// Conditional request: 304 with no body while the data is unchanged.
using var first = await http.GetAsync("/v1/hulls");
var conditional = new HttpRequestMessage(HttpMethod.Get, "/v1/hulls");
conditional.Headers.IfNoneMatch.Add(first.Headers.ETag!);
using var again = await http.SendAsync(conditional);
Console.WriteLine((int)again.StatusCode); // 304

// Turn an in-game fit string into a fit, then check it.
var imported = await (await http.PostAsJsonAsync("/v1/fits/import", new { fitString }))
    .Content.ReadFromJsonAsync<JsonElement>();
var result = await (await http.PostAsJsonAsync("/v1/fits/evaluate", new { fit = imported.GetProperty("fit") }))
    .Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine($"{result.GetProperty("valid")} {result.GetProperty("rating")}");

Go

Go 1.18 or later, standard library only.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
)

const api = "https://api.thecitadel.com"
const userAgent = "MyFitTool/1.0 (me@example.com)"
const fitString = "<a fit string from the game>"

func call(path string, body any, header http.Header) (*http.Response, []byte) {
	method, reader := http.MethodGet, io.Reader(nil)
	if body != nil {
		encoded, err := json.Marshal(body)
		if err != nil {
			log.Fatal(err)
		}
		method, reader = http.MethodPost, bytes.NewReader(encoded)
	}
	req, err := http.NewRequest(method, api+path, reader)
	if err != nil {
		log.Fatal(err)
	}
	for name, values := range header {
		req.Header[name] = values
	}
	req.Header.Set("User-Agent", userAgent)
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	data, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	return resp, data
}

func main() {
	_, status := call("/v1/status", nil, nil)
	fmt.Println(string(status))

	// Conditional request: 304 with no body while the data is unchanged.
	first, _ := call("/v1/hulls", nil, nil)
	again, _ := call("/v1/hulls", nil, http.Header{"If-None-Match": {first.Header.Get("ETag")}})
	fmt.Println(again.StatusCode) // 304

	// Turn an in-game fit string into a fit, then check it.
	_, imported := call("/v1/fits/import", map[string]string{"fitString": fitString}, nil)
	var fit struct {
		Fit json.RawMessage `json:"fit"`
	}
	if err := json.Unmarshal(imported, &fit); err != nil {
		log.Fatal(err)
	}
	_, evaluated := call("/v1/fits/evaluate", fit, nil)
	var result struct {
		Valid  bool `json:"valid"`
		Rating int  `json:"rating"`
	}
	if err := json.Unmarshal(evaluated, &result); err != nil {
		log.Fatal(err)
	}
	fmt.Println(result.Valid, result.Rating)
}

curl

The polling half uses jq.

API=https://api.thecitadel.com
UA='MyKillBot/1.0 (me@example.com)'

# Follow the stream; -N prints each event as it arrives. Ctrl-C to stop.
curl -N -A "$UA" "$API/v1/kills/stream?kind=pvp"

# Or poll: start from the newest kill, then ask for whatever was listed after it.
cursor=$(curl -s -A "$UA" "$API/v1/kills?limit=1" | jq -r '.kills[0].cursor')
while sleep 15; do
  page=$(curl -s -A "$UA" "$API/v1/kills/feed?kind=pvp&after=$cursor")
  echo "$page" | jq -r '.kills[] | "\(.victim.name) lost a \(.victim.hull.name)"'
  cursor=$(echo "$page" | jq -r '.cursor')
done

JavaScript

In a web page. EventSource reconnects by itself and resumes after the last kill it saw.

const stream = new EventSource("https://api.thecitadel.com/v1/kills/stream?kind=pvp");

stream.addEventListener("kill", (event) => {
  const kill = JSON.parse(event.data);
  console.log(`${kill.victim.name} lost a ${kill.victim.hull.name}`, kill.value?.total);
});

// Sent instead of a replay when the page was away for over an hour: fetch the
// kills after `after`, up to and including `until`, from /v1/kills/feed.
stream.addEventListener("gap", (event) => console.log(JSON.parse(event.data)));

Python

Python 3, standard library only.

import json
import time
import urllib.request

API = "https://api.thecitadel.com"
USER_AGENT = "MyKillBot/1.0 (me@example.com)"


def get(path):
    request = urllib.request.Request(API + path, headers={"User-Agent": USER_AGENT})
    with urllib.request.urlopen(request) as response:
        return json.load(response)


# Start from the newest kill, then ask for whatever was listed after it.
cursor = get("/v1/kills?limit=1")["kills"][0]["cursor"]
while True:
    time.sleep(15)
    page = get(f"/v1/kills/feed?kind=pvp&after={cursor}")
    for kill in page["kills"]:
        print(f'{kill["victim"]["name"]} lost a {kill["victim"]["hull"]["name"]}')
    cursor = page["cursor"]

C#

.NET 8, as a top-level program.

using System.Net.Http.Json;
using System.Text.Json;

using var http = new HttpClient { BaseAddress = new Uri("https://api.thecitadel.com") };
http.DefaultRequestHeaders.UserAgent.ParseAdd("MyKillBot/1.0 (me@example.com)");

// Start from the newest kill, then ask for whatever was listed after it.
var newest = await http.GetFromJsonAsync<JsonElement>("/v1/kills?limit=1");
var cursor = newest.GetProperty("kills")[0].GetProperty("cursor").GetString();
while (true)
{
    await Task.Delay(TimeSpan.FromSeconds(15));
    var page = await http.GetFromJsonAsync<JsonElement>($"/v1/kills/feed?kind=pvp&after={cursor}");
    foreach (var kill in page.GetProperty("kills").EnumerateArray())
    {
        var victim = kill.GetProperty("victim");
        Console.WriteLine($"{victim.GetProperty("name")} lost a {victim.GetProperty("hull").GetProperty("name")}");
    }
    cursor = page.GetProperty("cursor").GetString();
}

Go

Go 1.18 or later, standard library only.

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"time"
)

const api = "https://api.thecitadel.com"
const userAgent = "MyKillBot/1.0 (me@example.com)"

type kill struct {
	Cursor string `json:"cursor"`
	Victim struct {
		Name string `json:"name"`
		Hull struct {
			Name string `json:"name"`
		} `json:"hull"`
	} `json:"victim"`
}

type page struct {
	Kills  []kill `json:"kills"`
	Cursor string `json:"cursor"`
}

func get(path string) page {
	req, err := http.NewRequest(http.MethodGet, api+path, nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("User-Agent", userAgent)
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	var p page
	if err := json.NewDecoder(resp.Body).Decode(&p); err != nil {
		log.Fatal(err)
	}
	return p
}

func main() {
	// Start from the newest kill, then ask for whatever was listed after it.
	cursor := get("/v1/kills?limit=1").Kills[0].Cursor
	for {
		time.Sleep(15 * time.Second)
		p := get("/v1/kills/feed?kind=pvp&after=" + cursor)
		for _, k := range p.Kills {
			fmt.Printf("%s lost a %s\n", k.Victim.Name, k.Victim.Hull.Name)
		}
		cursor = p.Cursor
	}
}