Authenticate using HTTP Basic Auth; send your Ashby API key as the username and leave the password field empty on all requests to https://api.ashbyhq.com/
To list all candidates, POST to https://api.ashbyhq.com/candidate.list with an empty JSON body or pagination parameters; this endpoint requires the candidatesRead permission on your API key
To create a candidate, POST to https://api.ashbyhq.com/candidate.create with fields such as name, email, and optionally phoneNumber, linkedInUrl, and socialLinks; requires candidatesWrite permission
To add a tag to a candidate, POST to https://api.ashbyhq.com/candidate.addTag with the candidateId and tagId; tags must exist in Ashby before they can be applied
To upload a file (e.g., resume) for a candidate, POST to https://api.ashbyhq.com/candidate.uploadFile as multipart/form-data with the candidateId and file fields; requires candidatesWrite permission
Use pagination parameters (cursor, limit) on list endpoints and follow the nextCursor in responses until it is null
Known gotchas
Ashby's API uses POST for all operations including reads (e.g., candidate.list is a POST, not a GET); sending a GET request to a list endpoint will return a 404 or method-not-allowed error
API key permissions are configured per key in the Ashby Settings; a key without candidatesWrite will silently fail or return a permission error on create and update operations
The Ashby API is under active development; check the official documentation at developers.ashbyhq.com for schema changes before relying on undocumented fields
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp