krcg-api 3.4
Web API for VTES cards and TWDA
Requires Python: >=3.10
Keywords: CCG, TWD, TWDA, Vampire: The Eternal Struggle, api, vtes, web

# KRCG API

[![PyPI version](https://badge.fury.io/py/krcg-api.svg)](https://badge.fury.io/py/krcg-api)
[![Validation](https://github.com/lionel-panhaleux/krcg-api/actions/workflows/validation.yml/badge.svg)](https://github.com/lionel-panhaleux/krcg-api/actions/workflows/validation.yml)
[![Python version](https://img.shields.io/badge/python-3.8-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-MIT-blue)](https://opensource.org/licenses/MIT)
[![Code Style](https://img.shields.io/badge/code%20style-black-black)](https://github.com/psf/black)

A web API for V:tES based on
the VEKN [official card texts](http://www.vekn.net/card-lists)
and the [Tournament Winning Deck Archive (TWDA)](http://www.vekn.fr/decks/twd.htm).

Portions of the materials are the copyrights and trademarks of Paradox Interactive AB,
and are used with permission. All rights reserved.
For more information please visit [white-wolf.com](http://www.white-wolf.com).

![Dark Pack](dark-pack.png)

## Online API and documentation

KRCG is a free to use (and documented) [online API](https://api.krcg.org/).
Anyone is free to use it, without warranty.

Breaking changes will only be introduced at major version upgrades,
after a proper deprecation period.

## Contribute

**Contributions are welcome !**

This API is an offspring of the [KRCG](https://github.com/lionel-panhaleux/krcg)
python package, so please refer to that repository for issues, discussions
and contributions guidelines.

## Examples

Query a card by name or ID, get text, rulings and image URL:

```bash
curl -X GET "http://127.0.0.1:8000/card/Alastor" -H  "accept: application/json"
```

```json
{
  "_name": "Alastor",
  "_set": "Gehenna:R, KMW:PAl, KoT:R",
  "artists": [
    "Monte Moore"
  ],
  "card_text": "Requires a justicar or Inner Circle member...",
  "id": 100038,
  "name": "Alastor",
  "ordered_sets": [
    "Gehenna",
    "Kindred Most Wanted",
    "Keepers of Tradition"
  ],
  "printed_name": "Alastor",
  "rulings": {
    "links": {
      "[ANK 20200901]": "http://www.vekn.net/forum/rules-questions/78830-alastor-and-ankara-citadel#100653",
      "[LSJ 20040518-2]": "https://groups.google.com/g/rec.games.trading-cards.jyhad/c/4emymfUPwAM/m/JF_o7OOoCbkJ",
      "[LSJ 20040518]": "https://groups.google.com/d/msg/rec.games.trading-cards.jyhad/4emymfUPwAM/B2SCC7L6kuMJ"
    },
    "text": [
      "If the weapon retrieved costs blood, that cost is paid by the vampire chosen by the vote. [LSJ 20040518]",
      "Requirements do not apply. If a discipline is required (eg. {Inscription}) and the Alastor vampire does not have it, the inferior version is used. [ANK 20200901] [LSJ 20040518-2]"
    ]
  },
  "scans": {
    "Gehenna": "https://static.krcg.org/card/set/gehenna/alastor.jpg",
    "Keepers of Tradition": "https://static.krcg.org/card/set/keepers-of-tradition/alastor.jpg",
    "Kindred Most Wanted": "https://static.krcg.org/card/set/kindred-most-wanted/alastor.jpg"
  },
  "sets": {
    "Gehenna": [{ "rarity": "Rare", "release_date": "2004-05-17"}],
    "Keepers of Tradition": [{ "rarity": "Rare", "release_date": "2008-11-19"}],
    "Kindred Most Wanted": [
      {
        "copies": 1,
        "precon": "Alastors",
        "release_date": "2005-02-21"
      }
    ]
  },
  "types": ["Political Action"],
  "url": "https://static.krcg.org/card/alastor.jpg"
}
```

Search for cards by text, type, discipline, title, city, artist, set,
preconstructed starter, group, capacity, trait, sect, bonus values, etc.:

```bash
curl
    -X POST "http://127.0.0.1:8000/card_search"
    -H "Content-Type: application/json"
    -d "{\"type\":[\"political action\"],\"sect\":[\"anarch\"]}"
```

```json
[
    "Anarch Salon",
    "Eat the Rich",
    "Firebrand",
    "Free States Rant",
    "Patsy",
    "Reckless Agitation",
    "Revolutionary Council",
    "Sweeper"
]
```

Get candidates for your decklist out of the **TWDA**:

```bash
curl
    -X POST "http://127.0.0.1:8000/candidates"
    -H  "Content-Type: application/json"
    -d "{\"cards\":[\"Cybele\",\"Nana Buruku\"]}"
```

```json
[
  {
    "average": 14,
    "card": "Ashur Tablets",
    "deviation": 6.25,
    "score": 1
  },
  {
    "average": 1,
    "card": "Giant's Blood",
    "deviation": 0,
    "score": 1
  },
  {
    "average": 2,
    "card": "The Parthenon",
    "deviation": 0.81,
    "score": 1
  },
  {
    "average": 1,
    "card": "Archon Investigation",
    "deviation": 0,
    "score": 0.9
  },
  ...
]
```

And a few other features, including:

-   search decks in the TWDA, by cards, dates, author and number of players
-   deck list format conversion
-   retrieving a decklist from an Amaranth share URL
-   card name completions

Check the [online documentation](https://api.krcg.org/) for more.

### Hosting the web API

To host the web API, you can use uv or pip to install it:

```bash
uv pip install "krcg-api"
# or
pip install "krcg-api"
```

No wsgi server is installed by default, you need to install one.
HTTP web servers can then easily be configured to serve WSGI applications,
check the documentation of your web server.

The API can be served with [uWSGI](https://uwsgi-docs.readthedocs.io):

```bash
uwsgi --module krcg_api.wsgi:application
```

or [Gunicorn](https://gunicorn.org):

```bash
gunicorn krcg_api.wsgi:application
```

Two environment variables are expected: `GITHUB_USERNAME` and `GITHUB_TOKEN`,
to allow the API to connect to Github as a user in order to post new rulings
as issues on the repository (`/submit-ruling` endpoint).

See the [Github help](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line)
on how to generate a personal token for the account you want KRCG to use.

#### Development

The development version of KRCG uses [uv](https://github.com/astral-sh/uv) for package management
and installs uWSGI to serve the API, this is the preferred WSGI server for now.

```bash
$ uv pip install -e ".[dev]"
$ just serve
...
uwsgi socket 0 bound to TCP address 127.0.0.1:8000
```

You can check the API is running by using your browser
on the provided address [http://127.0.0.1:8000](http://127.0.0.1:8000).

The environment variables `GITHUB_USERNAME` and `GITHUB_TOKEN` can be provided
by a personal `.env` file at the root of the krcg folder (ignored by git):

```bash
export GITHUB_USERNAME="dedicated_github_username_for_the_api"
export GITHUB_TOKEN="the_matching_github_token"
```