{"openapi":"3.1.0","info":{"title":"contactme.co for agents","version":"1.0.0","summary":"Make someone a contact page with a link.","description":"No account, key or tool is needed. Build a /new link with the person's name and links in it and hand it over. Nothing is created until they open it, choose a handle and sign in; then the page is live with the draft applied. If a request here fails, build the link anyway — the page checks the handle itself when it opens."},"servers":[{"url":"https://contactme.co"}],"paths":{"/api/handle/{handle}":{"get":{"operationId":"checkHandleByPath","summary":"Is this handle free? (handle in the path)","description":"Same answer as /api/handle?h=…, with the handle in the path so a fetcher that drops query strings cannot lose it. Prefer this form.","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":30,"pattern":"^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$"}}],"responses":{"200":{"description":"The verdict, with alternatives when it is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandleVerdict"}}}}}}},"/api/handle":{"get":{"operationId":"checkHandle","summary":"Is this handle free?","description":"Same answer the claim box gives, as JSON. Optional: a taken handle costs the person one keystroke on the page, so skip this if you cannot fetch.","parameters":[{"name":"h","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":30,"pattern":"^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$"}}],"responses":{"200":{"description":"The verdict, with alternatives when it is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandleVerdict"}}}}}}},"/new":{"get":{"operationId":"draftPage","summary":"A page drafted for someone, ready to claim.","description":"Renders a live preview of the page with the handle box underneath. Not an API call to make yourself: build this URL and give it to the person. At least one of name, headline, bio or link is required, or the page shows the instructions instead. Do not put an email address or phone number in the bio; the contact form is what a page is for.","parameters":[{"name":"handle","in":"query","schema":{"type":"string","minLength":2,"maxLength":30,"pattern":"^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$"},"description":"A suggestion. If it is taken, the person is offered alternatives on the page."},{"name":"name","in":"query","schema":{"type":"string","maxLength":80,"description":"Their name. Longer text is cut to 80 characters, not refused."}},{"name":"headline","in":"query","schema":{"type":"string","maxLength":120,"description":"What they do, in a line. Longer text is cut to 120 characters, not refused."}},{"name":"bio","in":"query","schema":{"type":"string","maxLength":240,"description":"A short bio. Longer text is cut to 240 characters, not refused."}},{"name":"location","in":"query","schema":{"type":"string","maxLength":80,"description":"Where they are. Longer text is cut to 80 characters, not refused."}},{"name":"link","in":"query","style":"form","explode":true,"schema":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":500}},"description":"Repeat the parameter for each link. A URL, or \"Label|URL\" to name it. Provider, icon and a sensible label are detected from the URL."},{"name":"avatar","in":"query","schema":{"type":"string","format":"uri","maxLength":500},"description":"An https URL of a photo. Copied to our storage on claim."},{"name":"theme","in":"query","schema":{"type":"string","enum":["paper","midnight","mono","sage","ember","cobalt","plum","forest","sand","noir"],"description":"Colour theme. An unknown value is ignored."}},{"name":"font","in":"query","schema":{"type":"string","enum":["sans","serif","mono"],"description":"Typeface. An unknown value is ignored."}},{"name":"layout","in":"query","schema":{"type":"string","enum":["card","minimal","hero"],"description":"Page layout. An unknown value is ignored."}},{"name":"surface","in":"query","schema":{"type":"string","enum":["solid","glow","dots","grid","mesh","rays","grain","stripes","topo","scanlines","nodes","circuit"],"description":"Background treatment. An unknown value is ignored."}},{"name":"accent","in":"query","schema":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"description":"Accent colour, #rrggbb."},{"name":"via","in":"query","schema":{"type":"string","maxLength":30},"description":"Always include this. Your name, lowercase (claude, chatgpt, gemini, cursor…). The only thing in the link that says an assistant built it. Nothing about the person is recorded."}],"responses":{"200":{"description":"The preview page. The person claims a handle from it; the draft expires 48 hours after it was last opened.","content":{"text/html":{}}}}}}},"components":{"schemas":{"HandleVerdict":{"type":"object","required":["handle","status","suggestions"],"properties":{"handle":{"type":"string"},"status":{"type":"string","enum":["available","taken","reserved","invalid"]},"suggestions":{"type":"array","items":{"type":"string"}}}}}}}