{"openapi":"3.1.0","info":{"title":"Growth.Talent API","version":"1.1.0","description":"The first agent-native job platform for growth marketing. Public read-only endpoints (jobs, talent, companies) need no auth. Authenticated endpoints (me, applications, posting jobs) require a Bearer API key generated by an admin-verified member at https://www.growthtalent.org/settings/api-keys.","contact":{"name":"Growth.Talent","url":"https://www.growthtalent.org/agents"},"license":{"name":"API terms","url":"https://www.growthtalent.org/terms"}},"servers":[{"url":"https://www.growthtalent.org/api/v1"}],"security":[{},{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/health":{"get":{"summary":"Health check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/categories":{"get":{"summary":"Job category taxonomy with counts","parameters":[{"name":"market","in":"query","schema":{"type":"string","enum":["usa","france","latam"]}}],"responses":{"200":{"description":"Categories list"}}}},"/jobs":{"get":{"summary":"Search jobs","parameters":[{"name":"market","in":"query","schema":{"type":"string","enum":["usa","france","latam"]},"description":"Default: usa"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Comma-separated category slugs"},{"name":"city","in":"query","schema":{"type":"string"},"description":"Comma-separated city slugs"},{"name":"seniority","in":"query","schema":{"type":"string"},"description":"Comma-separated: JUNIOR,MID,SENIOR,LEAD,MANAGER,DIRECTOR,VP,C_LEVEL"},{"name":"contractType","in":"query","schema":{"type":"string"},"description":"FULL_TIME,PART_TIME,CONTRACT,FREELANCE,INTERNSHIP"},{"name":"remote","in":"query","schema":{"type":"boolean"}},{"name":"salaryMin","in":"query","schema":{"type":"integer"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text search across title + description + company"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":100}}],"responses":{"200":{"description":"Paginated job list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"}}}}}},"post":{"summary":"Post a new job (companies only)","description":"Requires the `jobs:post` scope on a company-owned API key. AI moderation runs server-side; jobs scoring under 7 are auto-flagged. The new job is published immediately at /{market}/{category}/{companySlug}/{slug}.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","category","applyUrl","description"],"properties":{"title":{"type":"string"},"category":{"type":"string"},"applyUrl":{"type":"string","format":"uri"},"description":{"type":"string","description":"Min 100 chars. HTML or Markdown both supported."},"seniority":{"type":"string","enum":["INTERN","JUNIOR","MID","SENIOR","LEAD","MANAGER","DIRECTOR","VP","C_LEVEL"]},"contractType":{"type":"string","enum":["FULL_TIME","PART_TIME","CONTRACT","FREELANCE","INTERNSHIP"]},"remote":{"type":"string","enum":["REMOTE","HYBRID","ONSITE"]},"market":{"type":"string","enum":["USA","FRANCE","LATAM"]},"city":{"type":"string"},"country":{"type":"string"},"salaryMin":{"type":"integer"},"salaryMax":{"type":"integer"},"salaryCurrency":{"type":"string"}}}}}},"responses":{"201":{"description":"Job created"},"400":{"description":"Validation error"},"403":{"description":"Requires company-owned key"},"429":{"description":"Rate limit"}}}},"/jobs/{slug}":{"get":{"summary":"Get a single job","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobFull"}}}},"404":{"description":"Not found"}}}},"/talent":{"get":{"summary":"Search talent profiles","parameters":[{"name":"seniority","in":"query","schema":{"type":"string"}},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"tool","in":"query","schema":{"type":"string"},"description":"e.g. HubSpot, Mixpanel"},{"name":"openToWork","in":"query","schema":{"type":"boolean"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":100}}],"responses":{"200":{"description":"Paginated talent list"}}}},"/talent/{slug}":{"get":{"summary":"Get a single talent profile","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Profile"},"404":{"description":"Not found"}}}},"/companies":{"get":{"summary":"Search companies hiring in growth","parameters":[{"name":"market","in":"query","schema":{"type":"string","enum":["usa","france","latam"]}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":100}}],"responses":{"200":{"description":"Paginated companies"}}}},"/companies/{slug}":{"get":{"summary":"Get a single company with open jobs","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Company"},"404":{"description":"Not found"}}}},"/auth/device":{"post":{"summary":"Start OAuth 2.0 device-code flow","description":"Returns a device_code (long secret, polled by the CLI) and an 8-character user_code (entered in a browser at /auth/device). 15-minute TTL.","responses":{"200":{"description":"Device flow initiated","content":{"application/json":{"schema":{"type":"object","properties":{"device_code":{"type":"string"},"user_code":{"type":"string","example":"WDJB-MJHT"},"verification_uri":{"type":"string","format":"uri"},"verification_uri_complete":{"type":"string","format":"uri"},"expires_in":{"type":"integer"},"interval":{"type":"integer"}}}}}}}}},"/auth/device/poll":{"post":{"summary":"Poll for the issued API key after the user authorizes the device","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["device_code"],"properties":{"device_code":{"type":"string"}}}}}},"responses":{"200":{"description":"Issued","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","example":"gt_live_..."},"token_type":{"type":"string","example":"Bearer"},"scope":{"type":"string","example":"jobs:read jobs:apply me:read me:write"}}}}}},"400":{"description":"Pending or rejected. error in {authorization_pending, expired_token, access_denied, invalid_grant, already_issued}."},"403":{"description":"Account not yet verified by an admin."}}}},"/me":{"get":{"summary":"Whoami — return current candidate or company","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Current account info, scopes, rate-limit remaining."},"401":{"description":"Missing or invalid API key"},"403":{"description":"Scope or rate-limit error"}}}},"/me/applications":{"get":{"summary":"List applications submitted by the authenticated candidate","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":100}}],"responses":{"200":{"description":"Paginated applications"}}}},"/applications":{"post":{"summary":"Apply to a job on behalf of the authenticated candidate","description":"Requires the `jobs:apply` scope. If `via=magic` and the company has a contact email, the company receives a direct email with the candidate's profile and message; otherwise the application is recorded as `external` and the agent should also direct the user to `applyUrl`.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jobSlugOrId"],"properties":{"jobSlugOrId":{"type":"string","description":"Job slug or id (slugs are stable; prefer them)."},"message":{"type":"string","description":"Cover note. Required for magic apply."},"via":{"type":"string","enum":["magic","external"]}}}}}},"responses":{"201":{"description":"Application created (or upserted)"},"400":{"description":"Missing job"},"403":{"description":"Wrong scope or banned account"},"404":{"description":"Job not found / not approved"},"429":{"description":"Rate limit (5/min, 100/day for jobs:apply)"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Send `Authorization: Bearer gt_live_...`. Generate a key at https://www.growthtalent.org/settings/api-keys. Verified members only."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative to Bearer — same key value."}},"schemas":{"Health":{"type":"object","properties":{"status":{"type":"string"},"api":{"type":"string"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"JobShort":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"seniority":{"type":"string"},"contractType":{"type":"string"},"remote":{"type":"string"},"city":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"salary":{"type":"object","nullable":true,"properties":{"min":{"type":"integer"},"max":{"type":"integer"},"currency":{"type":"string"}}},"market":{"type":"string"},"postedAt":{"type":"string","format":"date-time"},"isBoosted":{"type":"boolean"},"company":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"logoUrl":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true}}},"url":{"type":"string","format":"uri"}}},"JobFull":{"allOf":[{"$ref":"#/components/schemas/JobShort"},{"type":"object","properties":{"description":{"type":"string","nullable":true},"applyUrl":{"type":"string","format":"uri","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true}}}]},"JobList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JobShort"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}