EQL Helper

Developers / public catalog

EQL Helper public API

The /api/v1 catalog API is versioned, read-only, and anonymous by default. JSON is the default representation; NDJSON and XML are available where noted. Optional account keys increase capacity and provide per-key usage guidance, but never grant write access.

Quick start

curl -H 'Accept: application/json' \
  -H 'User-Agent: My-EQL-Tool/1.0 (+https://example.test)' \
  'https://eql.gamertan.com/api/v1/items?q=brell&limit=10'

Use the exact slug returned by a collection or search response:

curl 'https://eql.gamertan.com/api/v1/items/Block_of_Brellium'
Slugs are canonical identifiers, not titles or external page IDs. They are case-sensitive, and some records differ only by case. Do not construct or case-fold them; follow the value returned by this API.

Endpoint map

PurposeRequestUse
MetadataGET /api/v1/catalogRevision, schema, hash, formats, and counts.
CollectionsGET /api/v1/{collection}Bounded search, filtering, sorting, and cursor paging.
RecordGET /api/v1/{collection}/{slug}One canonical record using an exact returned slug.
ChangesGET /api/v1/changes?since=REVISIONIncremental synchronization after a known revision.
Cross-catalog searchGET /api/v1/search?q=TEXTCompact discovery across record kinds.
RegistriesGET /api/v1/profiles
GET /api/v1/sources
GET /api/v1/partners		Compatibility, provenance, and approved external references.
TravelGET /api/v1/travel/*Neighborhood discovery, goals, and journey planning.

Collections: items, spells, actions, stances, quests, recipes, tradeskills, npcs, merchants, factions, and zones.

Paging, synchronization, and caching

curl -i -H 'If-None-Match: "YOUR_ETAG"' \
  'https://eql.gamertan.com/api/v1/items?limit=200'

curl 'https://eql.gamertan.com/api/v1/changes?since=42&limit=200'

Representations

Use Accept: application/json, application/x-ndjson, or application/xml. A format=json|jsonl|xml convenience parameter is available when a client cannot set headers. NDJSON pagination metadata is sent in response headers and Link relations rather than as a synthetic first row.

curl -H 'Accept: application/x-ndjson' \
  'https://eql.gamertan.com/api/v1/spells?limit=200'

curl -H 'Accept: application/xml' \
  'https://eql.gamertan.com/api/v1/zones/Chardok'

Evidence and compatibility

The default profile is eql-main, with evidence=include-unverified. That preserves useful legacy records without falsely claiming every field is confirmed for EQL. Use evidence=confirmed for stricter results, and inspect record provenance, evidence state, compatibility, and approved external references when correctness matters.

Errors and recovery

StatusMeaningClient action
400Invalid or excessive bounded input.Correct the request; do not retry unchanged.
401A supplied API key was invalid or disabled.Replace or remove it. Invalid credentials never silently downgrade to anonymous.
404Route or exact canonical record was not found.Discover the record and use its returned slug.
409A cursor belongs to an older catalog revision.Restart that traversal.
429Temporary capacity limit.Pause for Retry-After, then retry with bounded backoff.
5xxTransient service failure.Retry conservatively; report persistent failures with request ID.

API errors are compact problem documents. Conventional OpenAPI discovery routes are valid documentation requests and do not accrue abuse strikes.

Capacity and identification

Anonymous clients receive 120 requests per minute with a burst of 60 and up to four concurrent requests. Read keys receive 600 per minute with a burst of 200 and up to eight concurrent requests. Send a stable, descriptive User-Agent such as ProjectName/Version (+project-or-contact-URL); it helps us distinguish integrations and offer useful guidance if a client struggles.

Create an account or manage a key from API keys and usage. Send keys only as Authorization: Bearer …, never in URLs. Query strings are part of operational request logs, so credentials and private data do not belong there.

Machine-readable contracts