Build on the EpicDirectories API

EpicDirectories is a directory management platform: a public API and an admin UI for running a directory. You build and host the front-end — we hold the data.

There is no hosted rendering and no end-user auth to integrate. You pull a whole directory through one endpoint at build time, then publish the result on infrastructure and a domain you own. This site is built exactly that way — every page you are looking at came out of the export below.

Reference

• Interactive API docs — every route, generated from the server.
• openapi.json — the machine-readable spec. Also at /docs-json.

The spec is generated from the running service, so it is the authority. If this page and the spec ever disagree, the spec is right.

1. Check what your key can do

Every request carries an API key. Send it as X-API-Key or as Authorization: Bearer — both work, so you can use whichever your HTTP client reaches for first.

curl -H "X-API-Key: $ED_API_KEY" https://api.epicdirectories.com/public/v1/me

Start here rather than with a data call. The response tells you your account, your scopes, and which directories the key can reach — which is the fastest way to find out that a 403 later is a missing scope rather than a bug in your code.

Scopes

[]

Read-only, published listings only. The safest key, and the right one to put in a build pipeline.

write

Any mutation — creating listings, media, taxonomies, attribute templates.

read:drafts

Surfaces listings whose status is anything other than published.

submissions

The anonymous submission queue. Deliberately not implied by read:drafts — strangers' untrusted text and your own drafts are different trust classes.

null

A legacy unrestricted key, from before scopes were enforced. It can write and read drafts. If /me reports this, ask for a re-issued key with explicit scopes — a build-time key should not be able to write.

2. Pull the whole directory

One call returns directory config and listing types, attribute templates, taxonomies with all their terms, recipes, and listings with their attributes, terms and media.

curl -H "X-API-Key: $ED_API_KEY" \
  "https://api.epicdirectories.com/public/v1/directories/YOUR-DIRECTORY/export"

Use ?fields= to project only what you render, and the returned cursor to page. This is the endpoint to build against — the per-listing routes exist for editing, not for assembling a site.

3. Publish it

Whatever you like. The export is plain JSON, so a static site generator, a framework's build step, or a script that writes HTML all work equally well. Nothing about your front-end is our business, which is the point.

Things worth knowing before you start

• A directory-scoped key gets 404, not 403, for directories outside its scope. That is deliberate — a 403 would confirm the directory exists.
• JSON fields are full-replace on PATCH. PATCH {geo:{lat:1}} wipes every other geo key. Read, merge, then write.
• DELETE on a listing is a soft delete (status: "archived") and the slug stays reserved. Restore by setting the status back.
• Renaming a slug keeps the old URL alive. PATCH {slug: "…"} moves a listing and preserves its previous address as an alias, so inbound links keep resolving — and the response tells you the old slug so you can publish the redirect. GET .../listing-aliases returns a directory's whole redirect map in one call.
• Send an Idempotency-Key on writes. A retry with the same key replays the original response instead of re-running the operation.
• Enrichment costs a Google call and is never implicit. Geocoding and Places lookups run only when you ask for them, per listing, and only ever fill blanks — an existing value is never overwritten.

The typed SDK

There is a TypeScript client in the repo under packages/sdk. It is not published to npm — today it is a workspace dependency, so it is available if you are building inside this monorepo and not otherwise. Everything on this page is a plain HTTP call precisely because that is the interface everyone can use.

Getting a key

Keys are issued per account and can be pinned to a single directory. Email kal@epicdesignlabs.com and say which directory you are building against and whether the key needs to write — a build-time key should not.