submissions

Suggest a listing (anonymous)

Unauthenticated. Requires the directory to have opted in via submissionPolicy.suggestions = true; otherwise 404 — a directory never accepts anonymous writes by default.

Rate limited to 5 per hour per IP, per directory. Send a Cloudflare Turnstile token as turnstileToken when Turnstile is configured server-side.

Programmatic callers: send X-API-Key instead of a Turnstile token. A valid key whose scopes include submissions skips the human check and files directly as pending, with a much higher rate limit. A key is a stronger identity claim than Turnstile, which only approximates "probably human". An INVALID key is rejected with 401 rather than falling back to anonymous — omit the header entirely to submit anonymously.

Always returns 202 { accepted: true } for anything that passes validation — including submissions judged to be spam, which are stored with status: spam instead of pending. Bots get no signal about which check caught them. Nothing is published; an operator reviews and promotes.

post/public/v1/directories/{directory}/submissions

Request

  • Base URL: https://api.epicdirectories.com
  • URL: https://api.epicdirectories.com/public/v1/directories/{directory}/submissions
  • Auth: none declared

Path parameters

directorystring required

Request body

titlestring required

Name of the thing being suggested

urlstring required

Its website

descriptionstring

What it is, in the submitter's words

categorystring

Suggested category, as free text. NOT resolved to a taxonomy term here — an operator decides that on review, optionally via the taxonomy resolve endpoints.

emailstring

Submitter email, for follow-up. Never published.

turnstileTokenstring

Cloudflare Turnstile token from the widget. Required when Turnstile is configured.

extraobject

Values for the extra fields THIS directory declares in submissionPolicy.extraFields — read them from GET /public/v1/directories/{directory} and render inputs to match. Keys this directory has not declared are rejected with 400 naming them, rather than dropped: a dropped answer makes the form look like it worked while the operator reviews a submission missing the field they asked for.

website2string

Honeypot. Leave empty. A real browser never fills it, so a non-empty value is accepted with 202 and recorded as spam — silently, so bots get no signal to adapt.

Example request

{
  "extra": {
    "replaces": [
      "acme-cloud"
    ],
    "self_hostable": true,
    "submitter_role": "maintainer"
  }
}

Response

Received. Not published — queued for review.

Changes

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