Skip to content

API

Simple static JSON endpoints published via your site.

Endpoints

  • All components (JSON): /catalog.json
  • One component (JSON): /components/<slug>.json e.g. /components/payments-api.json

If this site is private, browsers must be authenticated. For programmatic access use the GitHub API with a token (PAT or GitHub App).

Example: curl (public site or your own authenticated proxy)

curl -sSL https://<your-domain>/catalog.json | jq .
curl -sSL https://<your-domain>/components/payments-api.json | jq .

Example: GitHub REST API (read catalog-info)

# List repos (paginate if needed)
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/orgs/<org>/repos?per_page=100

# Read file content (Base64)
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/<org>/<repo>/contents/.catalog/catalog-info.yaml?ref=main

Example: GitHub GraphQL API (read file content)

query($org:String!, $repo:String!, $expr:String!) {
  repository(owner:$org, name:$repo) {
    object(expression:$expr) {
      ... on Blob { text }
    }
  }
}

curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.github.com/graphql \
  -d '{"query":"query($org:String!,$repo:String!,$expr:String!){ repository(owner:$org,name:$repo){ object(expression:$expr){ ... on Blob { text } } } }","variables":{"org":"<org>","repo":"<repo>","expr":"HEAD:.catalog/catalog-info.yaml"}}'

CORS

Static sites usually don't send custom CORS headers. Fetch JSON from the same origin or serve behind your own proxy with the headers you need.