Language: English

API v1

Static, cacheable JSON that apps and the FootyCrests Figma plugin use to search crests, show previews and request downloads. No key is needed for public crest data. Versioned paths never change meaning; breaking changes ship as /api/v2/.

Endpoints

MethodPathReturns
GET/api/v1/index.jsonEvery published crest as a compact row: [id, name, kind, country, preview, search, versions, history, nameEn]. Field names are listed in fields; kinds in kinds.
GET/api/v1/entities/{id}.jsonOne crest with its versions: file names and sizes, a 640 px preview, a 128 px thumbnail and the grant endpoint of each file.

Files

Original files are kept in private storage and never have a public URL. To download one, send POST to the file's grant endpoint; the answer has a single-use url valid for 60 seconds, bound to the same browser session (cookie fc_sid). Downloads are limited per session and per IP, and a limited request answers 429 with Retry-After. Previews (GET /api/crests/{id}/preview/{version}?w=320|640, WebP) and 128 px thumbnails are public.

Example

GET https://footycrests.com/api/v1/entities/ac-milan.json

{
  "id": "ac-milan",
  "name": "AC Milan",
  "kind": "club",
  "country": "IT",
  "versions": [
    {
      "key": "primary",
      "type": "standard",
      "preview": "/api/crests/ac-milan/preview/primary?w=640",
      "files": [
        {
          "format": "png",
          "name": "ac-milan-logo-footycrests.png",
          "bytes": 102832,
          "grant": "/api/crests/ac-milan/files/ac-milan-logo-footycrests.png/grant"
        },
        {
          "format": "svg",
          "name": "ac-milan-logo-footycrests.svg",
          "bytes": 5535,
          "grant": "/api/crests/ac-milan/files/ac-milan-logo-footycrests.svg/grant"
        }
      ]
    }
  ]
}

Rules