directories

Create a new directory (low-level — prefer /from-template for typical use)

post/v1/directories

Request

  • Base URL: https://api.epicdirectories.com
  • URL: https://api.epicdirectories.com/v1/directories
  • Auth: HTTP bearer

Request body

slugstring required

URL-friendly slug for the directory

namestring required

Display name of the directory

domainobject nullable

Public domain this directory is published on, as a bare hostname. A pasted URL is normalised — scheme, port, path and case are stripped, and a leading "www." is KEPT because it is part of the hostname. Null or an empty string clears it.

listingTypesobject required

Listing types supported by this directory

seoPolicyobject

SEO policy configuration

monetizationPolicyobject

Monetization policy configuration

mediaPolicyobject

Media policy configuration

submissionPolicyobject

Opt-in for anonymous public writes. Absent/empty accepts nothing. Keys: suggestions, feedback, reviews, comments (page comments). Each flag must be exactly true — see common/directory-open-policy.ts.

enrichmentPolicyobject

Site-probe config. Absent = ON with defaults — unlike submissionPolicy, which is opt-in because it accepts untrusted writes. Probing writes nothing public. Keys: { probe: bool, autoApprove: bool, rubric?: string, linkSweepAttributes?: [{ key, liveness? }] }.

linkSweepAttributes adds this directory’s own url-typed ATTRIBUTE values to the link sweep, which otherwise checks only the one URL in canonicalFields. An explicit allowlist, in priority order — enrichment writes url-typed attributes of its own (site_og_image, site_canonical_url, site_final_url) that nobody wants checked, and one sweep run is capped, so something has to go first. liveness: "endpoint" marks a field that is a machine surface rather than a page: any HTTP response counts as alive, and only an unreachable host or a 410 is dead. An API root answering 404 is normal.

sweepSchedule makes the link sweep run on its own: true for daily, or { "everyHours": 24 }. Absent means OFF, and that default is deliberate — unlike probe, which is on by default because a sweep only ever ran when a person asked for one. Removing the person does not keep that safe: every directory on the platform reads probe !== false today, so deriving the schedule from it would enrol all 74,387 listings in a perpetual crawl. probe: false still wins over any schedule. Catch-up after a capped run is automatic, so no cadence shorter than an hour is accepted or needed.

linkDeadOn decides what counts as dead beyond an unreachable host: { tls: true } counts a certificate fault, { timeoutAfter: 2 } counts a URL that has timed out that many checks in a row. Both default OFF and neither can be turned on globally — three Convention Grid listings have a www. certificate that does not cover the host while serving 200 at the apex, and that report deliberately leaves them out.

themestring

Theme identifier

themeSettingsobject

Theme settings (colors etc.)

Example request

{
  "submissionPolicy": {
    "suggestions": true,
    "feedback": true
  },
  "enrichmentPolicy": {
    "probe": true,
    "linkSweepAttributes": [
      {
        "key": "docs_url"
      },
      {
        "key": "openapi_url"
      },
      {
        "key": "base_url",
        "liveness": "endpoint"
      },
      {
        "key": "signup_url"
      }
    ],
    "linkDeadOn": {
      "tls": true,
      "timeoutAfter": 2
    },
    "sweepSchedule": {
      "everyHours": 24
    }
  },
  "theme": "default",
  "themeSettings": {
    "primaryColor": "#3b82f6",
    "secondaryColor": "#1e40af"
  }
}

Response

Directory created successfully

Changes

No recorded changes to this operation across all 1 revision of this API.