Ashby/interviews

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

01README

Ashby interviewing: interviews, interview plans and stages, schedules and events, briefings, interviewer pools, feedback forms, take-home assignments and notetaker transcripts

02Release Notes

Updated: interview_schedule
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/interviews/feedback-form-definitionv2026.10.29.1feedback_form_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 get(feedbackFormDefinitionId: string)

Get a feedback form definition and record it as this model's state (feedbackFormDefinition.info). Returns a single feedback form by id Requires one of the `feedbackFormDefinitionsRead` or `hiringProcessMetadataRead` permissions.

Argument	Type	Required	Description
feedbackFormDefinitionId	string	yes	The unique id of the feedback form you'd like to fetch.

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

List feedback form definition records and record each as a data artifact (feedbackFormDefinition.list; capped at 500 by default; writes a feedback_form_definition_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 feedback form definitions updated since the last sync. Obtained from a previous list response.
includeArchived?	boolean	no	Whether to include archived feedback form definitions in the results.
sharedOnly?	boolean	no	When true, return only reusable shared feedback forms, excluding forms local to an Interview or activity. Defaults to false. Use the default includeArchived:false to find active shared forms.
includeVisibilityConditions?	boolean	no	This feature is in beta and may not be available for all organizations. When true, each form field's visibilityCondition tree is included. Defaults to false on this endpoint to keep responses small.
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 feedback_form_definition_lookup record reports truncated: true.

fn sync()

Sync the stored feedback form definition from Ashby (feedbackFormDefinition.info); records status not_found when it is gone.

Resources

state(infinite)— Ashby feedback form definition state

feedback_form_definition_lookup(infinite)— Ashby feedback form definition lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/interviews/interviewv2026.10.29.1interview.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 get(id: string)

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

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

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

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

Argument	Type	Required	Description
includeArchived?	boolean	no	When true, includes archived interviews in the response. Defaults to false.
includeNonSharedInterviews?	boolean	no	If true, interviews that are associated with specific jobs will be included in the response. Shared interviews that are not associated with a specific job can be scheduled for applications to any job. Interviews that are not shared can only be scheduled for applications to the job they are associated with. Defaults to false.
excludeArchivedScheduleTemplateInterviews?	boolean	no	If true, interviews local to archived schedule templates are omitted from the response. This parameter only has an effect when `includeNonSharedInterviews` is also set to true. Shared interviews (not associated with any schedule template) are always included regardless of this setting. Defaults to false.
syncToken?	string	no	A sync token to retrieve only interviews 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 interview_lookup record reports truncated: true.

fn sync()

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

Resources

state(infinite)— Ashby interview state

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

@keeb/ashby/interviews/interview-briefingv2026.10.29.1interview_briefing.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 get(interviewEventId: string, expand?: array)

Get a interview briefing and record it as this model's state (interviewBriefing.info). Fetch the briefing data for an interview event. Returns the application, interview, per-interviewer status, and the feedback form definition id needed to render an interviewer-facing briefing or to submit feedback via `applicationFeedback.submit`. Requires the `interviewsRead` permission.

Argument	Type	Required	Description
interviewEventId	string	yes	The id of the interview event whose briefing should be returned.
expand?	array	no	Choose to expand the result and include additional data for related objects.

Resources

state(infinite)— Ashby interview briefing state

@keeb/ashby/interviews/interview-eventv2026.10.29.1interview_event.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(interviewScheduleId: string, expand?: array, syncToken?: string, createdAfter?: number, max_items?: number)

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

Argument	Type	Required	Description
interviewScheduleId	string	yes	The unique ID of the interview schedule, for which to list interview events
expand?	array	no	Choose to expand the result and include additional data for related objects.
syncToken?	string	no	A sync token to retrieve only events updated since the last sync. Obtained from a previous list response.
createdAfter?	number	no	Return only events created after this date, expressed as milliseconds since the Unix epoch.
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 interview_event_lookup record reports truncated: true.

Resources

state(infinite)— Ashby interview event state

interview_event_lookup(infinite)— Ashby interview event lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/interviews/interview-planv2026.10.29.1interview_plan.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, syncToken?: string, max_items?: number)

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

Argument	Type	Required	Description
includeArchived?	boolean	no	Whether archived interview plans should be included in the response
syncToken?	string	no	A sync token to retrieve only interview plans 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 interview_plan_lookup record reports truncated: true.

Resources

state(infinite)— Ashby interview plan state

interview_plan_lookup(infinite)— Ashby interview plan lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/interviews/interview-schedulev2026.10.29.2interview_schedule.ts

Global Arguments

Argument	Type	Required	Description
applicationId?	string	no	The id of the application for this interview schedule. Sent by create only; interviewSchedule.update does not accept it.
interviewEvents?	array	no	The list of events that make up this interview schedule. Sent by create only; interviewSchedule.update does not accept it.
interviewEvent?	union	no	An event (or array of events) on the interview schedule to create or update. To update an event, its `interviewEventId` must be included in the request. Sent by update only; interviewSchedule.create does not accept it.
interviewEventIdToCancel?	union	no	The id (or array of ids) of interview events to cancel. Sent by update only; interviewSchedule.create does not accept it.
allowFeedbackDeletion?	boolean	no	By default, events with submitted feedback cannot be cancelled because cancellation deletes the associated feedback. Pass `true` to allow cancelling events with submitted feedback. Sent by update only; interviewSchedule.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 interview schedule from the model's global arguments (interviewSchedule.create). Create a scheduled interview in Ashby. Requires the `interviewsWrite` permission.

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

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

Argument	Type	Required	Description
applicationId?	string	no	The id of the application, for which to fetch interview schedules
interviewStageId?	string	no	The id of the interview stage, for which to fetch interview schedules
createdAfter?	number	no	The API will return data after this date, which is the time since the unix epoch in milliseconds
syncToken?	string	no	An opaque token representing the last time the data was successfully synced from the API. A new, updated one is returned after successfully fetching the last page of data.
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 interview_schedule_lookup record reports truncated: true.

fn update()

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

fn cancel(id: string, allowReschedule?: boolean)

interviewSchedule.cancel: Cancel an interview schedule by id. Requires the `interviewsWrite` permission.

Argument	Type	Required	Description
id	string	yes	The id of the interview schedule to cancel
allowReschedule?	boolean	no	Whether or not this interview schedule can be rescheduled.

Resources

state(infinite)— Ashby interview schedule state

interview_schedule_lookup(infinite)— Ashby interview schedule lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

interview_schedule_action(infinite)— Ashby interview schedule action result, one per action

@keeb/ashby/interviews/interview-stagev2026.10.29.1interview_stage.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 get(interviewStageId: string)

Get a interview stage and record it as this model's state (interviewStage.info). Retrieves detailed information about a specific interview stage by its ID. Requires the `interviewsRead` permission.

Argument	Type	Required	Description
interviewStageId	string	yes	The id of the interview stage to retrieve

fn lookup(interviewPlanId: string, max_items?: number)

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

Argument	Type	Required	Description
interviewPlanId	string	yes	The id of the interview plan to list stages for
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 interview_stage_lookup record reports truncated: true.

fn sync()

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

Resources

state(infinite)— Ashby interview stage state

