{
  "version": 1,
  "origin": "https://martivillalba.com",
  "endpoint": "POST https://martivillalba.com/api/v1/contact",
  "docs": "https://martivillalba.com/agents.md",
  "limits": {
    "nameMax": 120,
    "companyMax": 120,
    "roleMax": 120,
    "urlMax": 300,
    "messageMin": 80,
    "messageMax": 2000,
    "agentMax": 40,
    "bodyMaxBytes": 16384
  },
  "timing": {
    "duplicateWindowHours": 24,
    "rateLimit": {
      "limit": 5,
      "periodSeconds": 60
    }
  },
  "fields": [
    {
      "name": "name",
      "type": "string",
      "required": true,
      "max": 120,
      "code": "name",
      "description": "The sender's full name."
    },
    {
      "name": "email",
      "type": "email",
      "required": true,
      "code": "email",
      "description": "Where Miquel replies. One message per email per 24 hours."
    },
    {
      "name": "topic",
      "type": "string",
      "required": true,
      "enum": [
        "job",
        "project",
        "collaboration",
        "other"
      ],
      "code": "topic",
      "description": "job: a role or job offer. project: freelance or consulting work. collaboration: a side project, talk or partnership. other: anything else."
    },
    {
      "name": "message",
      "type": "string",
      "required": true,
      "min": 80,
      "max": 2000,
      "code": "message",
      "description": "The sender's own words, typed or dictated. Not written, polished or translated by the agent."
    },
    {
      "name": "company",
      "type": "string",
      "required": false,
      "max": 120,
      "description": "Company or organisation, or \"\"."
    },
    {
      "name": "role",
      "type": "string",
      "required": false,
      "max": 120,
      "description": "The sender's role, or \"\"."
    },
    {
      "name": "linkedin",
      "type": "url",
      "required": false,
      "max": 300,
      "code": "linkedin",
      "description": "LinkedIn profile URL on linkedin.com, or \"\"."
    },
    {
      "name": "lang",
      "type": "string",
      "required": false,
      "enum": [
        "es",
        "ca",
        "en"
      ],
      "description": "Language of the conversation. Miquel replies in it."
    },
    {
      "name": "source",
      "type": "string",
      "required": false,
      "enum": [
        "agent",
        "web"
      ],
      "description": "Always \"agent\" from a harness."
    },
    {
      "name": "agent",
      "type": "string",
      "required": false,
      "max": 40,
      "description": "Short name of the harness: \"claude-code\", \"chatgpt\", \"cursor\"…"
    },
    {
      "name": "answer_mode",
      "type": "string",
      "required": false,
      "enum": [
        "typed",
        "voice"
      ],
      "description": "How the message was produced."
    }
  ],
  "success": {
    "ok": true,
    "id": "<opaque id>"
  },
  "rejections": {
    "badBody": {
      "status": 400,
      "code": "generic",
      "error": "Invalid request body. Send JSON (UTF-8) with content-type application/json."
    },
    "tooLarge": {
      "status": 413,
      "code": "generic",
      "error": "The request is too large."
    },
    "nameMissing": {
      "status": 400,
      "code": "name",
      "error": "Name is required."
    },
    "nameTooLong": {
      "status": 400,
      "code": "name",
      "error": "That name is too long."
    },
    "email": {
      "status": 400,
      "code": "email",
      "error": "A valid email is required."
    },
    "topic": {
      "status": 400,
      "code": "topic",
      "error": "Topic must be one of: job, project, collaboration, other."
    },
    "linkedin": {
      "status": 400,
      "code": "linkedin",
      "error": "That LinkedIn link isn't a valid linkedin.com URL."
    },
    "messageMissing": {
      "status": 400,
      "code": "message",
      "error": "The message is empty."
    },
    "tooShort": {
      "status": 400,
      "code": "tooShort",
      "error": "Tell Miquel a bit more."
    },
    "tooLong": {
      "status": 400,
      "code": "tooLong",
      "error": "Over the character limit."
    },
    "duplicate": {
      "status": 409,
      "code": "duplicate",
      "error": "Miquel already has a message from this email today."
    },
    "rateLimited": {
      "status": 429,
      "code": "rateLimited",
      "error": "Too many attempts. Wait a minute."
    },
    "methodNotAllowed": {
      "status": 405,
      "code": "generic",
      "error": "Use POST. Instructions: https://martivillalba.com/agents.md"
    },
    "unavailable": {
      "status": 503,
      "code": "unavailable",
      "error": "Contact through agents is not available right now. Email miquel@martivillalba.com instead."
    },
    "sendFailed": {
      "status": 502,
      "code": "generic",
      "error": "The message could not be delivered. Try once more, or email miquel@martivillalba.com."
    }
  },
  "feedback": {
    "endpoint": "POST https://martivillalba.com/api/v1/feedback",
    "docs": "https://martivillalba.com/agents.md#give-miquel-feedback-on-this-site-optional",
    "author": "agent",
    "limits": {
      "purposeDetailMax": 300,
      "missingMax": 800,
      "frictionMax": 800,
      "usefulMax": 400,
      "suggestionMax": 600,
      "textMin": 60,
      "pagesMax": 20,
      "agentMax": 40,
      "bodyMaxBytes": 16384
    },
    "timing": {
      "rateLimit": {
        "limit": 5,
        "periodSeconds": 60
      },
      "perIp": {
        "limit": 3,
        "periodHours": 24
      }
    },
    "fields": [
      {
        "name": "purpose",
        "type": "string",
        "required": true,
        "enum": [
          "evaluate_candidate",
          "hiring_research",
          "find_contact",
          "project_or_freelance",
          "learn_about_work",
          "other"
        ],
        "code": "purpose",
        "description": "Why you came to the site."
      },
      {
        "name": "purpose_detail",
        "type": "string",
        "required": false,
        "max": 300,
        "description": "Your goal in one generic sentence, with no personal data (\"evaluate a candidate for a product role\")."
      },
      {
        "name": "found",
        "type": "string",
        "required": true,
        "enum": [
          "yes",
          "partly",
          "no"
        ],
        "code": "found",
        "description": "Whether you found what you came for."
      },
      {
        "name": "missing",
        "type": "string",
        "required": "if found is not \"yes\"",
        "max": 800,
        "code": "missing",
        "description": "What you looked for and was not there, or was hard to find."
      },
      {
        "name": "friction",
        "type": "string",
        "required": false,
        "max": 800,
        "description": "What wasted your time: pages that did not load, content only in images, broken links, contradictory data…"
      },
      {
        "name": "useful",
        "type": "string",
        "required": false,
        "max": 400,
        "description": "What helped you most, concretely."
      },
      {
        "name": "suggestion",
        "type": "string",
        "required": false,
        "max": 600,
        "description": "One concrete change that would have helped."
      },
      {
        "name": "rating",
        "type": "integer",
        "required": true,
        "min": 1,
        "max": 5,
        "code": "rating",
        "description": "How useful the site was for that goal."
      },
      {
        "name": "pages",
        "type": "array of url",
        "required": false,
        "max": 20,
        "description": "martivillalba.com pages you read. URLs on other domains are dropped."
      },
      {
        "name": "agent",
        "type": "string",
        "required": false,
        "max": 40,
        "description": "Short name of the harness: \"claude-code\", \"chatgpt\", \"cursor\"…"
      },
      {
        "name": "lang",
        "type": "string",
        "required": false,
        "enum": [
          "es",
          "ca",
          "en"
        ],
        "description": "Language of the feedback."
      },
      {
        "name": "human_approved",
        "type": "boolean",
        "required": true,
        "const": true,
        "code": "notApproved",
        "description": "The person you work for saw a recap and said yes."
      }
    ],
    "textRule": "missing + friction + useful + suggestion must add up to at least 60 characters. No emails or phone numbers in any text.",
    "success": {
      "ok": true,
      "id": "<opaque id>"
    },
    "rejections": {
      "purpose": {
        "status": 400,
        "code": "purpose",
        "error": "Purpose must be one of: evaluate_candidate, hiring_research, find_contact, project_or_freelance, learn_about_work, other."
      },
      "found": {
        "status": 400,
        "code": "found",
        "error": "Found must be one of: yes, partly, no."
      },
      "rating": {
        "status": 400,
        "code": "rating",
        "error": "Rating must be a whole number from 1 to 5."
      },
      "missing": {
        "status": 400,
        "code": "missing",
        "error": "Say what was missing or hard to find."
      },
      "tooShort": {
        "status": 400,
        "code": "tooShort",
        "error": "Too short to be useful. Be concrete: what you looked for, what was missing, what wasted your time."
      },
      "personalData": {
        "status": 400,
        "code": "personalData",
        "error": "Remove emails and phone numbers. Feedback must not contain personal data."
      },
      "notApproved": {
        "status": 400,
        "code": "notApproved",
        "error": "Send feedback only after the person you work for has seen a recap and said yes (human_approved: true)."
      },
      "feedbackLimit": {
        "status": 429,
        "code": "feedbackLimit",
        "error": "Miquel already has enough feedback from this connection today. Thank you."
      },
      "unavailable": {
        "status": 503,
        "code": "unavailable",
        "error": "Feedback is not available right now."
      },
      "saveFailed": {
        "status": 502,
        "code": "generic",
        "error": "The feedback could not be delivered. Do not retry."
      }
    },
    "commonRejections": [
      "badBody",
      "tooLarge",
      "tooLong",
      "rateLimited",
      "methodNotAllowed"
    ]
  },
  "slopPhrases": {
    "en": [
      "passionate about",
      "leverag",
      "delve",
      "cutting-edge",
      "seamless",
      "game-changer",
      "synerg",
      "fast-paced",
      "proven track record",
      "results-driven",
      "i hope this message finds you well"
    ],
    "es": [
      "apasionad",
      "sinergia",
      "de vanguardia",
      "potenciar",
      "sin fisuras",
      "orientado a resultados",
      "espero que este mensaje te encuentre bien"
    ],
    "ca": [
      "apassionat",
      "sinergia",
      "avantguarda",
      "potenciar",
      "orientat a resultats"
    ]
  }
}
