{
  "openapi": "3.1.0",
  "info": {
    "title": "Overcode API",
    "version": "1.0.0",
    "summary": "The public HTTP surface of overcode.io.",
    "description": "Overcode embeds engineers in your operation, maps how the work really flows, then builds the AI agents and custom systems that streamline it.\n\nThis is a small engineering practice, not a SaaS product: the API surface is\nthe contact endpoint plus the machine-readable files that describe the site.\nThere is no authentication, no account, and no data API. If you are an agent\nlooking for one, there is not one, and the useful next step is to read\n/llms.txt and /agent-instructions.md instead.\n\nErrors are JSON whenever the request sends Accept: application/json, or sends\nno preference at all. Every error carries a stable \"error\" code to branch on,\na human \"message\", and a \"hint\" saying what to do about it.",
    "contact": {
      "name": "Overcode",
      "email": "cheefi.ng@overcode.io",
      "url": "https://overcode.io/contact/"
    },
    "license": {
      "name": "Proprietary",
      "identifier": "LicenseRef-Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://overcode.io",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "contact",
      "description": "Reaching a human at Overcode."
    },
    {
      "name": "discovery",
      "description": "Machine-readable files describing the site and this API."
    }
  ],
  "externalDocs": {
    "description": "Agent instructions: when to use Overcode and how to hand a lead over.",
    "url": "https://overcode.io/agent-instructions.md"
  },
  "paths": {
    "/api/contact": {
      "post": {
        "tags": [
          "contact"
        ],
        "operationId": "submitContactEnquiry",
        "summary": "Send an enquiry to Overcode.",
        "description": "Delivers the enquiry to the inbox and sends an acknowledgement to the\naddress given. There is no authentication; abuse is bounded by a honeypot\nfield, length and link limits, a Cloudflare Turnstile challenge, and a\nper-IP rate limit at the edge.\n\nThe body is form-encoded, not JSON. A JSON body returns malformed_body.\n\nThe success representation depends on what the caller asks for:\nAccept: application/json gets 200 with a JSON body, the on-page fetch\n(which sends X-Requested-With: fetch) gets 204, and a browser posting the\nform natively gets a 303 back to the page.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/ContactEnquiry"
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/ContactEnquiry"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Enquiry accepted. Returned when the caller accepts JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactAccepted"
                },
                "example": {
                  "ok": true,
                  "message": "Enquiry received. A reply will come to the address you gave."
                }
              }
            }
          },
          "204": {
            "description": "Enquiry accepted, no body. Returned to the on-page fetch, which renders its own confirmation."
          },
          "303": {
            "description": "Enquiry accepted. Returned to a native browser form post, redirecting to /?sent=1#contact so a refresh cannot resubmit.",
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri-reference"
                }
              }
            }
          },
          "400": {
            "description": "The submission was rejected. See \"error\" for which check failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "malformed_body": {
                    "summary": "Expected form-encoded request body.",
                    "value": {
                      "error": "malformed_body",
                      "message": "Expected form-encoded request body.",
                      "hint": "Post multipart/form-data or application/x-www-form-urlencoded. JSON bodies are not read.",
                      "status": 400,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  },
                  "missing_fields": {
                    "summary": "Name, email, and message are all required.",
                    "value": {
                      "error": "missing_fields",
                      "message": "Name, email, and message are all required.",
                      "hint": "Send all three fields with non-empty values.",
                      "status": 400,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  },
                  "invalid_email": {
                    "summary": "That email address doesn't look right.",
                    "value": {
                      "error": "invalid_email",
                      "message": "That email address doesn't look right.",
                      "hint": "Send a syntactically valid address; the reply goes to it.",
                      "status": 400,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  },
                  "message_too_long": {
                    "summary": "Message is too long (max 5000 characters).",
                    "value": {
                      "error": "message_too_long",
                      "message": "Message is too long (max 5000 characters).",
                      "hint": "Trim the message to 5000 characters or fewer.",
                      "status": 400,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  },
                  "field_too_long": {
                    "summary": "Name or email is too long.",
                    "value": {
                      "error": "field_too_long",
                      "message": "Name or email is too long.",
                      "hint": "name is capped at 200 characters, email at 320.",
                      "status": 400,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  },
                  "message_too_short": {
                    "summary": "Please say a little more about the problem (at least 25 characters).",
                    "value": {
                      "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"
                    }
                  },
                  "too_many_links": {
                    "summary": "That looks like spam. Please send it with fewer links.",
                    "value": {
                      "error": "too_many_links",
                      "message": "That looks like spam. Please send it with fewer links.",
                      "hint": "At most 2 links per message.",
                      "status": 400,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  },
                  "human_verification_failed": {
                    "summary": "Could not verify that you're human. Please reload and try again.",
                    "value": {
                      "error": "human_verification_failed",
                      "message": "Could not verify that you're human. Please reload and try again.",
                      "hint": "Solve the Cloudflare Turnstile challenge on the page and send the cf-turnstile-response token with the form.",
                      "status": 400,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Wrong method. This endpoint is POST only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "method_not_allowed": {
                    "summary": "Method not allowed.",
                    "value": {
                      "error": "method_not_allowed",
                      "message": "Method not allowed.",
                      "hint": "The contact endpoint accepts POST only.",
                      "status": 405,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  }
                }
              }
            }
          },
          "406": {
            "description": "The Accept header excludes every representation this endpoint can produce.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_acceptable": {
                    "summary": "No acceptable representation.",
                    "value": {
                      "error": "not_acceptable",
                      "message": "No acceptable representation.",
                      "hint": "Send Accept: application/json, text/plain or text/html.",
                      "status": 406,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "The mail provider failed. Nothing was delivered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "mail_send_failed": {
                    "summary": "Failed to send message. Please try again later.",
                    "value": {
                      "error": "mail_send_failed",
                      "message": "Failed to send message. Please try again later.",
                      "hint": "Nothing was delivered. Retry once, then email cheefi.ng@overcode.io instead.",
                      "status": 502,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "The mail backend is not configured. Nothing was delivered and retrying will not help.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "mail_backend_unconfigured": {
                    "summary": "Mail backend is not configured. Please try again later.",
                    "value": {
                      "error": "mail_backend_unconfigured",
                      "message": "Mail backend is not configured. Please try again later.",
                      "hint": "Nothing was sent and retrying will not help until this is fixed. Email cheefi.ng@overcode.io instead.",
                      "status": 503,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "contact"
        ],
        "operationId": "contactMethodNotAllowed",
        "summary": "Not allowed. Documented so an agent does not have to probe for it.",
        "responses": {
          "405": {
            "description": "This endpoint is POST only. The Allow header says so as well.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "method_not_allowed": {
                    "summary": "Method not allowed.",
                    "value": {
                      "error": "method_not_allowed",
                      "message": "Method not allowed.",
                      "hint": "The contact endpoint accepts POST only.",
                      "status": 405,
                      "documentation_url": "https://overcode.io/openapi.json"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "getOpenApiDocument",
        "summary": "This document.",
        "responses": {
          "200": {
            "description": "The OpenAPI 3.1 description of this API.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "getLlmsTxt",
        "summary": "Site index for language models, including when to use Overcode.",
        "responses": {
          "200": {
            "description": "llmstxt.org-format index.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-instructions.md": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "getAgentInstructions",
        "summary": "What Overcode is a fit for, what it is not, and how to hand a lead over.",
        "responses": {
          "200": {
            "description": "Markdown instructions for agents.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": [
          "discovery"
        ],
        "operationId": "getSitemap",
        "summary": "Every published page.",
        "responses": {
          "200": {
            "description": "sitemaps.org urlset.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContactEnquiry": {
        "type": "object",
        "required": [
          "name",
          "email",
          "message"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Who is writing.",
            "examples": [
              "Aisha Rahman"
            ]
          },
          "email": {
            "type": "string",
            "format": "email",
            "minLength": 1,
            "maxLength": 320,
            "description": "Where the reply goes. An acknowledgement is sent here immediately.",
            "examples": [
              "aisha@example.com"
            ]
          },
          "message": {
            "type": "string",
            "minLength": 25,
            "maxLength": 5000,
            "description": "What the sender is trying to fix. Describe the operational problem rather than the desired feature. At most 2 links.",
            "examples": [
              "Our sales team re-keys every order from WhatsApp into the ERP by hand, roughly 60 a day, and the two disagree by the end of every week."
            ]
          },
          "cf-turnstile-response": {
            "type": "string",
            "description": "Cloudflare Turnstile token from the widget on the page. Required whenever the challenge is configured; without it the submission is rejected with human_verification_failed."
          },
          "company_website": {
            "type": "string",
            "description": "Honeypot. Leave absent or empty. A non-empty value is answered as if it succeeded and nothing is sent.",
            "default": ""
          }
        }
      },
      "ContactAccepted": {
        "type": "object",
        "required": [
          "ok",
          "message"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message",
          "status"
        ],
        "description": "Every error response from this API has this shape.",
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine-readable code. Branch on this rather than on \"message\".",
            "enum": [
              "method_not_allowed",
              "not_acceptable",
              "malformed_body",
              "missing_fields",
              "invalid_email",
              "message_too_long",
              "field_too_long",
              "message_too_short",
              "too_many_links",
              "human_verification_failed",
              "mail_backend_unconfigured",
              "mail_send_failed"
            ]
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation."
          },
          "hint": {
            "type": "string",
            "description": "What to do about it."
          },
          "status": {
            "type": "integer",
            "description": "Repeats the HTTP status code."
          },
          "documentation_url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}