{"openapi":"3.0.3","info":{"title":"Otter API","version":"0.2.0","description":"Multi-tenant ATS API for Otter (otter.diy). Authenticate with a workspace API key (Authorization: Bearer otter_sk_…) created in Settings → API keys. Keys are bound to one workspace, hashed at rest, and can be read-only or read & write. Requires Growth+ (api_access).","contact":{"url":"https://otter.diy/docs"}},"servers":[{"url":"https://app.otter.diy/api/v1","description":"Production"},{"url":"/api/v1","description":"Current deployment"}],"tags":[{"name":"Meta"},{"name":"Jobs"},{"name":"Candidates"},{"name":"Applications"},{"name":"Interviews"},{"name":"Notes"}],"paths":{"/":{"get":{"tags":["Meta"],"summary":"API root / capability discovery","responses":{"200":{"description":"Discovery payload"}}}},"/jobs":{"get":{"tags":["Jobs"],"summary":"List jobs","description":"Returns jobs for the authenticated tenant (DB-backed). Requires Growth+.","security":[{"bearerAuth":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated job list"},"401":{"description":"Unauthorized"},"403":{"description":"Plan does not include api_access"}}}},"/jobs/{id}":{"get":{"tags":["Jobs"],"summary":"Get a job","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job"},"404":{"description":"Not found"}}}},"/candidates":{"get":{"tags":["Candidates"],"summary":"List or search candidates","description":"Pass `q` for free-text search (name, email, headline, company). DB-backed. Requires Growth+.","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query"},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated candidates"}}}},"/candidates/{id}":{"get":{"tags":["Candidates"],"summary":"Get a candidate","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Candidate"},"404":{"description":"Not found"}}}},"/applications":{"get":{"tags":["Applications"],"summary":"List applications","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Paginated applications"}}}},"/applications/{id}":{"get":{"tags":["Applications"],"summary":"Get an application","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Application"}}}},"/interviews":{"get":{"tags":["Interviews"],"summary":"List interviews","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Paginated interviews"}}}},"/notes":{"get":{"tags":["Notes"],"summary":"List notes","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Paginated notes"}}},"post":{"tags":["Notes"],"summary":"Create a note","description":"Attach a note to a candidate (optionally tied to an application). Requires a read & write key. The note is authored by the key's creator and appears on the candidate timeline.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":8000},"candidate_id":{"type":"string","format":"uuid"},"application_id":{"type":"string","format":"uuid"},"visibility":{"type":"string","enum":["team","hiring_team"],"default":"team"}}}}}},"responses":{"201":{"description":"Created note"},"400":{"description":"Validation error"},"403":{"description":"Read-only key or plan without API access"},"404":{"description":"Candidate or application not found in this workspace"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Workspace API key (otter_sk_…). Optional X-Otter-Tenant must match the key's workspace if sent."}}},"security":[{"bearerAuth":[]}]}