Can I use Ashby as a CLI?

Yes. KosmoKrator exposes a Ashby CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Ashby through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Ashby tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Ashby credentials stored?

Ashby credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Ashby MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Ashby Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Ashby KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.ashby.*. Use lua_read_doc("integrations.ashby") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Ashby workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.ashby.api_post({}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("ashby"))' --json
kosmo integrations:lua --eval 'print(docs.read("ashby.api_post"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local ashby = app.integrations.ashby
local result = ashby.api_post({})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.ashby, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.ashby.default.* or app.integrations.ashby.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Ashby, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Ashby ATS Lua API Reference

Namespace: app.integrations.ashby

Ashby’s public API uses RPC-style POST endpoints such as /candidate.list and /application.info. This integration exposes first-class tools for common recruiting workflows plus api_post for newer or less common endpoints.

Ashby uses cursor pagination and syncToken for incremental syncs on many .list endpoints. Prefer those fields over offset pagination when the endpoint supports them.

Raw API

local result = app.integrations.ashby.api_post({
  endpoint = "/candidate.list",
  body = { limit = 100 }
})

Candidates

Tools:

list_candidates
search_candidates
get_candidate
create_candidate
update_candidate
create_note
list_candidate_notes

local page = app.integrations.ashby.list_candidates({
  limit = 100,
  cursor = "opaque-cursor"
})

local matches = app.integrations.ashby.search_candidates({
  email = "person@example.test"
})

local note = app.integrations.ashby.create_note({
  candidateId = "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
  content = "Screen completed.",
  contentType = "text/plain"
})

Applications

Tools:

list_applications
get_application
create_application
update_application
list_criteria_evaluations

local app = app.integrations.ashby.get_application({
  id = "e9ed20fd-d45f-4aad-8a00-a19bfba0083e"
})

local created = app.integrations.ashby.create_application({
  candidateId = "candidate-id",
  jobId = "job-id",
  sourceId = "source-id"
})

Jobs And Openings

Tools:

list_jobs
search_jobs
get_job
create_job
update_job
list_job_postings
get_job_posting
list_openings
create_opening
list_departments
list_locations
list_sources

local postings = app.integrations.ashby.list_job_postings({
  listedOnly = true
})

local jobs = app.integrations.ashby.search_jobs({
  requisitionId = "REQ-123"
})

Set listedOnly = true before using job postings on a public career page, because Ashby’s API can return unlisted postings.

Interviews

Tools:

list_interviews
get_interview
list_interview_plans
list_interview_schedules
update_interview_schedule
list_interview_events

local schedules = app.integrations.ashby.list_interview_schedules({
  applicationId = "application-id",
  limit = 25
})

local events = app.integrations.ashby.list_interview_events({
  interviewScheduleId = "schedule-id"
})

Offers

Tools:

list_offers
get_offer
create_offer
update_offer
approve_offer

local offers = app.integrations.ashby.list_offers({
  applicationId = "application-id"
})

local approved = app.integrations.ashby.approve_offer({
  offerVersionId = "offer-version-id"
})

Users, Files, Custom Fields, Webhooks, And Assessments

Tools:

get_current_user
list_users
get_file
set_custom_field_value
list_webhooks
get_webhook
create_webhook
update_assessment

local me = app.integrations.ashby.get_current_user({})

local file = app.integrations.ashby.get_file({
  fileId = "file-id"
})

local changed = app.integrations.ashby.set_custom_field_value({
  body = {
    objectType = "Candidate",
    objectId = "candidate-id",
    fieldId = "field-id",
    value = "Example value"
  }
})

Multi-Account Usage

If multiple Ashby accounts are configured, use account-specific namespaces:

app.integrations.ashby.production.list_jobs({})
app.integrations.ashby.staging.list_candidates({ limit = 50 })

Safety Notes

Ashby API keys are sent using HTTP Basic auth with the key as username and an empty password.
Candidate, job, opening, offer, webhook, and assessment write tools may require specific Ashby API permissions.
Use example.test and dummy UUIDs in generated examples and tests.

Raw agent markdown

# Ashby ATS Lua API Reference

Namespace: `app.integrations.ashby`

Ashby's public API uses RPC-style POST endpoints such as `/candidate.list` and `/application.info`. This integration exposes first-class tools for common recruiting workflows plus `api_post` for newer or less common endpoints.

Ashby uses cursor pagination and `syncToken` for incremental syncs on many `.list` endpoints. Prefer those fields over offset pagination when the endpoint supports them.

## Raw API

```lua
local result = app.integrations.ashby.api_post({
  endpoint = "/candidate.list",
  body = { limit = 100 }
})
```

## Candidates

Tools:

- `list_candidates`
- `search_candidates`
- `get_candidate`
- `create_candidate`
- `update_candidate`
- `create_note`
- `list_candidate_notes`

```lua
local page = app.integrations.ashby.list_candidates({
  limit = 100,
  cursor = "opaque-cursor"
})

local matches = app.integrations.ashby.search_candidates({
  email = "person@example.test"
})

local note = app.integrations.ashby.create_note({
  candidateId = "e9ed20fd-d45f-4aad-8a00-a19bfba0083e",
  content = "Screen completed.",
  contentType = "text/plain"
})
```

## Applications

Tools:

- `list_applications`
- `get_application`
- `create_application`
- `update_application`
- `list_criteria_evaluations`

```lua
local app = app.integrations.ashby.get_application({
  id = "e9ed20fd-d45f-4aad-8a00-a19bfba0083e"
})

local created = app.integrations.ashby.create_application({
  candidateId = "candidate-id",
  jobId = "job-id",
  sourceId = "source-id"
})
```

## Jobs And Openings

Tools:

- `list_jobs`
- `search_jobs`
- `get_job`
- `create_job`
- `update_job`
- `list_job_postings`
- `get_job_posting`
- `list_openings`
- `create_opening`
- `list_departments`
- `list_locations`
- `list_sources`

```lua
local postings = app.integrations.ashby.list_job_postings({
  listedOnly = true
})

local jobs = app.integrations.ashby.search_jobs({
  requisitionId = "REQ-123"
})
```

Set `listedOnly = true` before using job postings on a public career page, because Ashby's API can return unlisted postings.

## Interviews

Tools:

- `list_interviews`
- `get_interview`
- `list_interview_plans`
- `list_interview_schedules`
- `update_interview_schedule`
- `list_interview_events`

```lua
local schedules = app.integrations.ashby.list_interview_schedules({
  applicationId = "application-id",
  limit = 25
})

local events = app.integrations.ashby.list_interview_events({
  interviewScheduleId = "schedule-id"
})
```

## Offers

Tools:

- `list_offers`
- `get_offer`
- `create_offer`
- `update_offer`
- `approve_offer`

```lua
local offers = app.integrations.ashby.list_offers({
  applicationId = "application-id"
})

local approved = app.integrations.ashby.approve_offer({
  offerVersionId = "offer-version-id"
})
```

## Users, Files, Custom Fields, Webhooks, And Assessments

Tools:

- `get_current_user`
- `list_users`
- `get_file`
- `set_custom_field_value`
- `list_webhooks`
- `get_webhook`
- `create_webhook`
- `update_assessment`

```lua
local me = app.integrations.ashby.get_current_user({})

local file = app.integrations.ashby.get_file({
  fileId = "file-id"
})

local changed = app.integrations.ashby.set_custom_field_value({
  body = {
    objectType = "Candidate",
    objectId = "candidate-id",
    fieldId = "field-id",
    value = "Example value"
  }
})
```

## Multi-Account Usage

If multiple Ashby accounts are configured, use account-specific namespaces:

```lua
app.integrations.ashby.production.list_jobs({})
app.integrations.ashby.staging.list_candidates({ limit = 50 })
```

## Safety Notes

- Ashby API keys are sent using HTTP Basic auth with the key as username and an empty password.
- Candidate, job, opening, offer, webhook, and assessment write tools may require specific Ashby API permissions.
- Use `example.test` and dummy UUIDs in generated examples and tests.

Metadata-derived Lua example

local result = app.integrations.ashby.api_post({})
print(result)

Functions

api_post Write

Call any Ashby RPC API endpoint.

Lua path: app.integrations.ashby.api_post
Full name: ashby.ashby_api_post

Parameter	Type	Required	Description
No parameters.

get_current_user Read

Get the profile of the currently authenticated Ashby user. Use this to verify API access and see user details.

Lua path: app.integrations.ashby.get_current_user
Full name: ashby.ashby_get_current_user

Parameter	Type	Required	Description
No parameters.

list_users Read

List Ashby users.

Lua path: app.integrations.ashby.list_users
Full name: ashby.ashby_list_users

Parameter	Type	Required	Description
No parameters.

list_candidates Read

List candidates from Ashby with cursor pagination and sync tokens. Use ashby_search_candidates for name or email lookups.

Lua path: app.integrations.ashby.list_candidates
Full name: ashby.ashby_list_candidates

