Ashby/jobs

@keeb/ashby/jobsv2026.10.29.2· MIT· 2d agoBEHAVIORS

01README

Ashby jobs and requisitions: jobs, job postings, openings, locations, departments, hiring teams, approvals, job boards and templates

02Release Notes

Updated: job, job_posting, opening, department
sync now sends read parameters configured as global arguments (jobPosting includeUnpublishedJobPostings, offer excludeFormDefinition) instead of recording unpublished/filtered records as not_found; global arguments accepted by only create or only update now say so

03Behaviors12

@keeb/ashby/jobs/approvalv2026.10.29.1approval.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn lookup(entityType?: enum, entityId?: string, exactOfferVersionMatch?: boolean, syncToken?: string, max_items?: number)

List approval records and record each as a data artifact (approval.list; capped at 500 by default; writes a approval_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
entityType?	enum	no	Filter approvals by the type of entity they are associated with
entityId?	string	no	Filter approvals to only those associated with this specific entity ID
exactOfferVersionMatch?	boolean	no	Only applies when entityType is Offer and entityId is an offer version ID. By default, any version of an offer returns the offer's current approval. When true, returns the approvals that governed that specific version: its own approvals, or the earlier approval it inherited. These can be superseded (cancelled) approvals that can no longer be acted on. Keep the same value across a pagination or sync sequence.
syncToken?	string	no	A sync token to retrieve only approvals updated since the last sync. Obtained from a previous list response.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the approval_lookup record reports truncated: true.

Resources

state(infinite)— Ashby approval state

approval_lookup(infinite)— Ashby approval lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/jobs/approval-definitionv2026.10.29.1approval_definition.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn update_action(entityType: literal, entityId: string, approvalStepDefinitions: array, submitApprovalRequest?: boolean)

approvalDefinition.update: Create or update an approval definition for a specific entity that requires approval. The entity requiring approval must be within scope of an approval in Ashby that is marked as being managed by the API. Requires the `approvalsWrite` permission.

Argument	Type	Required	Description
entityType	literal	yes	The type of approval entity being updated.
entityId	string	yes	The id of the approval entity being updated, such as the id of the offer version.
approvalStepDefinitions	array	yes	An ordered list of approval steps that describes the number of required approvers at each step, as well as who is an approver at each step.
submitApprovalRequest?	boolean	no	Control whether an approval request created through this API should be immediately submitted. If false, then the approval will need to be manually submitted in the Ashby app. Defaults to false.

Resources

state(infinite)— Ashby approval definition state

approval_definition_action(infinite)— Ashby approval definition action result, one per action

@keeb/ashby/jobs/close-reasonv2026.10.29.1close_reason.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn lookup(includeArchived?: boolean, max_items?: number)

List close reason records and record each as a data artifact (closeReason.list; capped at 500 by default; writes a close_reason_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
includeArchived?	boolean	no	Whether to include archived close reasons in the response.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the close_reason_lookup record reports truncated: true.

Resources

state(infinite)— Ashby close reason state

close_reason_lookup(infinite)— Ashby close reason lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/jobs/departmentv2026.10.29.2department.ts

Global Arguments

Argument	Type	Required	Description
name?	string	no	The name of the department or team
externalName?	string	no	An alternate candidate-facing name for this department that will be used on Ashby job boards
parentId?	string	no	The id of the department's parent department. Sent by create only; department.update does not accept it.
extraData?	record	no	Key-value pairs for your own use and reference. Keys must be at most 100 characters, values at most 512 characters, and total size less than 1kb.
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a department from the model's global arguments (department.create). Creates a department. Requires the `organizationWrite` permission.

fn get(departmentId: string)

Get a department and record it as this model's state (department.info). Fetch department details by id. Requires the `organizationRead` permission.

Argument	Type	Required	Description
departmentId	string	yes	The unique id of the department whose details will be fetched

fn lookup(includeArchived?: boolean, syncToken?: string, max_items?: number)

List department records and record each as a data artifact (department.list; capped at 500 by default; writes a department_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
includeArchived?	boolean	no	Whether archived departments should be included in the response
syncToken?	string	no	A sync token to retrieve only departments updated since the last sync. Obtained from a previous list response.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the department_lookup record reports truncated: true.

fn update()

Apply the model's global arguments to the stored department (department.update). Run create or get first.

fn sync()

Sync the stored department from Ashby (department.info); records status not_found when it is gone.

fn archive(departmentId: string)

department.archive: Archives a department. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
departmentId	string	yes	The department's ID

fn move(departmentId: string, parentId?: string)

department.move: Moves a department to another parent. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
departmentId	string	yes	The department's ID
parentId?	string	no	The department parent's ID. Pass null (or omit) to move to the top level.

fn restore(departmentId: string)

department.restore: Restores a department. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
departmentId	string	yes	The department's ID

Resources

state(infinite)— Ashby department state

department_lookup(infinite)— Ashby department lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

department_action(infinite)— Ashby department action result, one per action

@keeb/ashby/jobs/hiring-teamv2026.10.29.1hiring_team.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn add_member(applicationId?: string, jobId?: string, openingId?: string, teamMemberId: string, roleId: string)

hiringTeam.addMember: Adds an Ashby user to the hiring team at the application, job, or opening level. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
applicationId?	string	no	The application to assign the user a role on
jobId?	string	no	The job to assign the user a role on
openingId?	string	no	The opening to assign the user a role on
teamMemberId	string	yes	The id of the user to assign the role to
roleId	string	yes	The id of the hiring team role to assign

fn remove_member(applicationId?: string, jobId?: string, openingId?: string, teamMemberId: string, roleId: string)

hiringTeam.removeMember: Removes an Ashby user from the hiring team at the application, job, or opening level. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
applicationId?	string	no	The application to unassign the user role from
jobId?	string	no	The job to unassign the user role from
openingId?	string	no	The opening to unassign the user role from
teamMemberId	string	yes	The id of the user to unassign the role from
roleId	string	yes	The id of the hiring team role to unassign from

Resources

state(infinite)— Ashby hiring team state

hiring_team_action(infinite)— Ashby hiring team action result, one per action

@keeb/ashby/jobs/hiring-team-rolev2026.10.29.1hiring_team_role.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn lookup(namesOnly: boolean, max_items?: number)

List hiring team role records and record each as a data artifact (hiringTeamRole.list; capped at 500 by default; writes a hiring_team_role_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
namesOnly	boolean	yes	When set to true (the default), an array of role titles is returned. When set to false, an array of objects that include the id and title of the role is returned.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the hiring_team_role_lookup record reports truncated: true.

Resources

state(infinite)— Ashby hiring team role state

hiring_team_role_lookup(infinite)— Ashby hiring team role lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/jobs/jobv2026.10.29.2job.ts

Global Arguments

Argument	Type	Required	Description
title?	string	no	The title of the job
teamId?	string	no	The id of the department or team associated with the job
locationId?	string	no	The id of the location associated with the job
defaultInterviewPlanId?	string	no	The id of the default interview plan for this job. A job cannot be opened without a default interview plan.
jobTemplateId?	string	no	The id of the job template to use for this job. Only active job templates can be used to create a job. Sent by create only; job.update does not accept it.
employmentType?	enum	no	The employment type for the job. When omitted, inherits from the job template or defaults to FullTime.
brandId?	string	no	The id of the brand to use for this job. Sent by create only; job.update does not accept it.
customRequisitionId?	string	no	The new custom requisition id for the job. Pass `null` (together with another field to update) to clear the existing value. Sent by update only; job.create does not accept it.
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a job from the model's global arguments (job.create). Creates a new job. Requires the `jobsWrite` permission.

fn get(id: string, includeUnpublishedJobPostingsIds?: boolean, expand?: array)

Get a job and record it as this model's state (job.info). Fetches details of a single job by id. Requires the `jobsRead` permission.

Argument	Type	Required	Description
id	string	yes	The id of the job to fetch
includeUnpublishedJobPostingsIds?	boolean	no	Whether to include unpublished job posting ids in the response
expand?	array	no	Expand the result with related objects. Supported values are `openings`, `location`, and `compensation`.

fn lookup(syncToken?: string, status?: array, createdAfter?: number, openedAfter?: number, openedBefore?: number, closedAfter?: number, closedBefore?: number, includeUnpublishedJobPostingsIds?: boolean, expand?: array, max_items?: number)

List job records and record each as a data artifact (job.list; capped at 500 by default; writes a job_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
syncToken?	string	no	A sync token to retrieve only jobs updated since the last sync. Obtained from a previous list response.
status?	array	no	When supplied, only jobs with the provided status(es) are returned. Accepted values are `Draft`, `Open`, `Closed`, and `Archived` (case-insensitive).
createdAfter?	number	no	Return jobs created at or after this date. Unix timestamp in milliseconds.
openedAfter?	number	no	Return jobs opened after this date. Unix timestamp in milliseconds.
openedBefore?	number	no	Return jobs opened before this date. Unix timestamp in milliseconds.
closedAfter?	number	no	Return jobs closed after this date. Unix timestamp in milliseconds.
closedBefore?	number	no	Return jobs closed before this date. Unix timestamp in milliseconds.
includeUnpublishedJobPostingsIds?	boolean	no	Whether to include unpublished job posting ids in the response
expand?	array	no	Expand the result with related objects. Supported values are `openings` and `location`.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the job_lookup record reports truncated: true.

fn update()

Apply the model's global arguments to the stored job (job.update). Run create or get first.

fn sync()

Sync the stored job from Ashby (job.info); records status not_found when it is gone.

fn search(title?: string, requisitionId?: string, limit?: number)

job.search: Searches jobs by title or custom requisition id. At least one of `title` or `requisitionId` must be provided. Requires the `jobsRead` permission.

Argument	Type	Required	Description
title?	string	no	The title (or substring of a title) of the job to search for
requisitionId?	string	no	The custom requisition id (or substring) of the job to search for
limit?	number	no	The maximum number of jobs to return. Defaults to 100 and cannot exceed 100.

fn set_status(jobId: string, status: enum, closeReasonId?: string)

job.setStatus: Sets the status of a job. When setting a job to Closed, you can optionally provide a `closeReasonId` from `closeReason.list`. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
jobId	string	yes	The unique id of the job to set the status of
status	enum	yes	The status to apply to the job
closeReasonId?	string	no	The unique id of the close reason. Only valid when setting the job status to Closed

fn start_approval_process(jobId: string, note?: object)

job.startApprovalProcess: Starts the approval process for a job. Creates an approval instance and submits it to the configured approvers. Requires the `approvalsWrite` permission.

Argument	Type	Required	Description
jobId	string	yes	The id of the job whose approval process should be started
note?	object	no	Optional note to attach to the approval request using `{ type: "text/plain" \| "text/html", value }`.

fn update_compensation(jobId: string, compensationTiers: array)

job.updateCompensation: Replaces the compensation tiers on a job. Pass an empty array to clear existing compensation. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
jobId	string	yes	The unique id of the job to update
compensationTiers	array	yes	The compensation tiers to set on the job. Pass an empty array to clear existing compensation.

fn update_compensation_settings(jobId: string, shouldShowOnJobBoard?: boolean, shouldShowOnJobPostings?: boolean, compensationTierGuideUrl?: string, compensationPhilosophy?: object)

job.updateCompensationSettings: Updates compensation display settings for a job. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
jobId	string	yes	The unique id of the job whose compensation display settings to update
shouldShowOnJobBoard?	boolean	no	Whether compensation should appear on the job board listing. Omit to leave unchanged. Pass `null` to clear the override and inherit from the brand.
shouldShowOnJobPostings?	boolean	no	Whether compensation should appear on individual job postings. Omit to leave unchanged. Pass `null` to clear the override and inherit from the brand. Note: organization-level pay transparency settings can force this on regardless.
compensationTierGuideUrl?	string	no	A URL explaining the compensation tiers. Omit to leave unchanged. Pass `null` to clear the override and inherit from the brand.
compensationPhilosophy?	object	no	The compensation philosophy as a `{ type, value }` object using `text/plain` or `text/html`. Omit to leave unchanged. Pass `null` to clear the override and inherit from the brand.

Resources

state(infinite)— Ashby job state

job_lookup(infinite)— Ashby job lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

job_action(infinite)— Ashby job action result, one per action

@keeb/ashby/jobs/job-boardv2026.10.29.1job_board.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn lookup(max_items?: number)

List job board records and record each as a data artifact (jobBoard.list; capped at 500 by default; writes a job_board_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the job_board_lookup record reports truncated: true.

Resources

state(infinite)— Ashby job board state

job_board_lookup(infinite)— Ashby job board lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/jobs/job-postingv2026.10.29.2job_posting.ts

Global Arguments

Argument	Type	Required	Description
jobId?	string	no	The id of the job to create a posting for. Sent by create only; jobPosting.update does not accept it.
title?	string	no	The title for the new job posting. If omitted, defaults to the parent job's title.
description?	object	no	An HTML block of the job posting description
workplaceType?	enum	no	The type of workplace
status?	enum	no	The initial status of the job posting. Defaults to `Draft` if omitted. A description is required when creating a `Published` posting. Sent by create only; jobPosting.update does not accept it.
isListed?	boolean	no	Whether the posting should be listed on the job board. Defaults to `true` and is forced to `false` when the parent job is confidential. Sent by create only; jobPosting.update does not accept it.
locationId?	string	no	The id of the primary location for the job posting. If omitted, the posting inherits the parent job's location.
secondaryLocationIds?	array	no	The secondary locations for the job posting.
applicationFormDefinitionId?	string	no	The id of the application form definition to use for the posting. If omitted, the organization default form is used.
suppressDescriptionOpening?	boolean	no	When true, the job description opening from the brand will be suppressed. descriptionOpening will be returned as null. Sent by update only; jobPosting.create does not accept it.
suppressDescriptionClosing?	boolean	no	When true, the job description closing from the brand will be suppressed. descriptionClosing will be returned as null. Sent by update only; jobPosting.create does not accept it.
applicationConfirmationEmailTemplateId?	string	no	The id of the email template to use for application confirmation emails on this posting. Pass `null` to clear the posting-level override and fall back to organization defaults. Sent by update only; jobPosting.create does not accept it.
jobBoardAssociations?	array	no	A full replacement of the Ashby-hosted job boards associated with this posting. Pass an empty array to remove the posting from every Ashby-hosted job board. Omit to leave associations unchanged. Sent by update only; jobPosting.create does not accept it.
includeUnpublishedJobPostings?	boolean	no	When true, allows updating unpublished (draft) job postings. Required when updating a draft posting. Sent by update only; jobPosting.create does not accept it. Also sent by sync.
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a job posting from the model's global arguments (jobPosting.create). Creates a new job posting for the specified job. Requires the `jobsWrite` permission.

fn get(jobPostingId: string, jobBoardId?: string, includeUnpublishedJobPostings?: boolean, expand?: array)

Get a job posting and record it as this model's state (jobPosting.info). Retrieve an individual job posting. Requires the `jobsRead` permission.

Argument	Type	Required	Description
jobPostingId	string	yes	The id of the job posting to return
jobBoardId?	string	no	If provided, returns the job posting data for the specified job board. If omitted, defaults to an external job board.
includeUnpublishedJobPostings?	boolean	no	If true, allows retrieving unpublished (draft) job postings. Required when fetching a draft job posting.
expand?	array	no	Choose to expand the result and include additional data for related objects.

fn lookup(location?: string, department?: string, listedOnly?: boolean, includeUnpublishedJobPostings?: boolean, jobBoardId?: string, expand?: array, max_items?: number)

List job posting records and record each as a data artifact (jobPosting.list; capped at 500 by default; writes a job_posting_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
location?	string	no	Filter by location name (case sensitive)
department?	string	no	Filter by department name (case sensitive)
listedOnly?	boolean	no	If true, filter out unlisted job postings.
includeUnpublishedJobPostings?	boolean	no	If true, include unpublished (draft) job postings in addition to published job postings.
jobBoardId?	string	no	If provided, only returns the job postings on the specified job board. If omitted, this API will return the job postings on the primary external job board.
expand?	array	no	Choose to expand the result and include additional data. Supported values: `customFields`.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the job_posting_lookup record reports truncated: true.

fn update()

Apply the model's global arguments to the stored job posting (jobPosting.update). Run create or get first.

fn sync()

Sync the stored job posting from Ashby (jobPosting.info); records status not_found when it is gone. Sends the model's includeUnpublishedJobPostings too.

fn set_custom_field_value(fieldId?: string, referenceIdentifier?: string, fieldValue?: union, jobPostingId: string)

jobPosting.setCustomFieldValue (Beta): Updates one custom field on a job posting. Returns the affected entry, including `value: null` when the field is empty. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
fieldId?	string	no	An active Job Posting custom field ID.
referenceIdentifier?	string	no	Beta. This field is in beta and may not be available for all organizations. The reference ID assigned to the object. Use the value exactly as saved.
fieldValue?	union	no	Canonical field value: text, boolean, finite number, configured option values, or ISO date or timestamp. Null clears an optional field, including when already empty.
jobPostingId	string	yes	The job posting to edit.

fn set_custom_field_values(jobPostingId: string, values: array)

jobPosting.setCustomFieldValues (Beta): Updates a nonempty batch of distinct custom fields on a job posting. Returns the affected entries in request order, including `value: null` for cleared fields. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
jobPostingId	string	yes	The job posting to edit.
values	array	yes	Values to replace, in response order. Omitted fields remain unchanged. Use null to clear an optional field.

fn set_status(jobPostingId: string, status: enum)

jobPosting.setStatus: Sets the status of a job posting. Use this to publish or unpublish a job posting. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
jobPostingId	string	yes	The unique id of the job posting to update
status	enum	yes	The status to apply to the job posting. Set to `Draft` to unpublish or `Published` to publish.

fn update_compensation(jobPostingId: string, compensationTiers?: array, includeUnpublishedJobPostings?: boolean)

jobPosting.updateCompensation: Updates compensation for an existing job posting. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
jobPostingId	string	yes	The unique id of the job posting to update
compensationTiers?	array	no	The compensation tiers to set on the job posting. Pass `null` to reset the posting to inherit compensation from the parent job.
includeUnpublishedJobPostings?	boolean	no	When true, allows updating compensation for unpublished (draft) job postings. Required when updating a draft posting.

fn update_compensation_settings(jobPostingId: string, shouldShowOnJobBoard?: boolean, shouldShowOnJobPostings?: boolean, compensationTierGuideUrl?: string, compensationPhilosophy?: object, includeUnpublishedJobPostings?: boolean)

jobPosting.updateCompensationSettings: Updates compensation display settings for a job posting. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
jobPostingId	string	yes	The unique id of the job posting whose compensation display settings to update
shouldShowOnJobBoard?	boolean	no	Whether compensation should appear on the job board listing for this posting. Omit to leave unchanged. Pass `null` to clear the override and inherit from the parent job.
shouldShowOnJobPostings?	boolean	no	Whether compensation should appear on this posting's detail page. Omit to leave unchanged. Pass `null` to clear the override and inherit from the parent job. Note: organization-level pay transparency settings can force this on regardless.
compensationTierGuideUrl?	string	no	A URL explaining the compensation tiers. Omit to leave unchanged. Pass `null` to clear the override and inherit from the parent job.
compensationPhilosophy?	object	no	The compensation philosophy as a `{ type, value }` object using `text/plain` or `text/html`. Omit to leave unchanged. Pass `null` to clear the override and inherit from the parent job.
includeUnpublishedJobPostings?	boolean	no	When true, allows updating an unpublished (draft) job posting. Required when updating a draft posting.

Resources

state(infinite)— Ashby job posting state

job_posting_lookup(infinite)— Ashby job posting lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

job_posting_action(infinite)— Ashby job posting action result, one per action

@keeb/ashby/jobs/job-templatev2026.10.29.1job_template.ts

Global Arguments

Argument	Type	Required	Description
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn lookup(syncToken?: string, expand?: array, max_items?: number)

List job template records and record each as a data artifact (jobTemplate.list; capped at 500 by default; writes a job_template_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
syncToken?	string	no	A sync token to retrieve only job templates updated since the last sync. Obtained from a previous list response.
expand?	array	no	Expand the result with related objects. Supported values are `location`.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the job_template_lookup record reports truncated: true.

Resources

state(infinite)— Ashby job template state

job_template_lookup(infinite)— Ashby job template lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/jobs/locationv2026.10.29.1location.ts

Global Arguments

Argument	Type	Required	Description
name?	string	no	The name of the location.
type?	enum	no	A Location represents an actual location that jobs and employees can be associated with. A Location Hierarchy is a grouping of locations or other location hierarchies.
address?	object	no	The address of the location.
parentLocationId?	string	no	The id of the location's parent.
isRemote?	boolean	no	Whether the location should be labeled as remote. LocationHierarchies cannot be labeled as remote.
workplaceType?	enum	no	The type of workplace. LocationHierarchies cannot be labeled with a workplaceType.
externalName?	string	no	An alternate candidate-facing name for this location used on job boards and in the API.
extraData?	record	no	Structured key-value information for your own use and reference. Do not store personally identifiable information in this field.
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a location from the model's global arguments (location.create). Creates a location or location hierarchy. Requires the `organizationWrite` permission.

fn get(locationId: string)

Get a location and record it as this model's state (location.info). Gets details for a single location by id. Requires the `organizationRead` permission.

Argument	Type	Required	Description
locationId	string	yes	The id of the location to fetch

fn lookup(syncToken?: string, includeArchived?: boolean, includeLocationHierarchy?: boolean, max_items?: number)

List location records and record each as a data artifact (location.list; capped at 500 by default; writes a location_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
syncToken?	string	no	A sync token to retrieve only locations updated since the last sync. Obtained from a previous list response.
includeArchived?	boolean	no	When true, includes archived items. Defaults to false.
includeLocationHierarchy?	boolean	no	If true, the response will include the location hierarchy (regions). Defaults to false.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the location_lookup record reports truncated: true.

fn sync()

Sync the stored location from Ashby (location.info); records status not_found when it is gone.

fn archive(locationId: string)

location.archive: Archives a location or location hierarchy. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
locationId	string	yes	The id of the location

fn move(locationId: string, parentLocationHierarchyId: string)

location.move: Moves a location in location hierarchy. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
locationId	string	yes	The id of the location
parentLocationHierarchyId	string	yes	The id of the parent location hierarchy

fn restore(locationId: string)

location.restore: Restores an archived location or location hierarchy. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
locationId	string	yes	The id of the location to restore

fn update_address(locationId: string, address?: object)

location.updateAddress: Update an address of a location or location hierarchy. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
locationId	string	yes	The id of the location
address?	object	no	The address of the location. Pass `null` to clear.

fn update_external_name(locationId: string, externalName?: string)

location.updateExternalName: Update a location's external (candidate-facing) name. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
locationId	string	yes	The id of the location
externalName?	string	no	An alternate candidate-facing name for this location used on job boards and in the API. Pass `null` to clear.

fn update_name(locationId: string, name: string)

location.updateName: Update location's name. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
locationId	string	yes	The id of the location
name	string	yes	The name of the location

fn update_workplace_type(locationId: string, workplaceType?: enum)

location.updateWorkplaceType: Update location's workplace type. Requires the `organizationWrite` permission.

Argument	Type	Required	Description
locationId	string	yes	The id of the location
workplaceType?	enum	no	The type of workplace. LocationHierarchies cannot be labeled with a workplaceType.

Resources

state(infinite)— Ashby location state

location_lookup(infinite)— Ashby location lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

location_action(infinite)— Ashby location action result, one per action

@keeb/ashby/jobs/openingv2026.10.29.2opening.ts

Global Arguments

Argument	Type	Required	Description
identifier?	string	no	The human-readable identifier of the opening
description?	string	no	The description of the opening
teamId?	string	no	The id of the department or team associated with the opening
locationIds?	array	no	The ids of the locations associated with the opening. Sent by create only; opening.update does not accept it.
jobIds?	array	no	The ids of the jobs associated with the opening. Sent by create only; opening.update does not accept it.
targetHireDate?	string	no	The date (in YYYY-MM-DD format) by which you intend to hire against this opening
targetStartDate?	string	no	The date (in YYYY-MM-DD format) by which you intend someone hired against this opening will start employment
isBackfill?	boolean	no	Whether this opening is intended to backfill a previous employee
employmentType?	enum	no	The employment type for this opening
openingState?	enum	no	The state the opening should be created in. Defaults to `Draft`. If not Draft, additional validation will be performed. Sent by create only; opening.update does not accept it.
apiKey?	string	no	Ashby API key, sent as the HTTP Basic username. Overrides the ASHBY_API_KEY environment variable. Wire with a vault.get(...) expression to source it from a vault.
apiVersion?	string	no	Pin an Ashby API version (e.g. 2026-01-01) via the Ashby-Version header. Defaults to the version the API key was created on.
onBehalfOf?	string	no	Ashby user id to act as, sent in the X-On-Behalf-Of header. Only some endpoints honor it.

fn create()

Create a opening from the model's global arguments (opening.create). Creates an opening. Requires the `jobsWrite` permission.

fn get(openingId: string)

Get a opening and record it as this model's state (opening.info). Retrieves an opening by its UUID. Requires the `jobsRead` permission.

Argument	Type	Required	Description
openingId	string	yes	The id of the opening

fn lookup(createdAfter?: number, syncToken?: string, max_items?: number)

List opening records and record each as a data artifact (opening.list; capped at 500 by default; writes a opening_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
createdAfter?	number	no	The API will return data after this date, which is the time since the unix epoch in milliseconds
syncToken?	string	no	A sync token to retrieve only openings updated since the last sync. Obtained from a previous list response.
max_items?	number	no	Stop after this many results (default 500). Whole pages are kept, so the recorded next_cursor resumes exactly after the last row. When the walk stops with rows still on offer, the opening_lookup record reports truncated: true.

fn update()

Apply the model's global arguments to the stored opening (opening.update). Run create or get first.

fn sync()

Sync the stored opening from Ashby (opening.info); records status not_found when it is gone.

fn add_job(openingId: string, jobId: string)

opening.addJob: Adds a job to an opening. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
openingId	string	yes	The id of the opening
jobId	string	yes	The id of the job to add to the opening

fn add_location(openingId: string, locationId: string)

opening.addLocation: Adds a location to an opening. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
openingId	string	yes	The id of the opening
locationId	string	yes	The id of the location to add to the opening

fn remove_job(openingId: string, jobId: string)

opening.removeJob: Removes a job from an opening. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
openingId	string	yes	The id of the opening
jobId	string	yes	The id of the job to remove from the opening

fn remove_location(openingId: string, locationId: string)

opening.removeLocation: Removes a location from an opening. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
openingId	string	yes	The id of the opening
locationId	string	yes	The id of the location to remove from the opening

fn search(identifier: string)

opening.search: Searches for openings by identifier. Requires the `jobsRead` permission.

Argument	Type	Required	Description
identifier	string	yes	The identifier of the opening you want to search for

fn set_archived(openingId: string, archive: boolean)

opening.setArchived: Sets the archived state of an opening. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
openingId	string	yes	The id of the opening you want to archive or unarchive
archive	boolean	yes	The new archived state you want to update the opening to

fn set_opening_state(openingId: string, openingState: enum, closeReasonId?: string)

opening.setOpeningState: Sets the state of an opening. Requires the `jobsWrite` permission.

Argument	Type	Required	Description
openingId	string	yes	The id of the opening you want to update
openingState	enum	yes	The new state you want to update the opening to
closeReasonId?	string	no	The id of the close reason if you are setting the state to closed

Resources

state(infinite)— Ashby opening state

opening_lookup(infinite)— Ashby opening lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

opening_action(infinite)— Ashby opening action result, one per action

04Previous Versions1

2026.10.29.1MITOct 29, 2026

Added: job, job_posting, job_template, job_board, opening, location, department, hiring_team, hiring_team_role, approval, approval_definition, close_reason

05Stats

100 / 100

Downloads

Archive size

59.8 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Docs keep secrets in a vault1/1earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License2/2earned
Verified public repository2/2earned

Repository

https://github.com/keeb/swamp-ashby

06Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64 windows · x86_64

07Labels

#ashby #ats #recruiting #jobs #postings #openings #requisitions