Developers

What there is, and what there is not

Overcode is an engineering practice, not a software product. There is no account to create, no dashboard, no API key, and no data API. The public HTTP surface is one endpoint — the contact form — plus the machine-readable files that describe this site.

That is stated plainly because the alternative is worse. An agent that trusts an invented API and calls a route which does not exist has been actively misled, and a specification padded out to look substantial is how that happens.

Authentication

There is none. The contact endpoint is open, and abuse is bounded rather than authenticated: a honeypot field, length and link limits, a Cloudflare Turnstile challenge, and a per-address rate limit at the edge.

The rate limit is two requests per ten seconds per IP. Exceed it and Cloudflare answers with its own block page before the request reaches the endpoint, so the response will not be in the JSON shape documented below.

One outcome, three representations

The endpoint answers in whichever form the caller can use, decided by the request headers. Send Accept: application/json, or no preference at all, and both success and failure come back as JSON. A browser posting the form natively is sent the whole failure page, because that response is the entire page the visitor is looking at. The form on the site sends X-Requested-With: fetch and gets one line of plain text plus a 204 on success, because the page it came from renders its own confirmation.

Reading the site itself

Every page serves Markdown at its own URL when the request sends Accept: text/markdown, and responds with Vary: Accept. If you would rather be explicit, append .md to the path without its trailing slash — /about.md, /work/manufacturing-erp.md.

A path that does not exist returns a real 404, not a 200 carrying the site shell, so a miss can be trusted. Ask for a type nothing here can produce and you get a 406 rather than a guess.

The endpoint

POST https://overcode.io/api/contact

Form-encoded, as application/x-www-form-urlencoded ormultipart/form-data. A JSON body is rejected withmalformed_body.

Example

curl -X POST https://overcode.io/api/contact \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "name=Aisha Rahman" \
  --data-urlencode "email=aisha@example.com" \
  --data-urlencode "message=Our sales team re-keys every WhatsApp order into the ERP by hand, roughly 60 a day, and the two disagree by the end of every week."

A successful send returns 200 with:

{
  "ok": true,
  "message": "Enquiry received. A reply will come to the address you gave."
}

Errors

Every error carries a stable error code, a human message, a hint saying what to do about it, and a documentation_url. Branch on the code, never on the message — the wording may be improved at any time and the code will not change.

{
  "error": "message_too_short",
  "message": "Please say a little more about the problem (at least 25 characters).",
  "hint": "Describe the problem in at least 25 characters. \"hi\" and \"test\" are rejected.",
  "status": 400,
  "documentation_url": "https://overcode.io/openapi.json"
}

Machine-readable files