Parameter	Type	Required	Description
`createdAfter`	integer	no	Return candidates created after this Unix epoch timestamp in milliseconds.
`cursor`	string	no	Pagination cursor.
`syncToken`	string	no	Incremental sync token.
`limit`	integer	no	Maximum number of candidates to return (max/default 100).

search_candidates Read

Search candidates by name or email.

Lua path: app.integrations.ashby.search_candidates
Full name: ashby.ashby_search_candidates

Parameter	Type	Required	Description
No parameters.

get_candidate Read

Get a single candidate.

Lua path: app.integrations.ashby.get_candidate
Full name: ashby.ashby_get_candidate

Parameter	Type	Required	Description
No parameters.

create_candidate Write

Create a candidate.

Lua path: app.integrations.ashby.create_candidate
Full name: ashby.ashby_create_candidate

Parameter	Type	Required	Description
No parameters.

update_candidate Write

Update a candidate.

Lua path: app.integrations.ashby.update_candidate
Full name: ashby.ashby_update_candidate

Parameter	Type	Required	Description
No parameters.

create_note Write

Create a note in Ashby attached to a candidate, application, or job. Notes are visible to the hiring team and appear in activity feeds.

Lua path: app.integrations.ashby.create_note
Full name: ashby.ashby_create_note

Parameter	Type	Required	Description
`candidateId`	string	yes	The candidate UUID.
`content`	string	yes	The note content (supports plain text).
`contentType`	string	no	Content type, such as text/plain or text/html.

list_candidate_notes Read

List notes for a candidate.

Lua path: app.integrations.ashby.list_candidate_notes
Full name: ashby.ashby_list_candidate_notes

Parameter	Type	Required	Description
No parameters.

list_applications Read

List job applications in Ashby. Returns applications with candidate info, status, and associated job. Use filters to narrow by job or status.

Lua path: app.integrations.ashby.list_applications
Full name: ashby.ashby_list_applications

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of applications to return (default: 100).
`offset`	integer	no	Number of results to skip for pagination.
`job_id`	string	no	Filter applications by job ID.
`status`	string	no	Filter by application status (e.g., "hired", "rejected", "active").

get_application Read

Get detailed information about a specific job application in Ashby, including candidate details, status, and evaluation data.

Lua path: app.integrations.ashby.get_application
Full name: ashby.ashby_get_application

Parameter	Type	Required	Description
`id`	string	yes	The application ID.

create_application Write

Create an application for a candidate and job.

Lua path: app.integrations.ashby.create_application
Full name: ashby.ashby_create_application

Parameter	Type	Required	Description
No parameters.

update_application Write

Update an application.

Lua path: app.integrations.ashby.update_application
Full name: ashby.ashby_update_application

Parameter	Type	Required	Description
No parameters.

list_criteria_evaluations Read

List AI criteria evaluations for an application.

Lua path: app.integrations.ashby.list_criteria_evaluations
Full name: ashby.ashby_list_criteria_evaluations

Parameter	Type	Required	Description
No parameters.

list_jobs Read

List job postings in Ashby. Returns open and closed positions with department, location, and application count. Filter by status to find active openings.

Lua path: app.integrations.ashby.list_jobs
Full name: ashby.ashby_list_jobs

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of jobs to return (default: 100).
`offset`	integer	no	Number of results to skip for pagination.
`status`	string	no	Filter by job status (e.g., "open", "closed", "draft").

search_jobs Read

Search jobs.

Lua path: app.integrations.ashby.search_jobs
Full name: ashby.ashby_search_jobs

Parameter	Type	Required	Description
No parameters.

get_job Read

Get detailed information about a specific job in Ashby, including full description, requirements, compensation, and hiring team.

Lua path: app.integrations.ashby.get_job
Full name: ashby.ashby_get_job

Parameter	Type	Required	Description
`id`	string	yes	The job ID.

create_job Write

Create a job.

Lua path: app.integrations.ashby.create_job
Full name: ashby.ashby_create_job

Parameter	Type	Required	Description
No parameters.

update_job Write

Update a job.

Lua path: app.integrations.ashby.update_job
Full name: ashby.ashby_update_job

Parameter	Type	Required	Description
No parameters.

list_job_postings Read

List job postings.

Lua path: app.integrations.ashby.list_job_postings
Full name: ashby.ashby_list_job_postings

Parameter	Type	Required	Description
No parameters.

get_job_posting Read

Get a job posting.

Lua path: app.integrations.ashby.get_job_posting
Full name: ashby.ashby_get_job_posting