interview_stage_lookup(infinite)— Ashby interview stage lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/interviews/interview-stage-groupv2026.10.29.1interview_stage_group.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 interview stage group records and record each as a data artifact (interviewStageGroup.list; capped at 500 by default; writes a interview_stage_group_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 interview_stage_group_lookup record reports truncated: true.

Resources

state(infinite)— Ashby interview stage group state

interview_stage_group_lookup(infinite)— Ashby interview stage group lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

@keeb/ashby/interviews/interviewer-poolv2026.10.29.1interviewer_pool.ts

Global Arguments

Argument	Type	Required	Description
title?	string	no	The title of the interviewer pool
requiresTraining?	boolean	no	Whether the interviewer pool requires training
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 interviewer pool from the model's global arguments (interviewerPool.create). Create an interviewer pool. Requires the `hiringProcessMetadataWrite` permission.

fn get(interviewerPoolId: string)

Get a interviewer pool and record it as this model's state (interviewerPool.info). Get information about an interviewer pool. Requires the `hiringProcessMetadataRead` permission.

Argument	Type	Required	Description
interviewerPoolId	string	yes	The id of the interviewer pool

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

List interviewer pool records and record each as a data artifact (interviewerPool.list; capped at 500 by default; writes a interviewer_pool_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 interviewer pools updated since the last sync. Obtained from a previous list response.
includeArchivedPools?	boolean	no	When true, includes archived pools. Defaults to false.
includeArchivedTrainingStages?	boolean	no	When true, includes archived training stages. Defaults to true.
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 interviewer_pool_lookup record reports truncated: true.

fn update()

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

fn sync()

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

fn add_user(interviewerPoolId: string, userId: string, interviewerPoolTrainingPathStageId?: string)

interviewerPool.addUser: Add a user to an interviewer pool. Requires the `hiringProcessMetadataWrite` permission.

Argument	Type	Required	Description
interviewerPoolId	string	yes	The id of the interviewer pool
userId	string	yes	The id of the user to add to the interviewer pool
interviewerPoolTrainingPathStageId?	string	no	The id of the training path stage to add the user to. If this is not provided, the user will be added as a fully qualified member of the pool.

fn archive(interviewerPoolId: string)

interviewerPool.archive: Archives an interviewer pool. Requires the `hiringProcessMetadataWrite` permission.

Argument	Type	Required	Description
interviewerPoolId	string	yes	The id of the interviewer pool to archive

fn remove_user(interviewerPoolId: string, userId: string)

interviewerPool.removeUser: Remove a user from an interviewer pool. Requires the `hiringProcessMetadataWrite` permission.

Argument	Type	Required	Description
interviewerPoolId	string	yes	The id of the interviewer pool
userId	string	yes	The id of the user to remove from the interviewer pool

fn restore(interviewerPoolId: string)

interviewerPool.restore: Restores an archived interviewer pool. Requires the `hiringProcessMetadataWrite` permission.

Argument	Type	Required	Description
interviewerPoolId	string	yes	The id of the interviewer pool to restore

Resources

state(infinite)— Ashby interviewer pool state

interviewer_pool_lookup(infinite)— Ashby interviewer pool lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

interviewer_pool_action(infinite)— Ashby interviewer pool action result, one per action

@keeb/ashby/interviews/job-interview-planv2026.10.29.1job_interview_plan.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 get(jobId: string)

Get a job interview plan and record it as this model's state (jobInterviewPlan.info). Returns a job's interview plan, including activities and interviews that need to be scheduled at each stage. Requires the `jobsRead` permission.

Argument	Type	Required	Description
jobId	string	yes	The id of the job to fetch an interview plan for

Resources

state(infinite)— Ashby job interview plan state

@keeb/ashby/interviews/notetaker-transcriptv2026.10.29.1notetaker_transcript.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 get(notetakerTranscriptId: string)

Get a notetaker transcript and record it as this model's state (notetakerTranscript.info). Fetches metadata and a pre-signed download URL for an AI Notetaker transcript recording. Requires the `notetakerRead` permission.

Argument	Type	Required	Description
notetakerTranscriptId	string	yes	The unique id of the notetaker transcript to fetch

fn sync()

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

Resources

state(infinite)— Ashby notetaker transcript state

@keeb/ashby/interviews/take-home-assignmentv2026.10.29.1take_home_assignment.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 get(takeHomeAssignmentId: string, expand?: array)

Get a take home assignment and record it as this model\'s state (takeHomeAssignment.info). Retrieves a single take-home assignment by id and links it to its interview definition through `interviewId`. Pass `expand: ["interview"]` to include that definition. Returns `take_home_assignment_not_found` if the id does not exist or is not visible to the caller. Requires the `interviewsRead` permission.

Argument	Type	Required	Description
takeHomeAssignmentId	string	yes	The id of the take-home assignment
expand?	array	no	Choose to expand the result and include the related interview definition.

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

List take home assignment records and record each as a data artifact (takeHomeAssignment.list; capped at 500 by default; writes a take_home_assignment_lookup record with the coverage of the walk and the sync token)

Argument	Type	Required	Description
applicationId?	string	no	Filter to take-home assignments for this application
candidateId?	string	no	Filter to take-home assignments for this candidate
expand?	array	no	Choose to expand results and include related interview definitions.
syncToken?	string	no	An opaque token representing the last time the data was successfully synced from the API. A new, updated one is returned after successfully fetching the last page of data.
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 take_home_assignment_lookup record reports truncated: true.

fn sync()

Sync the stored take home assignment from Ashby (takeHomeAssignment.info); records status not_found when it is gone.

Resources

state(infinite)— Ashby take home assignment state

take_home_assignment_lookup(infinite)— Ashby take home assignment lookup coverage — whether the walk exhausted the collection, and the sync token for the next one

04Previous Versions1

2026.10.29.1MITOct 29, 2026

Added: interview, interview_plan, interview_stage, interview_stage_group, interview_schedule, interview_event, interview_briefing, interviewer_pool, job_interview_plan, feedback_form_definition, take_home_assignment, notetaker_transcript

05Stats

100 / 100

Downloads

Archive size

39.7 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 #interviews #scheduling #feedback