{"openapi":"3.0.3","info":{"title":"Cavuno v1 REST API","version":"1.0.0","description":"The Cavuno API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n## Base URL\n\nProduction: `https://api.cavuno.com/v1`\n\nAll API requests must be made over HTTPS. Calls made over plain HTTP will fail.\n\n## Authentication\n\nThe Cavuno API uses API keys to authenticate requests. You can view and manage your API keys in the Cavuno dashboard, under Settings → API keys.\n\nCavuno API keys have the prefix `cavuno_live_`. Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.\n\nAuthentication to the API is performed via Bearer auth. Provide your API key as the bearer token in the `Authorization` header:\n\n```bash\ncurl https://api.cavuno.com/v1/jobs \\\n  -H \"Authorization: Bearer cavuno_live_a1b2c3d4e5f6g7h8_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n```\n\nAPI requests without authentication will fail.\n\n## Rate limits\n\nThe Cavuno API has rate limits in place to ensure stability and reliability. By default, API keys are limited to 100 requests per minute. If you exceed your limit, requests return an HTTP 429 response with a `Retry-After` header indicating when you can try again.\n\nIf you have a use case that needs a higher limit, contact support.\n\n## Idempotency\n\nThe API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a job fails due to a network connection error, you can safely retry the request with the same idempotency key, and we'll guarantee that only one job is created.\n\nTo perform an idempotent request, provide an additional `Idempotency-Key` header on any `POST`, `PATCH`, or `DELETE` request:\n\n```bash\ncurl https://api.cavuno.com/v1/jobs \\\n  -X POST \\\n  -H \"Authorization: Bearer cavuno_live_...\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"title\": \"Senior Engineer\" }'\n```\n\n## Errors\n\nCavuno uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the `5xx` range indicate an error with Cavuno's servers (these are rare).\n\nError responses include a JSON body with details:\n\n```json\n{\n  \"error\": {\n    \"type\": \"validation_error\",\n    \"message\": \"Field 'title' is required.\",\n    \"param\": \"title\",\n    \"requestId\": \"req_...\"\n  }\n}\n```\n\nWhen contacting support about a failed request, include the `requestId` value — it's the fastest way for us to find your request in our logs.\n"},"servers":[{"url":"https://api.cavuno.com/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"API keys","description":"Manage your API keys."},{"name":"Jobs","description":"Create, list, update, and publish jobs."},{"name":"Usage","description":"Your account's current usage and plan limits."},{"name":"Companies","description":"Create, list, update, and delete companies attached to jobs."},{"name":"Media","description":"Upload and manage logos and other binary assets.","x-internal":true},{"name":"Settings","description":"Read and update your board settings.","x-internal":true},{"name":"Audit logs","description":"Read your account audit-log entries.","x-internal":true},{"name":"Operations","description":"Track long-running asynchronous operations.","x-internal":true},{"name":"OAuth","description":"OAuth 2.0 authorization, token, and revocation endpoints.","x-internal":true},{"name":"Public boards","description":"Read-only endpoints for public job boards.","x-internal":true}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"cavuno_live_<keyId>_<secret>","description":"Use your secret API key to authenticate. Pass it as a Bearer token in the `Authorization` header. You can view and manage your API keys in the Cavuno dashboard."}},"schemas":{"ApiKey":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the object."},"object":{"type":"string","enum":["api_key"],"description":"String representing the object's type. Objects of the same type share the same value."},"keyId":{"type":"string","description":"Public key ID component, embedded in the key prefix as `cavuno_live_<keyId>_`."},"name":{"type":"string","description":"Human-readable name for the key, shown in the dashboard."},"prefix":{"type":"string","description":"Public prefix in the form `cavuno_live_<keyId>_`. Safe to log; the full plaintext secret is never returned by the API."},"createdAt":{"type":"number","description":"Time at which the key was created. Unix epoch in milliseconds."},"createdBy":{"type":"string","description":"Identifier of the user who minted the key."},"lastUsedAt":{"type":"number","nullable":true,"description":"Time at which the key was last used to authenticate a request, or `null` if it has never been used. Unix epoch in milliseconds."},"revokedAt":{"type":"number","nullable":true,"description":"Time at which the key was revoked, or `null` if the key is still active. Unix epoch in milliseconds."},"expiresAt":{"type":"number","nullable":true,"description":"Time at which the key expires, or `null` if the key has no expiry. Unix epoch in milliseconds."}},"required":["id","object","keyId","name","prefix","createdAt","createdBy","lastUsedAt","revokedAt","expiresAt"]},"AuditLogEntry":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the object."},"object":{"type":"string","enum":["audit_log"],"description":"String representing the object's type. Objects of the same type share the same value."},"accountId":{"type":"string","description":"Identifier of the account the entry belongs to."},"actorType":{"type":"string","enum":["api_key","oauth_token","user_session","system"],"description":"Type of actor that performed the action."},"actorId":{"type":"string","description":"Identifier of the actor that performed the action."},"actorLabel":{"type":"string","description":"Human-readable label for the actor, suitable for display."},"action":{"type":"string","description":"Action that was performed (e.g. `jobs.create`, `companies.update`)."},"resourceType":{"type":"string","description":"Type of resource the action was performed on."},"resourceId":{"type":"string","nullable":true,"description":"Identifier of the resource the action was performed on, or `null` for resource-less actions."},"before":{"type":"string","nullable":true,"description":"Serialized JSON snapshot of the resource before the action, or `null` for create actions."},"after":{"type":"string","nullable":true,"description":"Serialized JSON snapshot of the resource after the action, or `null` for delete actions."},"metadata":{"type":"string","nullable":true,"description":"Serialized JSON of free-form metadata about the action (e.g. truncation byte sizes), or `null` if none was attached."},"ipAddress":{"type":"string","nullable":true,"description":"IP address the request originated from, or `null` if unavailable."},"userAgent":{"type":"string","nullable":true,"description":"User-agent string from the request, or `null` if unavailable."},"requestId":{"type":"string","description":"Identifier of the request that produced the entry. Use this to correlate with platform logs."},"timestamp":{"type":"number","description":"Time at which the audit entry was written. Unix epoch in milliseconds."}},"required":["id","object","accountId","actorType","actorId","actorLabel","action","resourceType","resourceId","before","after","metadata","ipAddress","userAgent","requestId","timestamp"],"x-internal":true},"ResourceLinks":{"type":"object","properties":{"public":{"type":"string","format":"uri","description":"Canonical public URL for this resource on the board. Honours the configured custom domain when present, otherwise uses the board subdomain."},"admin":{"type":"string","format":"uri","description":"URL inside the Cavuno app where the authenticated owner can manage this resource."}},"required":["public","admin"]},"CompanySummary":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the object."},"object":{"type":"string","enum":["company"],"description":"String representing the object's type. Objects of the same type share the same value."},"name":{"type":"string","description":"Display name of the company."},"slug":{"type":"string","description":"URL-friendly slug for the company."},"website":{"type":"string","nullable":true,"description":"Public company website URL, or `null` if not set."},"logoUrl":{"type":"string","nullable":true,"description":"URL of the company logo, or `null` if no logo is set."},"summary":{"type":"string","nullable":true,"description":"One-line summary of the company, or `null` if not set."},"xUrl":{"type":"string","nullable":true,"description":"X (Twitter) profile URL, or `null` if not set."},"linkedinUrl":{"type":"string","nullable":true,"description":"LinkedIn page URL, or `null` if not set."},"facebookUrl":{"type":"string","nullable":true,"description":"Facebook page URL, or `null` if not set."},"createdAt":{"type":"string","description":"Time at which the company was created. ISO 8601 datetime."},"updatedAt":{"type":"string","nullable":true,"description":"Time at which the company was last updated, or `null` if it has never been updated. ISO 8601 datetime."},"links":{"allOf":[{"$ref":"#/components/schemas/ResourceLinks"},{"type":"object","properties":{"public":{"type":"string","nullable":true,"format":"uri","description":"Canonical public URL for this company on the board, or `null` when no slug is set."}}}],"description":"Public + admin URLs for this company. `public` may be `null` if the company lacks a slug."}},"required":["id","object","name","slug","website","logoUrl","summary","xUrl","linkedinUrl","facebookUrl","createdAt","updatedAt","links"]},"Company":{"allOf":[{"$ref":"#/components/schemas/CompanySummary"},{"type":"object","properties":{"description":{"type":"string","nullable":true,"description":"Long-form description of the company, or `null` if not set."},"canBackfill":{"type":"boolean","nullable":true,"description":"Whether automated backfill of jobs from this company is supported, or `null` if not yet evaluated."},"jobCount":{"type":"number","description":"Total number of jobs at this company across all statuses."},"publishedJobCount":{"type":"number","description":"Number of currently-published jobs at this company."}},"required":["description","canBackfill","jobCount","publishedJobCount"]}]},"CreateCompanyBody":{"type":"object","properties":{"website":{"type":"string","maxLength":200,"description":"Public company website URL. Normalized to a canonical apex domain when stored."},"summary":{"type":"string","maxLength":280,"description":"One-line summary of the company. Up to 280 characters."},"description":{"type":"string","maxLength":25000,"description":"Long-form description of the company. Up to 25,000 characters."},"xUrl":{"type":"string","maxLength":500,"description":"X (Twitter) profile URL or handle. Stored as the canonical handle."},"linkedinUrl":{"type":"string","maxLength":500,"description":"LinkedIn company page URL."},"facebookUrl":{"type":"string","maxLength":500,"description":"Facebook company page URL."},"name":{"type":"string","minLength":1,"maxLength":120,"description":"The company's display name."},"slug":{"type":"string","minLength":1,"maxLength":150,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"URL-friendly slug for the company. Auto-generated from `name` when omitted."}},"required":["name"],"additionalProperties":false},"FindOrCreateCompanyBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"The company's display name."},"website":{"type":"string","maxLength":200,"description":"Public company website URL. Used to resolve to an existing company by domain before falling back to creation."},"summary":{"type":"string","maxLength":280,"description":"One-line summary of the company. Up to 280 characters."}},"required":["name"],"additionalProperties":false},"UpdateCompanyBody":{"type":"object","properties":{"website":{"type":"string","maxLength":200,"description":"Public company website URL. Normalized to a canonical apex domain when stored."},"summary":{"type":"string","maxLength":280,"description":"One-line summary of the company. Up to 280 characters."},"description":{"type":"string","maxLength":25000,"description":"Long-form description of the company. Up to 25,000 characters."},"xUrl":{"type":"string","maxLength":500,"description":"X (Twitter) profile URL or handle. Stored as the canonical handle."},"linkedinUrl":{"type":"string","maxLength":500,"description":"LinkedIn company page URL."},"facebookUrl":{"type":"string","maxLength":500,"description":"Facebook company page URL."},"name":{"type":"string","minLength":1,"maxLength":120,"description":"The company's display name."},"slug":{"type":"string","minLength":1,"maxLength":150,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"URL-friendly slug for the company."}},"additionalProperties":false},"SearchCompaniesBody":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"Free-text search query matched against company name. Up to 200 characters."},"cursor":{"type":"string","nullable":true,"minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100.","example":20}},"additionalProperties":false},"CompaniesBatchRequest":{"type":"object","properties":{"operations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"method":{"type":"string","enum":["POST"]},"body":{"nullable":true},"action":{"type":"string"},"resourceId":{"type":"string"}},"required":["id","method"]},{"type":"object","properties":{"id":{"type":"string","minLength":1},"method":{"type":"string","enum":["PATCH"]},"body":{"nullable":true},"resourceId":{"type":"string","minLength":1}},"required":["id","method","resourceId"]},{"type":"object","properties":{"id":{"type":"string","minLength":1},"method":{"type":"string","enum":["DELETE"]},"resourceId":{"type":"string","minLength":1}},"required":["id","method","resourceId"]}]},"minItems":1,"maxItems":100,"description":"Array of sub-operations to execute. Each entry runs independently and reports its result on the corresponding entry of the response `data` array. Sub-operation `id` values must be unique within the batch. Up to 100 entries."}},"required":["operations"],"additionalProperties":false},"AdminOnlyResourceLinks":{"type":"object","properties":{"admin":{"type":"string","format":"uri","description":"URL inside the Cavuno app where the authenticated owner can manage this resource."}},"required":["admin"],"description":"Links related to this resource. List responses only carry the `admin` URL because the public URL needs the company slug, which list-shape Convex projections do not fan out to."},"JobSummary":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the object."},"object":{"type":"string","enum":["job"],"description":"String representing the object's type. Objects of the same type share the same value."},"title":{"type":"string","description":"The job title."},"slug":{"type":"string","nullable":true,"description":"URL-friendly slug used in public board URLs, or `null` if no slug is set."},"status":{"type":"string","enum":["draft","published","expired","archived"],"description":"Current status of the job. One of `draft`, `published`, `expired`, or `archived`."},"companyId":{"type":"string","nullable":true,"description":"Identifier of the company the job belongs to, or `null` if no company is attached."},"employmentType":{"type":"string","nullable":true,"enum":["full_time","part_time","contract","internship","temporary","volunteer","other"],"description":"Employment type of the role, or `null` if not specified."},"remoteOption":{"type":"string","nullable":true,"enum":["on_site","hybrid","remote"],"description":"Whether the role is on-site, hybrid, or fully remote, or `null` if not specified."},"seniority":{"type":"string","nullable":true,"enum":["entry_level","associate","mid_level","senior","lead","principal","director","executive"],"description":"Seniority level of the role, or `null` if not specified."},"salaryMin":{"type":"number","nullable":true,"description":"Minimum salary in `salaryCurrency` units, or `null` if not specified."},"salaryMax":{"type":"number","nullable":true,"description":"Maximum salary in `salaryCurrency` units, or `null` if not specified."},"salaryCurrency":{"type":"string","nullable":true,"description":"Three-letter ISO 4217 currency code for the salary range, or `null` if no salary is specified."},"salaryTimeframe":{"type":"string","nullable":true,"enum":["per_year","per_month","per_week","per_day","per_hour"],"description":"Period the salary range is quoted against, or `null` if no salary is specified."},"isFeatured":{"type":"boolean","description":"Whether the job appears in featured slots on the public board."},"publishedAt":{"type":"string","nullable":true,"description":"Time at which the job was first published, or `null` if not yet published. ISO 8601 datetime."},"expiresAt":{"type":"string","nullable":true,"description":"Time at which the job expires, or `null` if no expiry is set. ISO 8601 datetime."},"createdAt":{"type":"string","description":"Time at which the job was created. ISO 8601 datetime."},"updatedAt":{"type":"string","description":"Time at which the job was last updated. ISO 8601 datetime."},"links":{"$ref":"#/components/schemas/AdminOnlyResourceLinks"}},"required":["id","object","title","slug","status","companyId","employmentType","remoteOption","seniority","salaryMin","salaryMax","salaryCurrency","salaryTimeframe","isFeatured","publishedAt","expiresAt","createdAt","updatedAt","links"]},"JobCompany":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Unique identifier for the company."},"name":{"type":"string","nullable":true,"description":"Display name of the company, or `null` if not yet set."},"slug":{"type":"string","nullable":true,"description":"URL slug of the company, or `null` if not yet set."},"logoUrl":{"type":"string","nullable":true,"description":"URL of the company logo, or `null` if no logo is set."},"website":{"type":"string","nullable":true,"description":"Company website URL, or `null` if no website is set."}},"required":["id","name","slug","logoUrl","website"],"description":"Embedded company resource for the job, or `null` if no company is attached."},"JobOfficeLocation":{"type":"object","properties":{"countryCode":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2 country code, or `null` if the location was not resolved."},"country":{"type":"string","nullable":true,"description":"Full country name, or `null` if the location was not resolved."},"locality":{"type":"string","nullable":true,"description":"Neighborhood or sub-locality, or `null` if not resolved."},"city":{"type":"string","nullable":true,"description":"City, or `null` if not resolved."},"region":{"type":"string","nullable":true,"description":"Region, state, or province name, or `null` if not resolved."},"regionCode":{"type":"string","nullable":true,"description":"Region or state code (e.g. `CA` for California), or `null` if not resolved."},"displayName":{"type":"string","nullable":true,"description":"Pre-formatted display name for the location, or `null` if not resolved."}},"required":["countryCode","country","locality","city","region","regionCode","displayName"]},"Job":{"allOf":[{"$ref":"#/components/schemas/JobSummary"},{"type":"object","properties":{"links":{"allOf":[{"$ref":"#/components/schemas/ResourceLinks"},{"type":"object","properties":{"public":{"type":"string","nullable":true,"format":"uri","description":"Canonical public URL for this job, or `null` when the job has no slug or no associated company slug (so a stable URL cannot be assembled)."}}}],"description":"Public + admin URLs for this job. `public` may be `null` if the job lacks a slug or company-slug."},"description":{"type":"string","nullable":true,"description":"Long-form description of the role, or `null` if not specified."},"applicationUrl":{"type":"string","nullable":true,"description":"Where candidates apply, or `null` if not specified. An HTTPS URL or `mailto:` URI."},"remotePermits":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"]},"description":"Hierarchical permit selection authored by the caller. Lossless round-trip with the input — `[{type:\"world_region\",value:\"EMEA\"}]` goes in and comes out the same. The three `remoteWorkPermit*` and `remoteWorldwide` fields below are read-only derived projections of this list."},"remoteWorldwide":{"type":"boolean","nullable":true,"description":"Read-only — derived from `remotePermits`. `true` only when the authored selection is a single `{type:\"worldwide\"}` entry."},"remoteTimezones":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"plusMinus":{"type":"number"}},"required":["type","value"]},"description":"Hierarchical timezone selection. Lossless round-trip with the authored input. When omitted on POST, the server auto-derives this from `remotePermits` (or `[{all,all}]` if neither was provided). PATCH never auto-re-derives — once set, only an explicit replacement updates the stored value. The flat `remoteAllowedTzOffsets` field below is the read-only derived projection used by search."},"remoteAllowedTzOffsets":{"type":"array","items":{"type":"number"},"description":"Read-only — derived from `remoteTimezones` (per-country/per-region offset fan-out). UTC hour offsets used by the job-search index."},"remoteWorkPermitCountryCodes":{"type":"array","items":{"type":"string"},"description":"Read-only — derived from `remotePermits` (hierarchical groups fan out to alpha2 sets; subdivisions auto-add the parent country). ISO 3166-1 alpha-2 codes."},"remoteWorkPermitSubdivisionCodes":{"type":"array","items":{"type":"string"},"description":"Read-only — derived from `remotePermits` (subdivision entries only). ISO 3166-2 codes."},"remoteSponsorship":{"type":"string","enum":["yes","no","unknown"],"description":"Whether the employer sponsors visas for remote candidates. One of `yes`, `no`, or `unknown`."},"educationRequirements":{"type":"array","items":{"type":"string","enum":["high_school","associate_degree","bachelor_degree","professional_certificate","postgraduate_degree","no_requirements"]},"description":"Required education credentials. Each value is one of `high_school`, `associate_degree`, `bachelor_degree`, `professional_certificate`, `postgraduate_degree`, or `no_requirements`."},"experienceMonths":{"type":"number","nullable":true,"description":"Minimum required experience in months, or `null` if not specified."},"experienceInPlaceOfEducation":{"type":"boolean","nullable":true,"description":"If `true`, equivalent experience may substitute for the listed education requirements. `null` if not specified."},"inOfficePeriod":{"type":"string","nullable":true,"enum":["per_week","per_month","per_year"],"description":"Period denominator for `inOfficeFrequency`, or `null` if not specified."},"inOfficeFrequency":{"type":"number","nullable":true,"description":"How often the candidate must be in-office over `inOfficePeriod`, or `null` if not specified."},"company":{"$ref":"#/components/schemas/JobCompany"},"officeLocations":{"type":"array","items":{"$ref":"#/components/schemas/JobOfficeLocation"},"description":"Physical office locations associated with the job."}},"required":["description","applicationUrl","remotePermits","remoteWorldwide","remoteTimezones","remoteAllowedTzOffsets","remoteWorkPermitCountryCodes","remoteWorkPermitSubdivisionCodes","remoteSponsorship","educationRequirements","experienceMonths","experienceInPlaceOfEducation","inOfficePeriod","inOfficeFrequency","company","officeLocations"]}]},"JobOfficeLocationInput":{"anyOf":[{"type":"object","properties":{"locality":{"type":"string","minLength":1,"description":"Neighborhood or sub-locality."},"city":{"type":"string","minLength":1,"description":"City."},"region":{"type":"string","minLength":1,"description":"Region, state, or province."},"country":{"type":"string","minLength":1,"description":"ISO 3166-1 alpha-2 country code OR recognized country name/alias. Aliases are normalized to canonical alpha-2 server-side (e.g. `US`, `USA`, `United States` → `US`; `UK`, `GB`, `United Kingdom` → `GB`)."}},"required":["city","country"],"additionalProperties":false},{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500,"description":"Free-form location string (e.g. `\"Berlin, Germany\"`, `\"Mountain View, California, USA\"`). Mapbox parses + ranks candidates server-side; rejects on low confidence."}},"required":["query"],"additionalProperties":false}]},"CreateJobBody":{"type":"object","properties":{"companyId":{"type":"string","minLength":1,"description":"Identifier of the company the job belongs to."},"description":{"type":"string","minLength":1,"maxLength":25000,"description":"Long-form description of the role. Up to 25,000 characters."},"slug":{"type":"string","description":"URL-friendly slug for the job. Auto-generated from `title` when omitted."},"employmentType":{"type":"string","enum":["full_time","part_time","contract","internship","temporary","volunteer","other"],"description":"Employment type of the role."},"remoteOption":{"type":"string","enum":["on_site","hybrid","remote"],"description":"Whether the role is on-site, hybrid, or fully remote."},"remotePermits":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["worldwide","world_region","continent","region","subregion","subdivision","country","custom"]},"value":{"type":"string","minLength":1}},"required":["type","value"],"additionalProperties":false},"description":"Where remote candidates must hold work authorization. Each entry is the smallest relevant scope: `worldwide`, a `world_region` (EMEA / LATAM / NA / APAC), a `continent`, a `region`, a `subregion`, a `custom` group (e.g. `EU`), a `country` (ISO 3166-1 alpha-2), or a `subdivision` (ISO 3166-2). Subdivisions auto-imply their parent country in the derived `remoteWorkPermitCountryCodes` output. Worldwide is mutually exclusive with all other entries. The canonical `{type, value}` set is published at `GET /v1/taxonomies/remote-permits`. Pass `[]` to clear an existing constraint."},"remoteTimezones":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["all","world_region","continent","region","subregion","country","timezone"]},"value":{"type":"string","minLength":1},"plusMinus":{"type":"number","minimum":0,"maximum":12}},"required":["type","value"],"additionalProperties":false},"description":"Where remote candidates must be timezone-compatible. Each entry mirrors the `remotePermits` shape (`world_region`, `continent`, `region`, `subregion`, `country`) plus `timezone` (specific IANA name with optional `plusMinus` ±N hours expansion) and `all` (every timezone — equivalent of `worldwide` for permits). The canonical `{type, value}` set is published at `GET /v1/taxonomies/remote-timezones`. **When omitted on POST**, the server auto-derives this from `remotePermits` (or `[{all,all}]` if neither was provided). **PATCH never auto-re-derives** — once set, only an explicit replacement updates the stored value, even when `remotePermits` changes. Pass `[]` to clear an existing constraint."},"remoteSponsorship":{"type":"string","enum":["yes","no","unknown"],"description":"Whether the employer sponsors visas for remote candidates. One of `yes`, `no`, or `unknown`."},"seniority":{"type":"string","enum":["entry_level","associate","mid_level","senior","lead","principal","director","executive"],"description":"Seniority level of the role."},"applicationUrl":{"type":"string","minLength":1,"maxLength":2048,"description":"Where candidates apply. Accepts an HTTPS URL, a `mailto:` URI, or a bare email address (which is normalized to `mailto:` form)."},"salaryMin":{"type":"number","minimum":0,"description":"Minimum salary, in `salaryCurrency` units."},"salaryMax":{"type":"number","minimum":0,"description":"Maximum salary, in `salaryCurrency` units."},"salaryCurrency":{"type":"string","description":"Three-letter ISO 4217 currency code for `salaryMin` and `salaryMax`."},"salaryTimeframe":{"type":"string","enum":["per_year","per_month","per_week","per_day","per_hour"],"description":"Period the `salaryMin` and `salaryMax` figures are quoted against."},"isFeatured":{"type":"boolean","description":"Whether the job appears in featured slots on the public board."},"expiresAt":{"anyOf":[{"type":"integer","minimum":0},{"nullable":true},{"nullable":true}],"description":"Job expiry as a Unix epoch in milliseconds. Pass `null` to clear an existing expiry. Past timestamps remove the job from the public board."},"educationRequirements":{"type":"array","items":{"type":"string","enum":["high_school","associate_degree","bachelor_degree","professional_certificate","postgraduate_degree","no_requirements"]},"description":"Required education credentials. Each value is one of `high_school`, `associate_degree`, `bachelor_degree`, `professional_certificate`, `postgraduate_degree`, or `no_requirements`."},"experienceMonths":{"type":"integer","minimum":0,"description":"Minimum required experience, expressed in months."},"experienceInPlaceOfEducation":{"type":"boolean","description":"If `true`, equivalent experience may substitute for the listed education requirements."},"inOfficePeriod":{"type":"string","enum":["per_week","per_month","per_year"],"description":"Period denominator for `inOfficeFrequency`."},"inOfficeFrequency":{"type":"number","minimum":0,"description":"How often the candidate must be in-office over `inOfficePeriod`."},"officeLocations":{"type":"array","items":{"$ref":"#/components/schemas/JobOfficeLocationInput"},"description":"Physical office locations associated with the job. Each entry is forward-geocoded server-side; a country mismatch returns `400 jobs_unresolvable_location`."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"The job title."},"status":{"type":"string","enum":["draft","published"],"description":"Initial status of the job. Defaults to `draft`. Only `draft` and `published` are writable here. The system-set values `expired` and `archived` are not — use the dedicated transitions (`POST /v1/jobs/:id/publish`, `/pause`, `/expire`) for status changes after create."}},"required":["companyId","description","applicationUrl","title"],"additionalProperties":false},"DuplicateJobBody":{"type":"object","properties":{},"additionalProperties":false},"PublishJobBody":{"type":"object","properties":{"expiresAt":{"type":"string","nullable":true,"format":"date-time","description":"New expiry as an ISO 8601 datetime. Pass `null` to clear the expiry. When omitted, the server preserves the existing expiry **if it is still in the future**; a stored expiry in the past (e.g. left over from a prior `expire` call) is cleared automatically so a republished job does not land in an immediately-invisible state."}},"additionalProperties":false},"UpdateJobBody":{"type":"object","properties":{"companyId":{"type":"string","description":"Identifier of the company the job belongs to."},"description":{"type":"string","maxLength":25000,"description":"Long-form description of the role. Up to 25,000 characters."},"slug":{"type":"string","description":"URL-friendly slug for the job. Auto-generated from `title` when omitted."},"employmentType":{"type":"string","enum":["full_time","part_time","contract","internship","temporary","volunteer","other"],"description":"Employment type of the role."},"remoteOption":{"type":"string","enum":["on_site","hybrid","remote"],"description":"Whether the role is on-site, hybrid, or fully remote."},"remotePermits":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["worldwide","world_region","continent","region","subregion","subdivision","country","custom"]},"value":{"type":"string","minLength":1}},"required":["type","value"],"additionalProperties":false},"description":"Where remote candidates must hold work authorization. Each entry is the smallest relevant scope: `worldwide`, a `world_region` (EMEA / LATAM / NA / APAC), a `continent`, a `region`, a `subregion`, a `custom` group (e.g. `EU`), a `country` (ISO 3166-1 alpha-2), or a `subdivision` (ISO 3166-2). Subdivisions auto-imply their parent country in the derived `remoteWorkPermitCountryCodes` output. Worldwide is mutually exclusive with all other entries. The canonical `{type, value}` set is published at `GET /v1/taxonomies/remote-permits`. Pass `[]` to clear an existing constraint."},"remoteTimezones":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["all","world_region","continent","region","subregion","country","timezone"]},"value":{"type":"string","minLength":1},"plusMinus":{"type":"number","minimum":0,"maximum":12}},"required":["type","value"],"additionalProperties":false},"description":"Where remote candidates must be timezone-compatible. Each entry mirrors the `remotePermits` shape (`world_region`, `continent`, `region`, `subregion`, `country`) plus `timezone` (specific IANA name with optional `plusMinus` ±N hours expansion) and `all` (every timezone — equivalent of `worldwide` for permits). The canonical `{type, value}` set is published at `GET /v1/taxonomies/remote-timezones`. **When omitted on POST**, the server auto-derives this from `remotePermits` (or `[{all,all}]` if neither was provided). **PATCH never auto-re-derives** — once set, only an explicit replacement updates the stored value, even when `remotePermits` changes. Pass `[]` to clear an existing constraint."},"remoteSponsorship":{"type":"string","enum":["yes","no","unknown"],"description":"Whether the employer sponsors visas for remote candidates. One of `yes`, `no`, or `unknown`."},"seniority":{"type":"string","enum":["entry_level","associate","mid_level","senior","lead","principal","director","executive"],"description":"Seniority level of the role."},"applicationUrl":{"type":"string","minLength":1,"maxLength":2048,"description":"Where candidates apply. Accepts an HTTPS URL, a `mailto:` URI, or a bare email address (which is normalized to `mailto:` form)."},"salaryMin":{"type":"number","minimum":0,"description":"Minimum salary, in `salaryCurrency` units."},"salaryMax":{"type":"number","minimum":0,"description":"Maximum salary, in `salaryCurrency` units."},"salaryCurrency":{"type":"string","description":"Three-letter ISO 4217 currency code for `salaryMin` and `salaryMax`."},"salaryTimeframe":{"type":"string","enum":["per_year","per_month","per_week","per_day","per_hour"],"description":"Period the `salaryMin` and `salaryMax` figures are quoted against."},"isFeatured":{"type":"boolean","description":"Whether the job appears in featured slots on the public board."},"expiresAt":{"anyOf":[{"type":"integer","minimum":0},{"nullable":true},{"nullable":true}],"description":"Job expiry as a Unix epoch in milliseconds. Pass `null` to clear an existing expiry. Past timestamps remove the job from the public board."},"educationRequirements":{"type":"array","items":{"type":"string","enum":["high_school","associate_degree","bachelor_degree","professional_certificate","postgraduate_degree","no_requirements"]},"description":"Required education credentials. Each value is one of `high_school`, `associate_degree`, `bachelor_degree`, `professional_certificate`, `postgraduate_degree`, or `no_requirements`."},"experienceMonths":{"type":"integer","minimum":0,"description":"Minimum required experience, expressed in months."},"experienceInPlaceOfEducation":{"type":"boolean","description":"If `true`, equivalent experience may substitute for the listed education requirements."},"inOfficePeriod":{"type":"string","enum":["per_week","per_month","per_year"],"description":"Period denominator for `inOfficeFrequency`."},"inOfficeFrequency":{"type":"number","minimum":0,"description":"How often the candidate must be in-office over `inOfficePeriod`."},"officeLocations":{"type":"array","items":{"$ref":"#/components/schemas/JobOfficeLocationInput"},"description":"Physical office locations associated with the job. Each entry is forward-geocoded server-side; a country mismatch returns `400 jobs_unresolvable_location`."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"The job title."}},"additionalProperties":false},"BatchRequestBody":{"type":"object","properties":{"operations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","minLength":1},"method":{"type":"string","enum":["POST"]},"body":{"nullable":true},"action":{"type":"string"},"resourceId":{"type":"string"}},"required":["id","method"]},{"type":"object","properties":{"id":{"type":"string","minLength":1},"method":{"type":"string","enum":["PATCH"]},"body":{"nullable":true},"resourceId":{"type":"string","minLength":1}},"required":["id","method","resourceId"]},{"type":"object","properties":{"id":{"type":"string","minLength":1},"method":{"type":"string","enum":["DELETE"]},"resourceId":{"type":"string","minLength":1}},"required":["id","method","resourceId"]}]},"minItems":1,"maxItems":100,"description":"Array of sub-operations to execute. Each entry runs independently and reports its result on the corresponding entry of the response `data` array. Sub-operation `id` values must be unique within the batch. Up to 100 entries."}},"required":["operations"],"additionalProperties":false},"SearchJobsBody":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"Free-text search query matched against job title and description. Up to 200 characters."},"filters":{"type":"object","properties":{"status":{"type":"array","items":{"type":"string","enum":["draft","published","expired","archived"]},"maxItems":10,"description":"Only return jobs in any of the given statuses. Up to 10 values."},"companyId":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Only return jobs at any of the given company IDs. Up to 10 values."},"remoteOption":{"type":"array","items":{"type":"string","enum":["on_site","hybrid","remote"]},"maxItems":10,"description":"Only return jobs with any of the given remote-work options. Up to 10 values."},"employmentType":{"type":"array","items":{"type":"string","enum":["full_time","part_time","contract","internship","temporary","volunteer","other"]},"maxItems":10,"description":"Only return jobs with any of the given employment types. Up to 10 values."},"seniority":{"type":"array","items":{"type":"string","enum":["entry_level","associate","mid_level","senior","lead","principal","director","executive"]},"maxItems":10,"description":"Only return jobs at any of the given seniority levels. Up to 10 values."},"publishedAt":{"type":"object","properties":{"gte":{"type":"string","format":"date-time","description":"Only return jobs published at or after this ISO 8601 datetime."},"lte":{"type":"string","format":"date-time","description":"Only return jobs published at or before this ISO 8601 datetime."}},"additionalProperties":false,"description":"Range filter on the job's `publishedAt` timestamp."}},"additionalProperties":false,"description":"Optional faceted filters to narrow search results. Multi-value filters match jobs in any of the supplied values; range filters accept `gte` and `lte` bounds."},"cursor":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100.","example":20}},"additionalProperties":false},"MediaUpload":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the object."},"object":{"type":"string","enum":["media_upload"],"description":"String representing the object's type. Objects of the same type share the same value."},"url":{"type":"string","nullable":true,"description":"Signed URL where the file can be downloaded. Always set on the upload response; may be `null` on retrieval if the underlying blob has been deleted."},"urlExpiresAt":{"type":"string","description":"Time at which the signed `url` expires. Approximately 15 minutes after the response is issued. ISO 8601 datetime."},"mimeType":{"type":"string","description":"MIME type of the uploaded file."},"sizeBytes":{"type":"number","description":"Size of the uploaded file, in bytes."},"purpose":{"type":"string","enum":["board_logo","board_hero","account_avatar","company_logo","blog_image"],"description":"Resource type the file was uploaded for."}},"required":["id","object","url","urlExpiresAt","mimeType","sizeBytes","purpose"],"x-internal":true},"MediaGet":{"allOf":[{"$ref":"#/components/schemas/MediaUpload"},{"type":"object","properties":{"uploadedAt":{"type":"string","description":"Time at which the file was uploaded. ISO 8601 datetime."},"referencedBy":{"type":"array","items":{"type":"object","properties":{"resourceType":{"type":"string","description":"Type of the resource referencing this file."},"resourceId":{"type":"string","description":"Identifier of the resource referencing this file."}},"required":["resourceType","resourceId"]},"description":"Resources currently referencing this file. Currently always `[]` — the resolver is not yet implemented."}},"required":["uploadedAt","referencedBy"]}],"x-internal":true},"DynamicClientRegistrationResponse":{"type":"object","properties":{"client_id":{"type":"string","description":"Public OAuth client identifier."},"client_id_issued_at":{"type":"number","description":"Time at which the client was registered. Unix epoch in seconds."},"client_secret":{"type":"string","description":"Plaintext OAuth client secret. Returned exactly once, at registration; cannot be retrieved later."},"client_secret_expires_at":{"type":"number","description":"Time at which the client secret expires. Unix epoch in seconds, or `0` if the secret does not expire."},"redirect_uris":{"type":"array","items":{"type":"string"},"description":"Array of redirect URIs registered for the client."},"client_name":{"type":"string","description":"Human-readable client name shown to users on the consent screen."},"grant_types":{"type":"array","items":{"type":"string"},"description":"OAuth grant types the client is permitted to use."},"response_types":{"type":"array","items":{"type":"string"},"description":"OAuth response types the client is permitted to use."},"token_endpoint_auth_method":{"type":"string","description":"Authentication method the client uses at the token endpoint."},"scope":{"type":"string","description":"Space-separated list of scopes the client may request."}},"required":["client_id","client_id_issued_at","client_secret","client_secret_expires_at","redirect_uris","client_name","grant_types","response_types","token_endpoint_auth_method","scope"],"x-internal":true},"DynamicClientRegistrationRequest":{"type":"object","properties":{"redirect_uris":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"Array of redirect URIs the client may use. Must be HTTPS, except for `http://localhost` URIs in development. At least one entry is required."},"client_name":{"type":"string","minLength":1,"maxLength":256,"description":"Human-readable client name shown to users on the consent screen."},"scope":{"type":"string","description":"Space-separated list of scopes the client may request. When omitted, the client is registered for all scopes."}},"required":["redirect_uris","client_name"],"x-internal":true},"Usage":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the object. Equal to the account ID — usage is a per-account singleton."},"object":{"type":"string","enum":["usage"],"description":"String representing the object's type. Objects of the same type share the same value."},"activeJobs":{"type":"number","description":"Number of jobs currently in `published` status."},"activeJobsLimit":{"type":"number","description":"Plan-enforced cap on the number of published jobs."},"available":{"type":"number","description":"Number of additional jobs the account may publish before hitting the limit."},"plan":{"type":"string","description":"Slug of the account's current plan."}},"required":["id","object","activeJobs","activeJobsLimit","available","plan"]},"PublicJobLinks":{"type":"object","properties":{"public":{"type":"string","nullable":true,"format":"uri","description":"Canonical public URL for this job, or `null` when the job has no slug or no associated company slug (so a stable URL cannot be assembled)."}},"required":["public"],"description":"Public-only links. The admin URL is intentionally omitted on public-board responses.","x-internal":true},"PublicJob":{"allOf":[{"$ref":"#/components/schemas/JobSummary"},{"type":"object","properties":{"object":{"type":"string","enum":["public_job"],"description":"String representing the object's type. Objects of the same type share the same value."},"links":{"$ref":"#/components/schemas/PublicJobLinks"},"description":{"type":"string","nullable":true,"description":"Long-form description of the role, or `null` if not specified."},"applicationUrl":{"type":"string","nullable":true,"description":"Where candidates apply, or `null` if not specified. An HTTPS URL or `mailto:` URI."},"remotePermits":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"}},"required":["type","value"]},"description":"Hierarchical permit selection authored by the board owner. The three `remoteWorkPermit*` and `remoteWorldwide` fields are read-only derived projections."},"remoteWorldwide":{"type":"boolean","nullable":true,"description":"Read-only — derived from `remotePermits`. `true` only when the authored selection is a single `{type:\"worldwide\"}` entry."},"remoteTimezones":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"plusMinus":{"type":"number"}},"required":["type","value"]},"description":"Hierarchical timezone selection. The flat `remoteAllowedTzOffsets` field below is the read-only derived projection."},"remoteAllowedTzOffsets":{"type":"array","items":{"type":"number"},"description":"Read-only — derived from `remoteTimezones`. UTC hour offsets used by the job-search index."},"remoteWorkPermitCountryCodes":{"type":"array","items":{"type":"string"},"description":"Read-only — derived from `remotePermits` (hierarchical groups fan out to alpha2 sets; subdivisions auto-add the parent country). ISO 3166-1 alpha-2 codes."},"remoteWorkPermitSubdivisionCodes":{"type":"array","items":{"type":"string"},"description":"Read-only — derived from `remotePermits` (subdivision entries only). ISO 3166-2 codes."},"remoteSponsorship":{"type":"string","enum":["yes","no","unknown"],"description":"Whether the employer sponsors visas for remote candidates. One of `yes`, `no`, or `unknown`."},"educationRequirements":{"type":"array","items":{"type":"string","enum":["high_school","associate_degree","bachelor_degree","professional_certificate","postgraduate_degree","no_requirements"]},"description":"Required education credentials. Each value is one of `high_school`, `associate_degree`, `bachelor_degree`, `professional_certificate`, `postgraduate_degree`, or `no_requirements`."},"experienceMonths":{"type":"number","nullable":true,"description":"Minimum required experience in months, or `null` if not specified."},"experienceInPlaceOfEducation":{"type":"boolean","nullable":true,"description":"If `true`, equivalent experience may substitute for the listed education requirements. `null` if not specified."},"inOfficePeriod":{"type":"string","nullable":true,"enum":["per_week","per_month","per_year"],"description":"Period denominator for `inOfficeFrequency`, or `null` if not specified."},"inOfficeFrequency":{"type":"number","nullable":true,"description":"How often the candidate must be in-office over `inOfficePeriod`, or `null` if not specified."},"company":{"$ref":"#/components/schemas/JobCompany"},"officeLocations":{"type":"array","items":{"$ref":"#/components/schemas/JobOfficeLocation"},"description":"Physical office locations associated with the job."}},"required":["description","applicationUrl","remotePermits","remoteWorldwide","remoteTimezones","remoteAllowedTzOffsets","remoteWorkPermitCountryCodes","remoteWorkPermitSubdivisionCodes","remoteSponsorship","educationRequirements","experienceMonths","experienceInPlaceOfEducation","inOfficePeriod","inOfficeFrequency","company","officeLocations"]}],"x-internal":true},"PublicSearchJobsBody":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"Free-text search query matched against job title and description. Up to 200 characters."},"filters":{"type":"object","properties":{"companyId":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Only return jobs at any of the given company IDs. Up to 10 values."},"remoteOption":{"type":"array","items":{"type":"string","enum":["on_site","hybrid","remote"]},"maxItems":10,"description":"Only return jobs with any of the given remote-work options. Up to 10 values."},"employmentType":{"type":"array","items":{"type":"string","enum":["full_time","part_time","contract","internship","temporary","volunteer","other"]},"maxItems":10,"description":"Only return jobs with any of the given employment types. Up to 10 values."},"seniority":{"type":"array","items":{"type":"string","enum":["entry_level","associate","mid_level","senior","lead","principal","director","executive"]},"maxItems":10,"description":"Only return jobs at any of the given seniority levels. Up to 10 values."},"publishedAt":{"type":"object","properties":{"gte":{"type":"string","format":"date-time","description":"Only return jobs published at or after this ISO 8601 datetime."},"lte":{"type":"string","format":"date-time","description":"Only return jobs published at or before this ISO 8601 datetime."}},"additionalProperties":false,"description":"Range filter on the job's `publishedAt` timestamp."}},"additionalProperties":false,"description":"Optional faceted filters to narrow search results. Multi-value filters match jobs in any of the supplied values; range filters accept `gte` and `lte` bounds."},"cursor":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100.","example":20}},"additionalProperties":false,"x-internal":true},"PublicCompanyLinks":{"type":"object","properties":{"public":{"type":"string","nullable":true,"format":"uri","description":"Canonical public URL for this company on the board, or `null` when no slug is set."}},"required":["public"],"description":"Public-only links. The admin URL is intentionally omitted on public-board responses.","x-internal":true},"CompanyPublic":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the object."},"object":{"type":"string","enum":["public_company"],"description":"String representing the object's type. Objects of the same type share the same value."},"name":{"type":"string","description":"Display name of the company."},"slug":{"type":"string","description":"URL-friendly slug for the company."},"website":{"type":"string","nullable":true,"description":"Public company website URL, or `null` if not set."},"logoUrl":{"type":"string","nullable":true,"description":"URL of the company logo, or `null` if no logo is set."},"description":{"type":"string","nullable":true,"description":"Long-form description of the company, or `null` if not set."},"jobCount":{"type":"number","description":"Total number of public-facing jobs at this company. Currently mirrors `publishedJobCount`."},"publishedJobCount":{"type":"number","description":"Number of currently-published, non-expired jobs at this company."},"links":{"$ref":"#/components/schemas/PublicCompanyLinks"}},"required":["id","object","name","slug","website","logoUrl","description","jobCount","publishedJobCount","links"],"x-internal":true},"PublicCompaniesSearchBody":{"type":"object","properties":{"query":{"type":"string","maxLength":200,"description":"Free-text search query matched against company name. Up to 200 characters."},"cursor":{"type":"string","nullable":true,"minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"limit":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100."}},"additionalProperties":false,"x-internal":true},"TokenResponse":{"type":"object","properties":{"access_token":{"type":"string","description":"Newly issued access token. Use as a `Bearer` token in the `Authorization` header."},"token_type":{"type":"string","enum":["Bearer"],"description":"Always `Bearer`."},"expires_in":{"type":"number","description":"Lifetime of the access token, in seconds."},"refresh_token":{"type":"string","description":"Newly issued refresh token. Single-use; reusing it revokes the entire token chain."},"scope":{"type":"string","description":"Space-separated list of scopes granted on the issued token."}},"required":["access_token","token_type","expires_in","refresh_token","scope"],"x-internal":true},"TokenRequest":{"type":"object","properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"],"description":"OAuth grant type. Either `authorization_code` to exchange an authorization code for a new token pair, or `refresh_token` to exchange a refresh token for a new token pair."},"code":{"type":"string","description":"Authorization code returned from the authorization endpoint. Required when `grant_type` is `authorization_code`."},"redirect_uri":{"type":"string","description":"Redirect URI used in the original authorization request. Must match exactly. Required when `grant_type` is `authorization_code`."},"code_verifier":{"type":"string","description":"PKCE code verifier whose `S256` hash matches the original `code_challenge`. Required when `grant_type` is `authorization_code`."},"refresh_token":{"type":"string","description":"Refresh token previously issued. Required when `grant_type` is `refresh_token`. Refresh tokens are single-use; reusing one revokes the entire token chain."},"client_id":{"type":"string","description":"OAuth client identifier. May be supplied here or via HTTP Basic authentication."},"client_secret":{"type":"string","description":"OAuth client secret. May be supplied here or via HTTP Basic authentication."},"scope":{"type":"string","description":"Optional scope narrowing. Currently ignored — issued tokens always carry the full scope registered for the client."}},"required":["grant_type"],"x-internal":true},"RevokeRequest":{"type":"object","properties":{"token":{"type":"string","minLength":1,"description":"The access or refresh token to revoke."},"token_type_hint":{"type":"string","enum":["access_token","refresh_token"],"description":"Hint indicating whether `token` is an `access_token` or `refresh_token`. Optional."},"client_id":{"type":"string","description":"OAuth client identifier. May be supplied here or via HTTP Basic authentication."},"client_secret":{"type":"string","description":"OAuth client secret. May be supplied here or via HTTP Basic authentication."}},"required":["token"],"x-internal":true},"OperationProgress":{"type":"object","nullable":true,"properties":{"percent":{"type":"number","description":"Progress as a percentage between 0 and 100, when the operation reports a percentage."},"message":{"type":"string","description":"Human-readable progress message, when available."},"processed":{"type":"number","description":"Number of items processed so far, when applicable."},"total":{"type":"number","description":"Total number of items to process, when known."}},"description":"Snapshot of the operation's progress, or `null` if the operation does not report progress.","x-internal":true},"OperationErrorEnvelope":{"type":"object","nullable":true,"properties":{"code":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."},"details":{"nullable":true,"description":"Additional structured details about the error, when present."},"requestId":{"type":"string","description":"Identifier of the request that produced the error. Use this to correlate with platform logs."}},"required":["code","message"],"description":"Error envelope, populated once the operation reaches `failed`. `null` otherwise.","x-internal":true},"OperationResource":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the object."},"object":{"type":"string","enum":["operation"],"description":"String representing the object's type. Objects of the same type share the same value."},"kind":{"type":"string","description":"Operation kind, identifying which workflow the operation runs."},"state":{"type":"string","enum":["pending","running","succeeded","failed","cancelled"],"description":"Current state of the operation."},"accountId":{"type":"string","description":"Identifier of the account the operation belongs to."},"progress":{"$ref":"#/components/schemas/OperationProgress"},"result":{"nullable":true,"description":"Operation result, populated once the operation reaches `succeeded`. Shape varies by `kind`."},"error":{"$ref":"#/components/schemas/OperationErrorEnvelope"},"createdAt":{"type":"string","description":"Time at which the operation was created. ISO 8601 datetime."},"updatedAt":{"type":"string","description":"Time at which the operation was last updated. ISO 8601 datetime."},"completedAt":{"type":"string","nullable":true,"description":"Time at which the operation reached a terminal state, or `null` if it has not yet completed. ISO 8601 datetime."},"cancelRequested":{"type":"boolean","description":"Whether cancellation of the operation has been requested."},"resourceType":{"type":"string","nullable":true,"description":"Type of resource the operation acts on, or `null` for resource-less operations."},"resourceId":{"type":"string","nullable":true,"description":"Identifier of the resource the operation acts on, or `null` for resource-less operations."},"parentOperationId":{"type":"string","nullable":true,"description":"Identifier of the parent operation when this operation is a child of a fan-out, or `null` otherwise."}},"required":["id","object","kind","state","accountId","progress","error","createdAt","updatedAt","completedAt","cancelRequested","resourceType","resourceId","parentOperationId"],"x-internal":true},"PatchSettingsBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Display name of the board."},"slug":{"type":"string","minLength":1,"maxLength":120,"description":"URL slug of the board. Lowercase alphanumeric and hyphens; reserved values (e.g. `admin`, `api`) are rejected."},"primaryDomainId":{"type":"string","description":"Identifier of the custom domain to use as the primary public URL."},"logoStorageId":{"type":"string","description":"Media storage ID returned by `POST /v1/media/upload` with `purpose=board_logo`."},"heroStorageId":{"type":"string","description":"Media storage ID returned by `POST /v1/media/upload` with `purpose=board_hero`."},"passwordProtectionEnabled":{"type":"boolean","description":"Whether the board sits behind a password gate. Use `POST /v1/settings/password-protection` to set the actual password before enabling."},"jobAlertsEnabled":{"type":"boolean","description":"Whether candidates can subscribe to email alerts for new jobs."},"candidatesEnabled":{"type":"boolean","description":"Whether candidate profiles are enabled on the board."},"employersEnabled":{"type":"boolean","description":"Whether employer self-serve flows are enabled."},"blogEnabled":{"type":"boolean","description":"Whether the public blog is exposed."},"impressumEnabled":{"type":"boolean","description":"Whether the legal Impressum page is exposed (required in some jurisdictions)."},"requireApprovalFreeJobs":{"type":"boolean","description":"Whether jobs posted by employers from the free tier require admin approval before they appear on the public board."},"requireApprovalAggregatedJobs":{"type":"boolean","description":"Whether aggregated jobs (e.g. those scraped or imported from upstream sources) require admin approval before they appear on the public board."},"registrationWallEnabled":{"type":"boolean","description":"Whether visitors must sign in to view jobs."},"talentDirectoryEnabled":{"type":"boolean","description":"Whether the public talent directory is enabled."},"showCavunoBranding":{"type":"boolean","description":"Whether the Cavuno-branded footer is displayed on the public board. Plan-gated; lower-tier plans cannot disable this."},"defaultJobDurationDays":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Default expiry, in days, applied to newly published jobs when no `expiresAt` is supplied."},"contactEmail":{"anyOf":[{"type":"string","maxLength":320,"format":"email"},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Public contact email shown on the board. Pass `null` to clear."},"companyLegalName":{"anyOf":[{"type":"string","maxLength":200},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Legal name of the entity operating the board. Pass `null` to clear."},"companyAddress":{"anyOf":[{"type":"string","maxLength":500},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Postal address of the entity operating the board. Pass `null` to clear."},"companyWebsiteUrl":{"anyOf":[{"type":"string","maxLength":500},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Public company website URL. Pass `null` to clear."},"companyXHandle":{"anyOf":[{"type":"string","maxLength":500},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Company X (Twitter) handle or profile URL. Pass `null` to clear."},"companyFacebookUrl":{"anyOf":[{"type":"string","maxLength":500},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Company Facebook page URL. Pass `null` to clear."},"companyLinkedinUrl":{"anyOf":[{"type":"string","maxLength":500},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Company LinkedIn page URL. Pass `null` to clear."},"talentNavLabel":{"type":"string","minLength":1,"maxLength":50,"description":"Label shown for the talent directory in the public navigation. 1–50 characters."},"passwordProtectionMessage":{"anyOf":[{"type":"string","maxLength":500},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Custom copy displayed on the password gate. Up to 500 characters. Pass `null` to clear."},"config":{"type":"object","additionalProperties":{"nullable":true},"description":"Free-form configuration object merged into the existing config. Reserved keys (e.g. `passwordProtectionEnabled`, `adsenseClientId`, `jobAccessPaywallEnabled`) cannot be set here — use the dedicated endpoints instead."}},"additionalProperties":false,"x-internal":true},"SettingsAdsenseSlot":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this placement is rendered."},"slotId":{"anyOf":[{"type":"string","pattern":"^[0-9]{10}$"},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Ten-digit AdSense slot ID. Pass an empty string or `null` to clear."},"layout":{"anyOf":[{"type":"string","enum":["auto","in-article","in-feed","fluid"]},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"AdSense layout type for the placement."},"format":{"anyOf":[{"type":"string","enum":["auto","horizontal","vertical","rectangle","responsive"]},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"AdSense ad format."},"style":{"anyOf":[{"type":"string","enum":["default","light","dark","contrast"]},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Visual style override for the placement."},"frequency":{"anyOf":[{"type":"integer","minimum":1,"maximum":50},{"nullable":true},{"nullable":true}],"description":"How often the placement is shown (e.g. once every N items)."}},"required":["enabled","slotId"],"x-internal":true},"SettingsAdsenseBody":{"type":"object","properties":{"adsenseEnabled":{"type":"boolean","description":"Whether AdSense placements are rendered on the public board."},"adsenseClientId":{"anyOf":[{"type":"string","maxLength":25,"pattern":"^ca-pub-\\d{16}$"},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"AdSense publisher ID in `ca-pub-XXXXXXXXXXXXXXXX` format. Pass an empty string or `null` to clear."},"adsenseSlots":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SettingsAdsenseSlot"},"description":"Map of placement key to slot configuration. Placement keys are lowercase alphanumeric with `-`, `_`, `.`, or `:`."},"adsTxt":{"anyOf":[{"type":"string","maxLength":2000},{"type":"string","enum":[""]},{"nullable":true},{"nullable":true}],"description":"Contents to serve from `/ads.txt`. Up to 2,000 characters. Pass an empty string or `null` to clear."}},"additionalProperties":false,"x-internal":true},"SettingsPaywallBody":{"type":"object","properties":{"jobAccessPaywallEnabled":{"type":"boolean","description":"Whether the job-access paywall is enforced on the public board."},"jobAccessPreviewCount":{"type":"integer","minimum":1,"maximum":500,"description":"Number of jobs visible before the paywall locks the rest. Range 1–500."},"jobAccessLockHeading":{"type":"string","maxLength":120,"description":"Heading shown on the paywall. Up to 120 characters."},"jobAccessLockDescription":{"type":"string","maxLength":600,"description":"Body copy shown on the paywall. Up to 600 characters."},"jobAccessButtonText":{"type":"string","maxLength":60,"description":"Call-to-action label shown on the paywall. Up to 60 characters."},"jobAccessDisclaimerText":{"type":"string","maxLength":200,"description":"Fine-print disclaimer shown beneath the call-to-action. Up to 200 characters."},"jobAccessPerMonthLabel":{"type":"string","maxLength":60,"description":"Label appended to the monthly price (e.g. `/month`). Up to 60 characters."},"jobAccessSavingsTemplate":{"type":"string","maxLength":120,"description":"Template string used to render the savings line for annual plans. Up to 120 characters."},"jobAccessCurrency":{"type":"string","minLength":3,"maxLength":3,"description":"Three-letter ISO 4217 currency code for paywall pricing."},"jobAccessStripeProductId":{"anyOf":[{"type":"string"},{"nullable":true},{"nullable":true}],"description":"Stripe product ID associated with the paywall plan. Pass `null` to clear."},"jobAccessStripePortalConfigId":{"anyOf":[{"type":"string"},{"nullable":true},{"nullable":true}],"description":"Stripe billing-portal configuration ID used for self-serve plan management. Pass `null` to clear."}},"required":["jobAccessPaywallEnabled"],"additionalProperties":false,"x-internal":true},"SettingsPasswordProtectionBody":{"type":"object","properties":{"password":{"type":"string","minLength":8,"description":"Plaintext password used to gate the public board. Must be at least 8 characters. Stored hashed and encrypted server-side."}},"required":["password"],"additionalProperties":false,"x-internal":true},"RemotePermitTaxonomyEntry":{"type":"object","properties":{"type":{"type":"string","description":"Discriminator. One of: `worldwide`, `world_region`, `continent`, `region`, `subregion`, `custom`, `country`, `subdivision`."},"value":{"type":"string","description":"Canonical value for the type. ISO 3166-1 alpha-2 for `country`, ISO 3166-2 for `subdivision`, etc."},"label":{"type":"string","description":"Human-readable display label."}},"required":["type","value","label"]},"RemoteTimezoneTaxonomyEntry":{"type":"object","properties":{"type":{"type":"string","description":"Discriminator. One of: `all`, `world_region`, `continent`, `region`, `subregion`, `country`, `timezone`."},"value":{"type":"string","description":"Canonical value for the type. ISO 3166-1 alpha-2 for `country`, IANA name (e.g. `Europe/London`) for `timezone`, etc."},"label":{"type":"string","description":"Human-readable display label."}},"required":["type","value","label"]}},"parameters":{}},"paths":{"/api-keys":{"get":{"summary":"List all API keys","description":"Returns a list of your API keys. The keys are returned sorted by creation date, with the most recently created keys appearing first. Plaintext secrets are never included; each key is identified by its public prefix `cavuno_live_<keyId>_`. Keys can only be created from the dashboard — the API does not expose a creation endpoint.","parameters":[{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50.","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/api-keys"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}},"required":["object","url","hasMore","nextCursor","data"]}}}}},"tags":["API keys"]}},"/audit-logs":{"get":{"summary":"List all audit log entries","description":"Returns a list of audit log entries for your account. The entries are returned sorted by timestamp, with the most recent entries appearing first. Requires the `audit.read` permission.","parameters":[{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Only return audit entries on the given resource type (e.g. `job`, `company`)."},"required":false,"description":"Only return audit entries on the given resource type (e.g. `job`, `company`).","name":"resourceType","in":"query"},{"schema":{"type":"string","enum":["api_key","oauth_token","user_session","system"],"description":"Only return audit entries written by the given actor type."},"required":false,"description":"Only return audit entries written by the given actor type.","name":"actorType","in":"query"},{"schema":{"type":"string","description":"Only return audit entries written by the given actor ID."},"required":false,"description":"Only return audit entries written by the given actor ID.","name":"actorId","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only return audit entries with a `timestamp` at or after this ISO 8601 datetime."},"required":false,"description":"Only return audit entries with a `timestamp` at or after this ISO 8601 datetime.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only return audit entries with a `timestamp` at or before this ISO 8601 datetime."},"required":false,"description":"Only return audit entries with a `timestamp` at or before this ISO 8601 datetime.","name":"to","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/audit-logs"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLogEntry"}}},"required":["object","url","hasMore","nextCursor","data"]}}}}},"tags":["Audit logs"],"x-internal":true}},"/audit-logs/{id}":{"get":{"summary":"Retrieve an audit log entry","description":"Retrieves the details of an existing audit log entry. You only need to supply the unique ID that was returned with the entry.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the audit log entry."},"required":true,"description":"Unique identifier for the audit log entry.","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditLogEntry"}}}}},"tags":["Audit logs"],"x-internal":true}},"/companies":{"get":{"summary":"List all companies","description":"Returns a list of your companies. The companies are returned sorted by creation date, with the most recently created companies appearing first.","parameters":[{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100.","example":20,"name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/companies"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanySummary"}}},"required":["object","url","hasMore","nextCursor","data"]}}}},"400":{"description":"The request was malformed."}},"tags":["Companies"]},"post":{"summary":"Create a company","description":"Creates a new company. A logo is auto-fetched from `website` when available. The request is idempotent when an `Idempotency-Key` header is supplied.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompanyBody"}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"400":{"description":"The request was malformed."},"409":{"description":"Another company already uses the same website domain or name."}},"tags":["Companies"]}},"/companies/find-or-create":{"post":{"summary":"Resolve or create a company","description":"Resolves an existing company by website domain (then by slug), or creates a new company if no match is found. On creation, a logo is auto-fetched from `website` when available. Useful for workflows that have a name and website but no company ID yet.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindOrCreateCompanyBody"}}}},"responses":{"200":{"description":"Successful response. The `matched` field indicates whether the returned company already existed (`true`) or was newly created (`false`).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Company"},{"type":"object","properties":{"matched":{"type":"boolean"}},"required":["matched"]}]}}}}},"tags":["Companies"]}},"/companies/{id}":{"get":{"summary":"Retrieve a company","description":"Retrieves the details of an existing company. You only need to supply the unique company ID that was returned upon company creation.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the company."},"required":true,"description":"Unique identifier for the company.","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"404":{"description":"Company not found."}},"tags":["Companies"]},"patch":{"summary":"Update a company","description":"Updates the specified company by setting the values of the parameters passed. Any parameters not provided will be left unchanged. The request is idempotent when an `Idempotency-Key` header is supplied.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the company."},"required":true,"description":"Unique identifier for the company.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCompanyBody"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"400":{"description":"The request was malformed."},"404":{"description":"Company not found."},"409":{"description":"Another company already uses the same website domain or name."}},"tags":["Companies"]},"delete":{"summary":"Delete a company","description":"Permanently deletes a company and cascades to delete every job attached to it (along with each job’s child records). It cannot be undone.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the company."},"required":true,"description":"Unique identifier for the company.","name":"id","in":"path"}],"responses":{"204":{"description":"Successful response."},"404":{"description":"Company not found."}},"tags":["Companies"]}},"/companies/{id}/logo":{"post":{"summary":"Upload a company logo","description":"Uploads a logo for the company as a multipart form with a single `file` part. Accepts PNG, JPEG, WebP, and GIF up to 5 MB. Replaces the previous logo when one exists.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the company."},"required":true,"description":"Unique identifier for the company.","name":"id","in":"path"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"400":{"description":"The request was malformed."},"404":{"description":"Company not found."},"413":{"description":"The uploaded file exceeded the 5 MB size limit."},"415":{"description":"The uploaded file's MIME type is not supported."}},"tags":["Companies"]},"delete":{"summary":"Delete a company logo","description":"Removes the logo from the company and deletes the underlying file. Returns 404 if the company has no logo set.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the company."},"required":true,"description":"Unique identifier for the company.","name":"id","in":"path"}],"responses":{"204":{"description":"Successful response."},"404":{"description":"Company not found, or the company has no logo to remove."}},"tags":["Companies"]}},"/companies/{id}/jobs":{"get":{"summary":"List jobs at a company","description":"Returns a list of jobs belonging to the specified company. The jobs are returned sorted by creation date, with the most recently created jobs appearing first.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the company."},"required":true,"description":"Unique identifier for the company.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100.","example":20,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["draft","published","expired","archived"],"description":"Only return jobs matching the given status. One of `draft`, `published`, `expired`, or `archived`."},"required":false,"description":"Only return jobs matching the given status. One of `draft`, `published`, `expired`, or `archived`.","example":"published","name":"status","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/companies/{id}/jobs"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"nullable":true}}},"required":["object","url","hasMore","nextCursor","data"]}}}},"404":{"description":"Company not found."}},"tags":["Companies"]}},"/companies/search":{"post":{"summary":"Search companies","description":"Searches your companies using a free-text query. Results are returned sorted by creation date, with the most recently created companies appearing first.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCompaniesBody"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["search_result"]},"url":{"type":"string","example":"/v1/companies/search"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["object","url","hasMore","nextCursor","data"]}}}}},"tags":["Companies"]}},"/companies/batch":{"post":{"summary":"Run a batch of company operations","description":"Runs up to 100 company operations in a single request, with a 5 MB request body limit. Each sub-operation runs independently and writes its own audit entry. Idempotency keys are honored on the batch itself, not on individual sub-operations.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompaniesBatchRequest"}}}},"responses":{"200":{"description":"Successful response. Inspect each entry of the `data` array for the per-sub-operation status.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["batch_result"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"number"},"data":{"nullable":true},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"nullable":true}},"required":["code","message"]}},"required":["id","status"]}}},"required":["object","data"]}}}},"413":{"description":"The request body exceeded 5 MB."}},"tags":["Companies"]}},"/jobs":{"get":{"summary":"List all jobs","description":"Returns a list of your jobs. The jobs are returned sorted by creation date, with the most recently created jobs appearing first.","parameters":[{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100.","example":20,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["draft","published","expired","archived"],"description":"Only return jobs matching the given status. One of `draft`, `published`, `expired`, or `archived`."},"required":false,"description":"Only return jobs matching the given status. One of `draft`, `published`, `expired`, or `archived`.","example":"published","name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Only return jobs at the company with the given ID."},"required":false,"description":"Only return jobs at the company with the given ID.","name":"companyId","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/jobs"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"}}},"required":["object","url","hasMore","nextCursor","data"]}}}},"400":{"description":"The request was malformed."}},"tags":["Jobs"]},"post":{"summary":"Create a job","description":"Creates a new job in `draft` status. The request is idempotent when an `Idempotency-Key` header is supplied.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJobBody"}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"The request was malformed."},"404":{"description":"The supplied company does not exist or is not accessible."}},"tags":["Jobs"]}},"/jobs/{id}/duplicate":{"post":{"summary":"Duplicate a job","description":"Creates a new draft job by copying the fields of an existing job. The slug of the new job is generated with a `copy-of-` prefix to keep it unique.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the job."},"required":true,"description":"Unique identifier for the job.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateJobBody"}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"Job not found."}},"tags":["Jobs"]}},"/jobs/{id}/expire":{"post":{"summary":"Expire a job","description":"Marks a published job as expired. The `status` is set to `expired` and `expiresAt` is set to the current time. Expired jobs are removed from the public board and can be reopened by publishing them again.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the job."},"required":true,"description":"Unique identifier for the job.","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"Job not found."},"409":{"description":"The job is not currently published."}},"tags":["Jobs"]}},"/jobs/{id}/pause":{"post":{"summary":"Pause a job","description":"Returns a published job to draft status. The job is removed from the public board until it is published again.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the job."},"required":true,"description":"Unique identifier for the job.","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"Job not found."},"409":{"description":"The job is not currently published."}},"tags":["Jobs"]}},"/jobs/{id}/publish":{"post":{"summary":"Publish a job","description":"Publishes a draft or expired job, making it visible on the public board. Plan and quota limits are enforced. `expiresAt` accepts an ISO 8601 string to set a new expiry, `null` to clear, or may be omitted. When omitted, a stored future expiry is preserved; a stored past expiry (e.g. set by a prior `expire` call) is cleared automatically so a republished job is never published with a stale past timestamp.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the job."},"required":true,"description":"Unique identifier for the job.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishJobBody"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"Job not found."},"409":{"description":"The job is already published, or the account's published-job quota is exhausted."}},"tags":["Jobs"]}},"/jobs/{id}":{"get":{"summary":"Retrieve a job","description":"Retrieves the details of an existing job. You only need to supply the unique job ID that was returned upon job creation.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the job."},"required":true,"description":"Unique identifier for the job.","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"404":{"description":"Job not found."}},"tags":["Jobs"]},"patch":{"summary":"Update a job","description":"Updates the specified job by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Pass `expiresAt: null` to clear the expiry.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the job."},"required":true,"description":"Unique identifier for the job.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateJobBody"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"The request was malformed."},"404":{"description":"Job not found."}},"tags":["Jobs"]},"delete":{"summary":"Delete a job","description":"Permanently deletes a job. It cannot be undone. Saved jobs, orders, and any associated search-index entries are also removed.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the job."},"required":true,"description":"Unique identifier for the job.","name":"id","in":"path"}],"responses":{"204":{"description":"Successful response."},"404":{"description":"Job not found."}},"tags":["Jobs"]}},"/jobs/batch":{"post":{"summary":"Run a batch of job operations","description":"Runs up to 100 job operations in a single request. Supported sub-operations are create (`POST`), update (`PATCH`), delete (`DELETE`), publish, pause, expire, and duplicate. Each sub-operation runs independently; the response is HTTP 200 for any well-formed batch, and the per-operation outcome is reported on each entry of the `data` array.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequestBody"}}}},"responses":{"200":{"description":"Successful response. Inspect each entry of the `data` array for the per-sub-operation status.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["batch_result"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"number"},"data":{"nullable":true},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"nullable":true}},"required":["code","message"]}},"required":["id","status"]}}},"required":["object","data"]}}}},"400":{"description":"The batch was malformed (too many sub-operations, duplicate sub-operation IDs, or invalid sub-operation shapes)."},"413":{"description":"The request body exceeded 5 MB."}},"tags":["Jobs"]}},"/jobs/search":{"post":{"summary":"Search jobs","description":"Searches your jobs using a free-text query and faceted filters. Results are returned sorted by creation date, with the most recently created jobs appearing first. Multi-value filters match jobs in any of the supplied values; range filters accept `gte` and `lte` bounds. Each filter array accepts up to 10 values.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchJobsBody"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["search_result"]},"url":{"type":"string","example":"/v1/jobs/search"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/JobSummary"}}},"required":["object","url","hasMore","nextCursor","data"]}}}},"400":{"description":"The request was malformed, or a filter array exceeded the per-array cap."},"404":{"description":"A supplied `companyId` filter does not exist or is not accessible."}},"tags":["Jobs"]}},"/media/upload":{"post":{"summary":"Upload a media file","description":"Uploads a file via the unified media dispatcher. Send a multipart form with `file` (binary) and `purpose` (one of `board_logo`, `board_hero`, `account_avatar`, `company_logo`, or `blog_image`). Optionally include `resourceType` and `resourceId` to bind the upload to an owning resource. The request is idempotent when an `Idempotency-Key` header is supplied.","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"purpose":{"type":"string","enum":["board_logo","board_hero","account_avatar","company_logo","blog_image"]},"resourceType":{"type":"string"},"resourceId":{"type":"string"}},"required":["file","purpose"]}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaUpload"}}}},"400":{"description":"The `purpose` field is invalid, or the request was otherwise malformed."},"403":{"description":"The caller lacks the permission required for the requested upload purpose."},"404":{"description":"The owning resource for the upload (`resourceId`) does not exist."},"413":{"description":"The uploaded file exceeded the 5 MB size limit."},"415":{"description":"The uploaded file's MIME type is not supported."},"429":{"description":"Too many uploads. The limit is 30 per minute per account."}},"tags":["Media"],"x-internal":true}},"/media/{id}":{"get":{"summary":"Retrieve a media file","description":"Retrieves the metadata for a media file along with a fresh signed URL valid for fifteen minutes.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the media file."},"required":true,"description":"Unique identifier for the media file.","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaGet"}}}},"404":{"description":"Media file not found."}},"tags":["Media"],"x-internal":true}},"/oauth/register":{"post":{"security":[],"summary":"Register an OAuth client","description":"Registers a new OAuth client following dynamic client registration. The plaintext `client_secret` is returned exactly once. Redirect URIs must use HTTPS, with the exception of `http://localhost` URIs in development.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicClientRegistrationRequest"}}}},"responses":{"201":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DynamicClientRegistrationResponse"}},"required":["data"]}}}}},"tags":["OAuth"],"x-internal":true}},"/usage":{"get":{"summary":"Retrieve account usage","description":"Retrieves the current usage and plan limits for your account, including the number of published jobs, the plan-enforced limit, the number of remaining slots, and the plan slug.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}}},"tags":["Usage"]}},"/public/boards/{slug}/jobs":{"get":{"security":[],"summary":"List a public board's jobs","description":"Returns a list of published jobs for the named public board. The jobs are returned sorted by creation date, with the most recently created jobs appearing first.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the public board."},"required":true,"description":"URL slug of the public board.","name":"slug","in":"path"},{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100.","example":20,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Only return jobs at the company with the given ID."},"required":false,"description":"Only return jobs at the company with the given ID.","name":"companyId","in":"query"},{"schema":{"type":"string","enum":["on_site","hybrid","remote"],"description":"Only return jobs with the given remote-work option."},"required":false,"description":"Only return jobs with the given remote-work option.","name":"remoteOption","in":"query"},{"schema":{"type":"string","enum":["full_time","part_time","contract","internship","temporary","volunteer","other"],"description":"Only return jobs with the given employment type."},"required":false,"description":"Only return jobs with the given employment type.","name":"employmentType","in":"query"},{"schema":{"type":"string","enum":["entry_level","associate","mid_level","senior","lead","principal","director","executive"],"description":"Only return jobs at the given seniority level."},"required":false,"description":"Only return jobs at the given seniority level.","name":"seniority","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicJob"}}},"required":["object","url","hasMore","nextCursor","data"]}}}},"404":{"description":"Public board not found, or the board is private."}},"tags":["Public boards"],"x-internal":true}},"/public/boards/{slug}/jobs/{jobSlug}":{"get":{"security":[],"summary":"Retrieve a public job by slug","description":"Retrieves a published job by its slug on the named public board. Only published jobs are returned.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the public board."},"required":true,"description":"URL slug of the public board.","name":"slug","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the job."},"required":true,"description":"URL slug of the job.","name":"jobSlug","in":"path"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicJob"}}}},"404":{"description":"Public board not found, or the supplied job slug does not resolve to a published job on the board."}},"tags":["Public boards"],"x-internal":true}},"/public/boards/{slug}/jobs/search":{"post":{"security":[],"summary":"Search a public board's jobs","description":"Searches published jobs on the named public board using a free-text query and faceted filters. Results are returned sorted by creation date, with the most recently created jobs appearing first. Each filter array accepts up to 10 values.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the public board."},"required":true,"description":"URL slug of the public board.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSearchJobsBody"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["search_result"]},"url":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicJob"}}},"required":["object","url","hasMore","nextCursor","data"]}}}},"400":{"description":"The request was malformed, or a filter array exceeded the per-array cap."},"404":{"description":"Public board not found, or the board is private."}},"tags":["Public boards"],"x-internal":true}},"/public/boards/{slug}/companies":{"get":{"security":[],"summary":"List a public board's companies","description":"Returns a list of companies on the named public board. The companies are returned sorted by creation date, with the most recently created companies appearing first.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the public board."},"required":true,"description":"URL slug of the public board.","name":"slug","in":"path"},{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100.","example":20,"name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyPublic"}}},"required":["object","url","hasMore","nextCursor","data"]}}}},"404":{"description":"Public board not found, or the board is private."}},"tags":["Public boards"],"x-internal":true}},"/public/boards/{slug}/companies/{companySlug}":{"get":{"security":[],"summary":"Retrieve a public company","description":"Retrieves a company on the named public board by its slug.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the public board."},"required":true,"description":"URL slug of the public board.","name":"slug","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the company."},"required":true,"description":"URL slug of the company.","name":"companySlug","in":"path"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyPublic"}}}},"404":{"description":"Public board or company not found."}},"tags":["Public boards"],"x-internal":true}},"/public/boards/{slug}/companies/search":{"post":{"security":[],"summary":"Search a public board's companies","description":"Searches companies on the named public board using a free-text query. Search results return a subset of fields — retrieve the full company resource via `GET /v1/public/boards/{slug}/companies/{companySlug}` if you need additional fields.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the public board."},"required":true,"description":"URL slug of the public board.","name":"slug","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCompaniesSearchBody"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["search_result"]},"url":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyPublic"}}},"required":["object","url","hasMore","nextCursor","data"]}}}}},"tags":["Public boards"],"x-internal":true}},"/public/boards/{slug}/companies/{companySlug}/jobs":{"get":{"security":[],"summary":"List published jobs at a public company","description":"Returns a list of published jobs for a single company on the named public board. The jobs are returned sorted by creation date, with the most recently created jobs appearing first.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the public board."},"required":true,"description":"URL slug of the public board.","name":"slug","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":150,"description":"URL slug of the company."},"required":true,"description":"URL slug of the company.","name":"companySlug","in":"path"},{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100.","example":20,"name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"nullable":true}}},"required":["object","url","hasMore","nextCursor","data"]}}}},"404":{"description":"Public board or company not found."}},"tags":["Public boards"],"x-internal":true}},"/oauth/authorize":{"get":{"security":[],"summary":"Start an OAuth authorization flow","description":"Validates an OAuth authorization request, ensures the user is signed in, and redirects to the consent page. PKCE is required and must use the `S256` challenge method; the `plain` method is rejected.","parameters":[{"schema":{"type":"string","enum":["code"],"description":"Must be `code`. The implicit and hybrid flows are not supported."},"required":true,"description":"Must be `code`. The implicit and hybrid flows are not supported.","name":"response_type","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Identifier issued for the OAuth client at registration."},"required":true,"description":"Identifier issued for the OAuth client at registration.","name":"client_id","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Where the user is redirected after consent. Must exactly match a redirect URI registered with the client."},"required":true,"description":"Where the user is redirected after consent. Must exactly match a redirect URI registered with the client.","name":"redirect_uri","in":"query"},{"schema":{"type":"string","minLength":1,"description":"PKCE code challenge derived from the code verifier (RFC 7636)."},"required":true,"description":"PKCE code challenge derived from the code verifier (RFC 7636).","name":"code_challenge","in":"query"},{"schema":{"type":"string","enum":["S256"],"description":"Must be `S256`. The `plain` method is rejected."},"required":true,"description":"Must be `S256`. The `plain` method is rejected.","name":"code_challenge_method","in":"query"},{"schema":{"type":"string","description":"Space-separated list of requested scopes."},"required":false,"description":"Space-separated list of requested scopes.","name":"scope","in":"query"},{"schema":{"type":"string","description":"Opaque value echoed back to the redirect URI. Use it to maintain state across the redirect and to mitigate CSRF."},"required":false,"description":"Opaque value echoed back to the redirect URI. Use it to maintain state across the redirect and to mitigate CSRF.","name":"state","in":"query"}],"responses":{"302":{"description":"Redirect — to the consent page on success, to sign-in if the user is unauthenticated, or to the client's `redirect_uri` if the request was rejected."}},"tags":["OAuth"],"x-internal":true},"post":{"security":[],"summary":"Submit an OAuth consent decision","description":"Receives the consent form submission from the authorization page. On approval, an authorization code is issued and the user is redirected to the client's `redirect_uri`. On denial, the user is redirected to `redirect_uri` with `error=access_denied`.","responses":{"302":{"description":"Redirect to the client's `redirect_uri`, with `code` and `state` on approval, or with `error=access_denied` on denial."}},"tags":["OAuth"],"x-internal":true}},"/oauth/token":{"post":{"security":[],"summary":"Exchange an authorization code or refresh token","description":"Issues new access and refresh tokens. Supports the `authorization_code` and `refresh_token` grant types. PKCE is required for `authorization_code`. Refresh tokens are single-use; reusing a refresh token revokes the entire token chain.","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TokenResponse"}},"required":["data"]}}}}},"tags":["OAuth"],"x-internal":true}},"/oauth/revoke":{"post":{"security":[],"summary":"Revoke an OAuth token","description":"Revokes an access or refresh token. Always returns 200, even for unknown tokens, to avoid revealing whether a given token exists.","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/RevokeRequest"}}}},"responses":{"200":{"description":"Successful response. Always returned, even for tokens that did not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"revoked":{"type":"boolean"}},"required":["revoked"]}},"required":["data"]}}}}},"tags":["OAuth"],"x-internal":true}},"/operations":{"get":{"summary":"List all operations","description":"Returns a list of asynchronous operations for your account. The operations are returned sorted by creation date, with the most recently created operations appearing first.","parameters":[{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only return operations in the given state. Repeatable: pass once per state to OR-combine values."},"required":false,"description":"Only return operations in the given state. Repeatable: pass once per state to OR-combine values.","name":"state","in":"query"},{"schema":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Only return operations of the given kind. Repeatable: pass once per kind to OR-combine values."},"required":false,"description":"Only return operations of the given kind. Repeatable: pass once per kind to OR-combine values.","name":"kind","in":"query"},{"schema":{"type":"string","description":"Only return operations on the given resource type."},"required":false,"description":"Only return operations on the given resource type.","name":"resourceType","in":"query"},{"schema":{"type":"string","description":"Only return operations on the given resource ID."},"required":false,"description":"Only return operations on the given resource ID.","name":"resourceId","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only return operations with a `createdAt` at or after this ISO 8601 datetime."},"required":false,"description":"Only return operations with a `createdAt` at or after this ISO 8601 datetime.","name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only return operations with a `createdAt` at or before this ISO 8601 datetime."},"required":false,"description":"Only return operations with a `createdAt` at or before this ISO 8601 datetime.","name":"to","in":"query"},{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50.","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/operations"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/OperationResource"}}},"required":["object","url","hasMore","nextCursor","data"]}}}}},"tags":["Operations"],"x-internal":true}},"/operations/{id}":{"get":{"summary":"Retrieve an operation","description":"Retrieves the details of an existing operation. Operations are garbage-collected thirty days after reaching a terminal state.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the operation."},"required":true,"description":"Unique identifier for the operation.","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResource"}}}}},"tags":["Operations"],"x-internal":true}},"/operations/{id}/children":{"get":{"summary":"List child operations","description":"Returns a list of child operations for a parent operation that fans out per item, such as a bulk enrichment that spawns one operation per company. Returns an empty list for operation kinds that do not fan out.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the operation."},"required":true,"description":"Unique identifier for the operation.","name":"id","in":"path"},{"schema":{"type":"string","minLength":1,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results."},"required":false,"description":"An opaque pagination cursor returned in the `nextCursor` field of a previous response. Pass it back to fetch the next page of results.","name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50."},"required":false,"description":"A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50.","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/operations"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/OperationResource"}}},"required":["object","url","hasMore","nextCursor","data"]}}}}},"tags":["Operations"],"x-internal":true}},"/operations/{id}/cancel":{"post":{"summary":"Cancel an operation","description":"Requests cancellation of an operation. A pending operation is cancelled immediately. A running operation is flagged for cancellation; the worker observes the flag at its next checkpoint. Operations that have already reached a terminal state cannot be cancelled. Cancellation does not roll back work that has already completed.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique identifier for the operation."},"required":true,"description":"Unique identifier for the operation.","name":"id","in":"path"}],"responses":{"200":{"description":"Successful response. The returned operation reflects `cancelRequested: true`; the worker observes the flag at its next checkpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResource"}}}}},"tags":["Operations"],"x-internal":true}},"/settings":{"get":{"summary":"Retrieve board settings","description":"Retrieves the settings for your board.","responses":{"200":{"description":"Successful response."}},"tags":["Settings"],"x-internal":true},"patch":{"summary":"Update board settings","description":"Updates the board settings by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Reserved fields such as `passwordProtectionEnabled`, `adsenseClientId`, and `jobAccessPaywallEnabled` must be set via their dedicated endpoints; sending them through the free-form `config` object is rejected.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchSettingsBody"}}}},"responses":{"200":{"description":"Successful response."},"400":{"description":"The request was malformed."},"403":{"description":"The account's plan tier does not permit this change. Common cases include disabling password protection on a plan that requires it, and removing Cavuno branding on a plan that does not allow it."},"409":{"description":"The supplied slug is already in use, or password protection cannot be enabled until a password is set via `POST /v1/settings/password-protection`."}},"tags":["Settings"],"x-internal":true}},"/settings/adsense":{"get":{"summary":"Retrieve AdSense configuration","description":"Retrieves the AdSense configuration for your board.","responses":{"200":{"description":"Successful response."}},"tags":["Settings"],"x-internal":true},"put":{"summary":"Update AdSense configuration","description":"Replaces the AdSense configuration for your board with the supplied values.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsAdsenseBody"}}}},"responses":{"200":{"description":"Successful response."},"400":{"description":"The supplied AdSense client ID is not in the required `ca-pub-XXXXXXXXXXXXXXXX` format."}},"tags":["Settings"],"x-internal":true}},"/settings/paywall":{"get":{"summary":"Retrieve paywall configuration","description":"Retrieves the paywall configuration for your board.","responses":{"200":{"description":"Successful response."}},"tags":["Settings"],"x-internal":true},"put":{"summary":"Update paywall configuration","description":"Replaces the paywall configuration for your board with the supplied values.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsPaywallBody"}}}},"responses":{"200":{"description":"Successful response."}},"tags":["Settings"],"x-internal":true}},"/settings/hero":{"delete":{"summary":"Delete the board hero image","description":"Removes the hero image from your board.","responses":{"204":{"description":"Successful response."},"409":{"description":"No hero image is currently set."}},"tags":["Settings"],"x-internal":true}},"/settings/password-protection":{"post":{"summary":"Enable password protection","description":"Enables password protection for your board with the supplied password. The password must be at least eight characters.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettingsPasswordProtectionBody"}}}},"responses":{"200":{"description":"Successful response."},"400":{"description":"The password is shorter than the 8-character minimum."}},"tags":["Settings"],"x-internal":true},"delete":{"summary":"Disable password protection","description":"Disables password protection on your board. Free-plan accounts cannot disable password protection and will receive a 403.","responses":{"204":{"description":"Successful response."},"403":{"description":"The account's plan tier does not permit a public board; password protection cannot be disabled."},"409":{"description":"Password protection is not currently enabled."}},"tags":["Settings"],"x-internal":true}},"/taxonomies/remote-permits":{"get":{"summary":"List remote-permit taxonomy","tags":["Taxonomies"],"description":"Returns the canonical `{type, value, label}` set accepted by the `remotePermits` field on `POST /v1/jobs` and `PATCH /v1/jobs/:id`. Public — no authentication required. Cached for 6h.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/taxonomies/remote-permits"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/RemotePermitTaxonomyEntry"}}},"required":["object","url","hasMore","nextCursor","data"]}}}}}}},"/taxonomies/remote-timezones":{"get":{"summary":"List remote-timezone taxonomy","tags":["Taxonomies"],"description":"Returns the canonical `{type, value, label}` set accepted by the `remoteTimezones` field on `POST /v1/jobs` and `PATCH /v1/jobs/:id`. Public — no authentication required. Cached for 6h.","responses":{"200":{"description":"Successful response.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","example":"/v1/taxonomies/remote-timezones"},"hasMore":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/RemoteTimezoneTaxonomyEntry"}}},"required":["object","url","hasMore","nextCursor","data"]}}}}}}}}}