Parameter	Type	Required	Description
No parameters.

list_openings Read

List openings.

Lua path: app.integrations.ashby.list_openings
Full name: ashby.ashby_list_openings

Parameter	Type	Required	Description
No parameters.

create_opening Write

Create an opening.

Lua path: app.integrations.ashby.create_opening
Full name: ashby.ashby_create_opening

Parameter	Type	Required	Description
No parameters.

list_departments Read

List departments/teams.

Lua path: app.integrations.ashby.list_departments
Full name: ashby.ashby_list_departments

Parameter	Type	Required	Description
No parameters.

list_locations Read

List locations.

Lua path: app.integrations.ashby.list_locations
Full name: ashby.ashby_list_locations

Parameter	Type	Required	Description
No parameters.

list_sources Read

List sources.

Lua path: app.integrations.ashby.list_sources
Full name: ashby.ashby_list_sources

Parameter	Type	Required	Description
No parameters.

list_interviews Read

List scheduled interviews in Ashby. Returns interview details with date, time, interviewers, and associated application. Filter by application to see interviews for a specific candidate.

Lua path: app.integrations.ashby.list_interviews
Full name: ashby.ashby_list_interviews

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of interviews to return (default: 100).
`offset`	integer	no	Number of results to skip for pagination.
`application_id`	string	no	Filter interviews by application ID.

get_interview Read

Get detailed information about a specific interview in Ashby, including scheduled time, interviewers, feedback, and scorecards.

Lua path: app.integrations.ashby.get_interview
Full name: ashby.ashby_get_interview

Parameter	Type	Required	Description
`id`	string	yes	The interview ID.

list_interview_plans Read

List interview plans.

Lua path: app.integrations.ashby.list_interview_plans
Full name: ashby.ashby_list_interview_plans

Parameter	Type	Required	Description
No parameters.

list_interview_schedules Read

List interview schedules.

Lua path: app.integrations.ashby.list_interview_schedules
Full name: ashby.ashby_list_interview_schedules

Parameter	Type	Required	Description
No parameters.

update_interview_schedule Write

Update an interview schedule.

Lua path: app.integrations.ashby.update_interview_schedule
Full name: ashby.ashby_update_interview_schedule

Parameter	Type	Required	Description
No parameters.

list_interview_events Read

List interview events.

Lua path: app.integrations.ashby.list_interview_events
Full name: ashby.ashby_list_interview_events

Parameter	Type	Required	Description
No parameters.

list_offers Read

List offers.

Lua path: app.integrations.ashby.list_offers
Full name: ashby.ashby_list_offers

Parameter	Type	Required	Description
No parameters.

get_offer Read

Get an offer.

Lua path: app.integrations.ashby.get_offer
Full name: ashby.ashby_get_offer

Parameter	Type	Required	Description
No parameters.

create_offer Write

Create an offer.

Lua path: app.integrations.ashby.create_offer
Full name: ashby.ashby_create_offer

Parameter	Type	Required	Description
No parameters.

update_offer Write

Update an offer.

Lua path: app.integrations.ashby.update_offer
Full name: ashby.ashby_update_offer

Parameter	Type	Required	Description
No parameters.

approve_offer Write

Approve an offer.

Lua path: app.integrations.ashby.approve_offer
Full name: ashby.ashby_approve_offer

Parameter	Type	Required	Description
No parameters.

get_file Read

Retrieve a file URL.

Lua path: app.integrations.ashby.get_file
Full name: ashby.ashby_get_file

Parameter	Type	Required	Description
No parameters.

set_custom_field_value Write

Set a custom field value.

Lua path: app.integrations.ashby.set_custom_field_value
Full name: ashby.ashby_set_custom_field_value

Parameter	Type	Required	Description
No parameters.

list_webhooks Read

List webhook settings.

Lua path: app.integrations.ashby.list_webhooks
Full name: ashby.ashby_list_webhooks

Parameter	Type	Required	Description
No parameters.

get_webhook Read

Get a webhook setting.

Lua path: app.integrations.ashby.get_webhook
Full name: ashby.ashby_get_webhook

Parameter	Type	Required	Description
No parameters.

create_webhook Write

Create a webhook setting.

Lua path: app.integrations.ashby.create_webhook
Full name: ashby.ashby_create_webhook

Parameter	Type	Required	Description
No parameters.

update_assessment Write

Update assessment status/results.

Lua path: app.integrations.ashby.update_assessment
Full name: ashby.ashby_update_assessment

Parameter	Type	Required	Description
No parameters.