{"openapi":"3.1.0","info":{"title":"Earken API","version":"1.0.0","description":"AI voice interviews → structured knowledge. See /llms.txt."},"servers":[{"url":"https://app.earken.com/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"ek_live_… API key"}}},"paths":{"/me":{"get":{"summary":"Who this key belongs to, credits, templates","responses":{"200":{"description":"JSON object"}}}},"/me/webhook":{"post":{"summary":"Set or clear the webhook URL","responses":{"200":{"description":"JSON object"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"https URL, or empty to remove"}},"required":["url"],"additionalProperties":false}}}}}},"/projects":{"get":{"summary":"List projects","responses":{"200":{"description":"JSON object"}}},"post":{"summary":"Create a project (consultancy keys)","responses":{"200":{"description":"JSON object"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Project name, e.g. the organisation or the research question"},"template":{"type":"string","enum":["org-mapping","journal"],"description":"Default org-mapping"},"about":{"type":"string","description":"Background every interview should know: what the organisation does, why this project exists"},"website":{"type":"string","description":"Organisation website (optional)"},"credits":{"type":"integer","minimum":0,"description":"Credits to allocate from the consultancy pool (an interview uses ~8–15)"}},"required":["name"],"additionalProperties":false}}}}}},"/projects/{id}":{"get":{"summary":"Project status","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/projects/{id}/interviews":{"get":{"summary":"List interviews","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"campaignId","in":"query","schema":{"type":"string"}}]},"post":{"summary":"Create interviews and get links","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"people":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Full name"},"email":{"type":"string","description":"Email address"},"role":{"type":"string","description":"Job title or role (optional)"},"team":{"type":"string","description":"Team or department (optional)"}},"required":["email"],"additionalProperties":false},"minItems":1,"maxItems":25},"brief":{"type":"string","description":"What the interviews should cover and why — steers every plan. Private: interviewees never see it."},"topics":{"type":"array","items":{"type":"string"},"description":"Specific topics to include (optional)"},"note":{"type":"string","description":"Personal message shown in the invite email, if sendEmail (optional)"},"from":{"type":"string","description":"Sender name for the invite email (optional)"},"sendEmail":{"type":"boolean","description":"Have Earken email the invites too. Default false."}},"required":["people"],"additionalProperties":false}}}}}},"/projects/{id}/interviews/{iid}":{"get":{"summary":"Interview status and distillation","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"iid","in":"path","required":true,"schema":{"type":"string"}}]}},"/projects/{id}/interviews/{iid}/link":{"post":{"summary":"Fresh one-click link","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"iid","in":"path","required":true,"schema":{"type":"string"}}]}},"/projects/{id}/interviews/{iid}/transcript":{"get":{"summary":"Transcript","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"iid","in":"path","required":true,"schema":{"type":"string"}}]}},"/projects/{id}/knowledge":{"get":{"summary":"Knowledge base","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","markdown"]}},{"name":"section","in":"query","schema":{"type":"string"}}]}},"/projects/{id}/knowledge/{path}":{"get":{"summary":"One knowledge page","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"path","in":"path","required":true,"schema":{"type":"string"}}]}},"/projects/{id}/facts":{"get":{"summary":"Sourced facts","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"interviewId","in":"query","schema":{"type":"string"}}]}},"/projects/{id}/people":{"get":{"summary":"People","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/projects/{id}/suggestions":{"get":{"summary":"Who to interview next","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/projects/{id}/ask":{"post":{"summary":"Ask the knowledge base","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","description":"The question"}},"required":["question"],"additionalProperties":false}}}}}},"/projects/{id}/campaigns":{"post":{"summary":"Email a cohort (campaign)","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Campaign name"},"people":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Full name"},"email":{"type":"string","description":"Email address"},"role":{"type":"string","description":"Job title or role (optional)"},"team":{"type":"string","description":"Team or department (optional)"}},"required":["email"],"additionalProperties":false},"minItems":1,"maxItems":500},"brief":{"type":"string","description":"What every conversation should cover (private)"},"closesOn":{"type":"string","description":"Complete-by date, YYYY-MM-DD (optional)"},"from":{"type":"string","description":"Sender name in the emails (optional)"},"note":{"type":"string","description":"Personal message in every email (optional)"},"autoRemind":{"type":"boolean","description":"Remind people who haven't started (default true)"}},"required":["name","people"],"additionalProperties":false}}}}}},"/projects/{id}/maps":{"get":{"summary":"List process maps","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}]}},"/projects/{id}/maps/{slug}":{"get":{"summary":"Read a process map","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","markdown"]}}]},"put":{"summary":"Create or replace a process map (consultancy keys)","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The map, format process-map/1 (see /llms.txt § Process maps). Max 2 MB."}}}}},"delete":{"summary":"Delete a process map (consultancy keys)","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}]}},"/projects/{id}/campaigns/{cid}":{"get":{"summary":"Campaign progress","responses":{"200":{"description":"JSON object"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"cid","in":"path","required":true,"schema":{"type":"string"}}]}}}}