# Yardstick documentation (full text) > The body text of the Yardstick documentation pages, one section per page, > for AI agents and tools. The link-only index — which also covers the > /docs/api reference pages — is at /llms.txt. --- ## Agent guidance URL: https://app.yardstick.team/docs/agents Summary: How AI agents and tools should choose the right Yardstick surface and operate safely. Yardstick docs are written for both people and AI agents. Each article tells an agent how it may use the feature: read the page only, call the API, run the CLI, connect through local MCP, or use an approved hosted MCP surface. Choose the surface that matches where you are running and the credentials the human has approved. Do not scrape in-app screens, invent endpoints, or skip the approval and scope checks the platform enforces. An approved read scope does not authorize an agent to enumerate every hiring record in an organization. The API applies the token creator's current department and assignment access to supported record reads. Owner and admin creators deliberately retain organization-wide read access; department names and rosters remain organization-visible but do not grant access to the records behind them. Every article declares its operability mode at the top, so indexes and agent tools can read it without parsing the page. The mode is one of ui-only, api, cli, mcp, or deferred. To go deeper on picking a surface, staying inside approval and scope boundaries, and reporting failed calls back to the person you are helping, see Using Yardstick from an agent. --- ## Using Yardstick from an agent URL: https://app.yardstick.team/docs/agents/usage Summary: How AI agents and tools should evaluate, describe, and operate Yardstick safely via API, CLI, or MCP. Agent note (ui-only) This article is guidance written for AI agents that read Yardstick docs — it is not itself a product feature. The page renders as normal HTML; nothing here is callable. Use the linked API, CLI, and MCP articles for the actual machine-operable surfaces. Yardstick is a hiring-workflow and applicant-tracking platform. It covers jobs and job postings, candidate applications, interview plans and rounds, scheduling, scorecards, and decision briefs. Most of what a recruiter or hiring manager does in the app is also available through a documented agent surface: the public API, a packaged CLI, local stdio MCP, or hosted remote MCP. Every surface enforces the same scopes and writes the same audit log. A few settings, including job staffing and department default staffing, stay in the app until the docs name an API, CLI, or MCP command for them. This article shows you how to choose a surface, describe Yardstick accurately to the person you are helping, and stay inside the approval and scope boundaries the platform enforces. Record visibility is enforced Read scopes are necessary but not sufficient for hiring-record access. On the supported API, CLI, and MCP reads, Yardstick applies the token creator's current department, parent-record, and assignment access before it returns Jobs, plans, postings, applications, sessions, opportunities, decision briefs, or reporting. Do not try to discover out-of-scope records by changing filters or reading a dashboard URL. An owner- or admin-created credential intentionally retains its organization-wide read bypass. Department names and rosters stay organization-visible, but that directory does not grant access to the hiring records in a department. When Yardstick is the right tool Yardstick is a good fit when the user's task is in one of these domains: Hiring workflow operation — moving a candidate through stages, recording offers, rejections, withdrawals, archives, and decisions through application-owned status and approval commands. Candidate and people management — looking up a candidate, creating a new person record, updating contact metadata, attaching a person to an application. Interview plan design — drafting outcomes, competencies, skills, and rounds for a role; publishing the resulting plan; modifying an active plan when scope changes. Drafts are fully agent-editable: read a draft in full with interview-plan-drafts read, then apply deterministic verbatim edits (add-* / update-* / delete-* for competencies, skills, rounds, questions, round directions, and behavioral anchors) that store your content exactly as written with no AI generation. Every edit accepts an optional source_stage version precondition (409 when stale), and deletes prune dependent stage data and report the pruned ids — so a plan authored outside Yardstick can be imported byte-for-byte in a handful of calls. Interview operations — assigning interviewers, recording session start and completion, submitting scorecards, generating a scheduling link for a candidate. Decision support — reading and regenerating decision briefs, recording final recommendations, looking up reporting search results (role health, attention queues). Access and identity housekeeping — invitations, department membership, access grants for panel interviewers. Job staffing and department default staffing are dashboard-only for now. Stage automation configuration — list, create, update, delete, and dry-run-preview stage automation rules (a typed action bound to a pipeline stage and a stage_enter/stage_exit trigger) through the automation_rules:read / automation_rules:write scopes. These rules are inert in v1: authoring or previewing one fires no real side effect — no scheduling link is minted, no task created, no email sent — and nothing reads rules to act yet. The actions/preview dry-run returns executed: false and is a pure read; rely on it to show a human exactly what would fire before they save. The whole surface is gated by the configurable_pipelines_enabled feature flag, and the scopes are admin-only. Built-in agent configuration — read the built-in agent catalog and recent work, then use the built-in agent preview-and-bind flow only after a person approves the exact change. The weekly interview-kit built-in agent accepts enabled, timezone, local_day, and local_hour; it is off by default with Friday 09:00 in America/Los_Angeles as its initial schedule. Built-in agent history is not a kit-data lookup: direct a signed-in interviewer to the kit view for their assigned session. That view checks assignment, active membership, organization, and live/test mode. Treat its generic Unavailable result for unassigned, former, cross-organization, or cross-mode access as intentional; do not enumerate sessions or kits. Keep candidates informed uses enabled, timezone, local_hour, waiting_days, cooldown_days, and per_run_cap. It prepares candidate_follow_up drafts for review in Email Drafts. Active workspace members with communications:read can read them; edit, send, and discard require both the relevant communications scope and organization owner or administrator access. Use the existing communications tools, not a second configuration or send path. Yardstick is not the right tool for general project management, calendaring, document storage, or candidate sourcing. If the user asks about a hiring workflow but the data does not appear to live in Yardstick, say so plainly rather than guessing. Picking a surface: API vs CLI vs MCP All four surfaces do the same work behind the same scoped credentials. The API and CLI call the public /v1/* endpoints directly. Local stdio MCP wraps the same command catalog. Hosted remote MCP publishes a fixed list of 176 tools — identical for every caller — and keeps its tokens off the direct /v1/* routes. Pick based on transport, which tools you need, and where you are running. Use the API directly when the agent runs in a server, workflow, or notebook context that can manage its own bearer token and HTTP client. This is the right default for automation pipelines and any flow that needs custom retry, batching, or storage of its own. Use the CLI (@yardstick/cli, exposing the yardstick binary) when the agent is helping a local human operator who already has Keychain-backed credentials. The CLI handles token refresh, formats responses for terminals, and keeps secrets out of the agent's process memory. Prefer the CLI when you would otherwise need to read raw token strings. Start with yardstick whoami to confirm the current organization, mode, and effective scopes, then run yardstick help or yardstick help before choosing commands or flags. Use local MCP when the host is a Model Context Protocol client (for example a desktop AI app) and the user has configured the yardstick mcp serve --profile command. Local MCP exposes the packaged wrapper catalog and keeps the bearer token isolated inside the local server process. Use hosted remote MCP only when the client supports a bearer-token HTTPS MCP endpoint and the user has approved a hosted resource/audience-bound credential. Hosted MCP lives at https://api.yardstick.team/mcp and publishes a fixed list of 176 tools with safety metadata, the same for every caller. There is no global hosted-write switch: each call is governed by its credential scopes, organization and mode partition, tool safety class, idempotency key, and preview/bind binding where required, and dashboard-required calls are refused before public API dispatch. Six further documented tools are not listed but remain callable; asking for one returns a short explanation naming a surface that can run it. If the host environment is unclear, ask the user. Do not invent an endpoint or guess a binary name. Approval, scope, and mode boundaries Yardstick requires a two-step preview-then-approve flow for state-changing actions that a human should review: application status transitions, archive, hire, offer, reject, withdraw, job posting publish or archive, and interview plan publish. Your job is to follow that flow, not to shortcut it: Call the transition-preview (or archive-preview, publish-preview, etc.) variant. The response contains a preview_hash, the resolved action_key, an input_hash, and the resource version the preview was computed against. Show this to the human user and explain what the change will do. Wait for explicit approval. The user may approve, narrow, or reject. Never auto-bind. Never reuse an old preview hash to skip the human step. Call the matching transition-bind (or archive-bind, publish-bind) variant with --idempotency-key matching binding.approved_idempotency_key and the full binding block carrying the four hashes plus the resource version precondition. The transition-direct and transition-preview variants speak the configured stage model: alongside the existing status enum they accept an optional pipeline_stage_id (a pst_ stage id) to move the application to a configured pipeline stage by id. status still selects the direct vs. approval variant and, when sent with pipeline_stage_id, must match the stage's mapped status; a mutating transition reports the resolved pipeline_stage_id. The status-only path is unchanged, and the denied-state semantics are identical either way — an unmet per-stage action gate returns the 409 action_gate_blocked block (described below) before any preview, and an approval-required target returns the 202 approval-preview envelope you bind in step 3. Additional rules: Discover CLI commands locally. For CLI sessions, use yardstick help topics, yardstick help scopes, and yardstick help before synthesizing a command. Help output is local metadata and does not read credentials or call the API. Scopes are floor-not-ceiling. The effective grant is whatever the approving owner or admin selected — which may be narrower than what the agent requested. Treat every call as scope-checked at the server and surface scope_insufficient errors verbatim so the user can re-approve. Do not invent a candidate namespace. yardstick help candidates explains how candidate-language work maps to people, applications, and opportunities; it is not evidence that yardstick candidates ... commands exist. Route candidate-language requests by action. Use people for identity, contact, and resume records; use applications when the user wants to create or mutate the person + Job attachment, application status, review evidence, transitions, or archive state; use opportunities only to read candidate/interview-cycle workflow context, next actions, and deep links. Never log raw tokens. Token-like flags (--token, --api-token, --api-key, --bearer-token) are rejected by the CLI so secrets do not land in shell history. If you encounter a token in user input, redact it in any output you produce. Do not send tokens in URLs. Hosted MCP accepts bearer credentials in headers only. Query-string token attempts are rejected before dispatch. Do not treat log lookup as a database backdoor. The function-log tool accepts only structured filters for a fixed set of allowed functions and returns redacted rows. It cannot run raw SQL, switch projects, call arbitrary admin paths, deploy or delete functions, or read secrets. Keep hosted resource tokens on hosted MCP. A token approved for https://api.yardstick.team/mcp is intentionally rejected on direct /v1/* API routes. Use a normal API or CLI credential for direct API calls. Hosted writes require explicit idempotency. Hosted MCP write-capable tools require the relevant scope, server write enablement, safety-class admission, and a caller-provided idempotency_key. Bind tools also require that key to match binding.approved_idempotency_key. Attribute actions correctly. When the CLI or MCP performs an action under a user's local credentials, the audit trail records that user, not "an agent." Do not claim the agent took the action — say "I ran yardstick applications transition-bind ... on your behalf; the audit log will attribute this to your account." Reporting denied or missing outcomes to a human Public API errors use a stable shape: { error: { code, message, request_id } }. Translate the code into language the user can act on rather than echoing HTTP statuses raw. 401 — the credential is missing or rejected. Say: "I do not have a valid Yardstick credential for this profile. Please re-run yardstick login (or check the host's MCP profile) and try again." 403 / scope_insufficient — the credential is valid but does not include the required scope. Name the missing scope from the error body and tell the user how to re-approve: "This account needs the applications:transition_status scope. Run yardstick reauthorize --add-scopes applications:transition_status for this profile, then approve the addition in the browser." If approval says the scope is unavailable, do not claim that renewal succeeded with narrower access. 403 / account_deletion_read_only — the organization has requested account deletion and is in the retained read-only window. Explain that writes are unavailable, but reads may still work while retained data is available. 404 — the resource ID does not resolve under the current credential's organization. Distinguish "the ID is wrong" from "the credential cannot see this org" by checking whoami first when the ID came from the user. 409 — idempotency reuse, version precondition failure, or a domain-specific conflict (for example ats_job_limit_exceeded). Read the code and explain the precondition, not the HTTP status. 409 / action_gate_blocked — a status transition was blocked by an unmet per-stage action gate. The body carries action_gate_blocked: true plus gate: { type, reason } (for example type: "scorecard_submitted", reason: "Needs a submitted scorecard for the current round"). This is a distinct discriminator from an approval/validity block and is returned before any approval preview, so the gate must clear before the move is even offered for approval. Surface gate.reason verbatim and act on it — for scorecard_submitted, prompt the human to submit the current round's scorecard, then retry the transition. You get the identical machine-readable block a recruiter's dashboard would; do not treat it as a missing feature. Built-in agent changes use the same preview-and-bind ceremony. Read with built_in_agents:read; request a preview or bind only with built_in_agents:write and an organization manager's explicit approval. Do not use the browser dashboard as an API route or supply an organization or live/test mode selector: the server derives both from the credential. For the interview-kit built-in agent, describe delivery_unknown as unconfirmed and stopped, not delivered. It must not be retried automatically. For kit access, point a signed-in user to the kit view for their assigned session; never use built-in agent history to look up kit data or infer whether an unavailable session or kit exists. For Keep candidates informed, explain that the built-in agent checks interview, application, and candidate-email activity recorded in Yardstick. External email does not reset its wait or cooldown. Its run report is count-only and links to /email-drafts?email_type=candidate_follow_up; counts never mean a message was sent. The built-in agent owns eligibility and timing, while Email Automation owns the active template, sender, draft review, delivery, and audit. Treat an invalidated candidate update as stale history. Edit, send, and discard return email_draft_not_mutable, and a send attempt does not call a provider. If the draft is still current but built-in agents or Email Automation is unavailable, send returns candidate_follow_up_feature_disabled. Keep the draft visible and retry with a new idempotency key only after availability is restored. The {{lastInterviewDate}} template variable belongs only to candidate_follow_up. Never claim a feature does not exist just because the call failed. A denied call means the credential, scope, or precondition was wrong — not that Yardstick lacks the capability. Surfacing request IDs and event references Every API response, success or failure, carries a request_id that ties it to server logs and the audit trail. When you report a problem to the user, include it verbatim — support staff can match it to the record directly. For errors, include the error.request_id from the response envelope. For successful state changes, the audit entry stores the same request ID; reference the event_id if you have it. For preview/bind ceremonies, surface both the preview's request ID (so the user can audit what they approved) and the bind's request ID (so the user can audit what was applied). A good failure report from an agent looks like: "I could not transition application app_abc to Offer. The API returned scope_insufficient (request_id: req_01HXYZ...). Your current credential is missing the applications:offer scope. Run yardstick reauthorize --add-scopes applications:offer for this profile, then approve the addition in the browser." A bad failure report is "It didn't work, sorry." Always include the request ID and the error code. Related reading Agent guidance overview — the operability mode model that every doc page declares in its frontmatter. API quickstart — the fastest path to a working /v1/whoami call. API agent-wrapper concepts — scopes, key types, idempotency, request IDs, and the approval-preview flow shared across every endpoint. CLI overview, CLI commands, and CLI safe-use for packaged help discovery, version checks, scopes, command flags, and approval-safe interactive use. MCP overview and MCP tools for the curated agent tool surface. Support Questions? Need help? Email support@yardstick.team --- ## Agent-auth + API wrapper concepts URL: https://app.yardstick.team/docs/api/agent-wrapper Summary: Scopes, key types, idempotency, request IDs, error envelopes, and the approval-preview flow shared across the Yardstick API. The pages under /docs/api/* describe individual endpoints. This page is the shared contract behind them — the concepts that apply to every public API call. It is a short summary; for the long-form detail, follow the canonical sources listed at the end. Key types Yardstick issues two kinds of bearer tokens. Both are validated by the same pipeline; the difference is which routes they can call. Publishable keys (ys_pk_live_… / ys_pk_test_…) are intake-safe keys for browser-mediated forms — the public API treats them as browser-origin requests and clamps them to a small allow-list of intake routes. Secret / agent keys (ys_sk_live_… / ys_sk_test_…) are server-side keys issued either statically by an admin or dynamically through the agent-auth approval flow. They can call any route in the scopes the approving user selected. The agent-auth approval flow (the one the CLI's yardstick login drives) always issues a secret-typed key. Behind the scenes it uses a PKCE challenge, a loopback callback, refresh-token rotation, and stores the credential in your system keychain. Use test-mode credentials for smoke writes; reach for live-mode only when a reviewer explicitly requests it. Test mode operates on generic test-mode data in the is_test partition. It is not the product's Sample mode: immutable Sample fixtures are browse-only and are not exposed through API credentials, fixture IDs, seed/reset actions, or writes. Scopes catalog A scope is a floor, not a ceiling: it caps what a key can do, but the approval step may grant less. The approval UI can narrow the set you request, and the API always enforces what was actually granted — never what you asked for. The current secret-scope catalog is: people:read, people:write — candidate and person records. applications:read, applications:write — application records and general updates. applications:transition_status — stage transitions guarded by the preview/bind ceremony. applications:offer, applications:hire, applications:reject, applications:withdraw, applications:archive — terminal-state transitions (each its own scope so least-privilege grants are meaningful). interview_plans:read, interview_plans:write, interview_plans:publish, interview_plans:modify_active — plan drafts, publishing, and live-plan edits. jobs:read, jobs:write — Job-row lifecycle (create, update, close, archive) and attaching/detaching artifacts (which also requires the artifact's own write scope). jobs:read is also required for Job-scoped prospect matches, alongside prospects:read and applications:read. Distinct from Job Postings. Closing, pausing, or archiving a Job unpublishes its live Job Postings; reopening does not republish them. automation_rules:read, automation_rules:write — stage automation-rule configuration and run history. Both scopes are organization-admin-only and gated by the configurable pipelines feature flag; authoring a rule is an internal configuration write, not an external provider action. prospects:read, prospects:write — Talent CRM prospects, pools, memberships, activity history, and approval-gated conversion to one canonical Application. Prospect match reads use prospects:read only and do not create outreach or application state. communications:read, communications:write, communications:send — candidate and prospect email draft review surfaces. Prospect outreach create can only create a pending review draft; actual send stays on email draft send and requires communications:send. source_links:read, source_links:write — posting-scoped source/referral attribution links. Create returns one-time public URL/token material; reads expose token hints only and never rank source quality. job_postings:read, job_postings:write, job_postings:publish, job_postings:archive — public-facing posting lifecycle. departments:read, departments:write — department records, membership, and lead assignment. invitations:read, invitations:write — department invitations. access_grants:read, access_grants:write — temporary access grants for panel interviewers and other narrow audiences. opportunities:read — read-only enriched opportunity workflow views, next actions, and deep links over application-backed candidate/interview-cycle work. reporting:read — reporting search queries (role health, attention, and deterministic Prospect CRM ops summaries). api_events:read, audit_logs:read — the audit trail used for correlation and after-the-fact review. scheduling:read, scheduling:write — scheduling links and session scheduling state. interview_sessions:read, interview_sessions:write — session records, interviewer assignment, start/complete, readiness. scorecards:read, scorecards:write — interviewer scorecards. decision_briefs:read, decision_briefs:write — decision briefs and regeneration. tasks:read — agent task queue used by yardstick tasks list and the default whoami smoke path. agency_collaboration:read, agency_collaboration:write — the agency principal of the agency↔customer collaboration surface (request/accept a connection; create/copy/share/stop-share an interview plan; submit/withdraw/revise/respond/add-evidence on a submission; read feedback). Held only by agency-org admins (an org whose workspace_type is agency). partner_collaboration:read, partner_collaboration:write — the customer principal of the same surface (read the submissions queue + redacted packet; make customer-owned decisions: connection mode/assign/ visibility/revoke, interview-plan accept/reject, submission accept-as-prospect/ reject/clarify/resolve-ownership). Held only by customer-org admins (an org whose workspace_type is customer). See Agency collaboration below for the dual-principal boundary. New logins preselect tasks:read by default; broaden the set only as needed. Packaged yardstick login defaults to the live-compatible subset of the catalog accepted by the production approval service. The value passed to login --scopes is the complete requested set for the new credential, not an addition to an existing profile. To renew a profile without changing its access, run yardstick reauthorize, yardstick auth reauthorize, or yardstick mcp reauthorize. Yardstick preserves the still-issuable inherited scopes and lists any scope it must drop. To request more access, pass --add-scopes to the matching reauthorize command. Yardstick proposes the union, opens browser approval, and requires an approver who can grant every addition. An unavailable addition blocks approval; it is never silently removed from the request. Department-enforced reads A read scope authorizes a route; it does not make every record in the organization enumerable. For Jobs, plans, postings, applications, sessions, opportunities, decision briefs, and reporting, Yardstick evaluates the token creator's current department, parent-record, and assignment access before a service-role reader returns rows. A normal member token sees only its readable departments, organization-wide/no-department records, and its documented assignment terms. An owner- or admin-created token inherits that creator's organization-wide read bypass by design. departments:read is different: department names and rosters remain organization-visible control-plane data. That visibility does not grant access to the department's hiring records, and a department name can itself reveal hiring intent. Treat an empty list or a generic unavailable result as an access boundary, not evidence that the record does not exist. Request IDs Every request the API serves carries a request_id and surfaces it in the response envelope and any error. The API either echoes the inbound X-Request-Id header you send or mints a new req_ value. Send your own ID by setting X-Request-Id on outbound calls. The server echoes it back; correlate against your own logs. Find the ID in error bodies at error.request_id (see the error envelope below). Find the ID for successful writes in the matching audit-log entry. When the agent reports a failure to a human user, include the request ID verbatim — that string is the cheapest way for support to pull the full log trail. Idempotency Write endpoints accept an Idempotency-Key header. Each key is scoped to the token that sent it, so the same key from a different token is treated as separate: Same key + same request body → the cached response is replayed. Safe for one-shot retries on network failure. Same key + different body → returns idempotency_key_reuse. The API refuses to silently serve a stale response under a reused key. No key → no replay protection. The CLI generates a key from the operation and request ID when one is not supplied. Bind commands in the approval ceremony require an explicit Idempotency-Key, and the value must match binding.approved_idempotency_key inside the request body. That coupling is what makes a binding replay-safe even though it carries state across two requests. The CLI never prints the raw key — only an idempotency_key_fingerprint appears in output. Application create Use POST /v1/applications, yardstick applications create, or the matching MCP tool when an agent needs to add an existing person to an existing job posting. The create request sends only person_id and job_posting_id, plus request and idempotency metadata. Read the person and job posting before you create the application; verify the resulting application as the write record, then use opportunities only when the user needs read-only candidate/interview-cycle workflow context or dashboard handoff. Applications are the person + Job attachment and write surface for application state, review evidence, status transitions, and archive flows. Opportunities are read-only candidate/interview-cycle views for next actions and dashboard handoff. Candidate self-submission still belongs in the public careers flow. Application create does not upload resume files, store screening answers, or evaluate knockouts. Screening answers are not part of the API Applications and opportunities return the application record — who applied, to which job posting, current status and stage, timestamps, and source attribution. They deliberately do not return what a candidate typed into your screening questions, and they do not return the pass/fail signal the apply form produced from those answers. This is a standing decision, not a gap waiting on implementation. Screening answers are candidate-entered and commonly cover work authorization, compensation expectations, location, and licensing. They are stored alongside a snapshot of the exact question wording so a reviewer sees what the candidate actually saw. Handing that content to every token with applications:read would be a much broader release of candidate data than the rest of the application record represents, so it stays out. The pass/fail signal is excluded for the same reason, and so is the status field that records whether the check finished. Adding a new column to the underlying application record never widens what these endpoints return; the response shape is built field by field, and there are tests that fail if a knockout field ever appears in it. Screening answers are visible to your team in the review screen for each application. If you need them through the API for a specific workflow, that is a separate, scoped piece of work with its own permission and audit story rather than something applications:read will start returning — tell us the workflow and we will scope it. Error envelope All 4xx and 5xx responses share one shape: { "error": { "code": "scope_insufficient", "message": "Token is missing required scope: applications:offer", "request_id": "req_01HXYZABCDE..." } } code is the stable, programmatically dispatchable identifier — match on it, not on message. Domain codes that an agent should expect include unauthorized, scope_insufficient, not_found, idempotency_key_reuse, resource_version_conflict, ats_job_limit_exceeded, account_deletion_read_only, and the per-domain preview/bind validation codes. account_deletion_read_only means the organization is in the account deletion lifecycle. Writes are denied before idempotency storage, audit or event writes, and handler side effects; reads continue while the retained account data is still available and the credential has scope. Approval-preview / bind flow State-changing actions that a human owner should approve use a two-request ceremony. The canonical pattern is the application-status transition: Preview — POST /v1/applications/{id}/transition-preview (or the matching archive-preview, publish-preview route). The response contains a preview_hash, the resolved action_key, an input_hash, and a resource_version the preview was computed against. Human approval — the agent surfaces the preview to the user and waits for explicit confirmation. The approval UI on the web app and the CLI both render the same preview shape. Bind — POST /v1/applications/{id}/transition-bind with header Idempotency-Key: and body { binding: { preview_hash, approved_action_key, approved_input_hash, approved_idempotency_key, resource_version_precondition }, ... }. The four hashes plus the precondition guarantee that the user approved exactly the request that gets applied. Every preview/bind pair is audited the same way as plain writes, so its audit-log entries tie back to a request ID. Endpoints currently using the ceremony include application status transitions, application archive, the combined status-and-email approval flow, prospect conversion to application, interview-plan publish, job-posting publish, and job-posting archive. Job posting actions expose four states: Draft, Published, Unpublished, and Archived. Publishing opens the attached non-archived Job when needed. A retained published_at value records prior publication and is not proof that the posting is currently public. Interview-plan edits create a new active version for each changed round. Future or not-started sessions use the newest active, unarchived version for their round; in-progress and completed sessions stay pinned to the version they were given. A later round may use the newest version after an earlier round completes. The combined status-and-email flow covers exactly one transition today: Interviewing -> Offer, with email_type=offer and decision=review_edit. Preview returns the status and reviewed-draft email side effects, template provenance, approval fields, idempotency, the planned audit entries, and read-back hints. Bind verifies those fields, then makes one status transition and one reviewed offer draft. It does not cover other status-and-email combinations, candidate interview scheduling links ({{interview_scheduling_link}}, {{sender_scheduling_link}}), provider setup, or sending status emails directly. See the API reference for the exact request shapes; this article is the contract they all share. Prospect conversion uses /v1/prospects/{prospect_id}/actions/convert_to_application/preview and /bind. It creates exactly one canonical Application for an existing prospect person and target Job Posting after approval binding. It does not import, dedupe, merge, send outreach, bulk convert, rank prospects, or write Opportunities. Prospect outreach uses /v1/prospects/{prospect_id}/outreach/preview and /outreach/drafts. Preview returns a reviewable subject/body and side-effect summary with no send, no sequence enrollment, and no application creation. Create requires a caller idempotency key and produces only a pending prospect-outreach draft for the existing /email-drafts review/send flow. Built-in agent APIs Use built_in_agents:read to list the five built-in agents, read current settings, and inspect count-only work reports. Use built_in_agents:write to preview and bind a configuration change. Built-in agent writes use the same approval fields and caller-supplied idempotency key described above; there is no manual-run command. Keep candidates informed has built-in agent id candidate-follow-through. Its strict configuration is enabled, timezone, local_hour, waiting_days, cooldown_days, and per_run_cap. It defaults off with America/Los_Angeles, 09:00, a three-day initial wait, a seven-day recurrence cooldown, and a cap of 100 candidates per run. Preview the complete proposed configuration, show it to the organization manager, then bind the same values with the approved binding. The built-in agent checks activity recorded in Yardstick and prepares candidate_follow_up drafts in Email Drafts. Email or workflow activity outside Yardstick does not reset its timing. The built-in agent resource reports whether Email Automation is currently available; saved settings and history remain readable when preparation is paused. Run responses include eligible, prepared, fallback, awaiting-review, suppression, failure, and output-state counts plus /email-drafts?email_type=candidate_follow_up. They do not expose candidate, message, recipient, private run/output, or provider details, and the counts do not mean an email was sent. Communications APIs Candidate communications routes mirror what the dashboard already does: draft list/read/preview/history, draft save/send/discard, application email-decision preview/apply, the combined status-and-email approval flow preview/bind, admin automation settings, redacted sender state/defaults, and candidate template list/detail/preview/validate/publish/version/rollback/customization preview. candidate_follow_up is the review-only draft type prepared by Keep candidates informed. Filter GET /v1/email/drafts with email_type=candidate_follow_up. List and read responses include safe candidate_follow_through attribution: the built-in agent label, reviewable or invalidated state, send availability, source interview timestamp/date, and model-or-deterministic fallback provenance. The worker does not expose a generic draft-create route and never sends the message. An active workspace member with communications:read can list and read these drafts. Editing, discarding, or sending requires both the relevant communications scope and organization owner or administrator access. The template variable {{lastInterviewDate}} is available only for candidate_follow_up; it is formatted from the completed source interview in the built-in agent timezone. {{interview_scheduling_link}} remains limited to interview_confirmation. The active Email Automation template, sender, draft lifecycle, reviewed send, and audit rules apply through the existing communications operations. When source facts change, a linked follow-up draft becomes invalidated. Edit, send, and discard then return 409 email_draft_not_mutable, and send performs no provider call. When the source remains current but built-in agents or Email Automation is unavailable, send returns 409 candidate_follow_up_feature_disabled; use a new idempotency key after the feature is restored. Existing scopes, the standard error envelope, hosted MCP write restrictions, and sender OAuth restrictions are unchanged. Required scopes are communications:read, communications:write, and communications:send, with application email-decision routes also requiring the matching application read/write/transition scopes. Candidate template APIs allow {{interview_scheduling_link}} only for interview_confirmation; it resolves to the candidate's interview-session scheduling link, not the sender's booking page. Draft provenance, history, and metadata may show a generated, reused, blocked, omitted, or suppressed scheduling-link outcome with safe session/link/provider/scheduler/sender/blocker/source metadata. Those provenance, history, and metadata fields must not expose provider tokens, raw provider payloads, raw prompts, or private provider URLs. Rendered draft bodies may include the public /schedule/:token link candidates receive. If scheduling setup blocks a required {{interview_scheduling_link}}, Yardstick creates a pending-review blocker draft instead of sending the candidate email or leaving an unresolved token. The combined status-and-email approval flow is fixed to Interviewing -> Offer, email_type=offer, and decision=review_edit; use applications status-email-poc-preview before applications status-email-poc-bind, with the same caller-supplied idempotency key and approval binding. Use Idempotency-Key for draft sends, draft edits, decision apply, sender mutations, and template mutations. Hosted MCP classifies safe reads and previews, and classifies the status-and-email approval tools as user_confirmed_preview_bind. There is no global hosted-write switch: each call is governed by its credential scopes, organization and mode partition, tool safety class, idempotency key, and preview/bind binding where required. Hosted MCP does not list the browser OAuth handoff and direct provider mutation tools: yardstick_email_sender_oauth_prepare, yardstick_email_sender_connections_refresh_discovery, and yardstick_email_sender_connections_disconnect. They are still reachable over the hosted endpoint; a call returns a short explanation instead of running. Use the dashboard, Yardstick CLI, or local MCP for those operations. These communications surfaces are not available: email sequences, mailbox reads or replies, raw provider mutation, raw prompt editing, and adjacent interviewer direct-send APIs. {{sender_scheduling_link}} belongs to Talent sequence email steps you author in the dashboard, not to the public API, CLI, or MCP. It resolves from the enrolled sender's personal scheduling URL when the sequence runs; missing setup blocks that step with SENDER_SCHEDULING_URL_REQUIRED and does not create a stale or unresolved draft. Integration Health APIs Workspace integration health is a read-only diagnostic surface for Google Workspace, Microsoft 365, and scheduling provider readiness. Use yardstick integrations workspace-health read or yardstick_integrations_workspace_health_read with communications:read and scheduling:read to inspect sanitized statuses, blocker codes, next actions, dashboard links, and counts. The health response does not expose provider tokens, Vault IDs, raw provider account identifiers, mailbox content, transcript text, participant emails, or raw provider payloads. Hosted MCP may execute the read tool, but OAuth setup, reconnect, disconnect, scope expansion, calendar writes, booking-page management, mailbox sync, and transcript content stay in the dashboard or are not supported. For customer-facing provider support status and security boundaries, see Google and Microsoft integrations. Agency collaboration (dual-principal) The agency-collaboration surface exposes the existing agency↔customer collaboration workflows to tokens and agents. It adds no new product behavior. Every mutation runs the same write path the in-app UI uses, every operation requires the agency-collaboration feature to be turned on, and every operation is audited exactly once. The defining property is a dual-principal trust boundary that never collapses. Agency-org admins hold the agency_collaboration:* scopes and drive the agency-originating actions; customer-org admins hold the partner_collaboration:* scopes and make the customer-owned decisions plus the customer reads. A token can hold only one family — whether the org is an agency or a customer, plus org-admin membership, decides which. A token in the wrong kind of org never receives the scope at all. So a cross-principal call (an agency token reaching a customer decision, or vice versa) is denied with a 403 before it reaches the endpoint. Agency tools never expose customer-owned decisions. Customer decisions need both the right scope and org-admin membership. A customer token that holds the scope but is not an org admin is still denied. High-risk operations are agent_confirmable (preview→bind): agency interview-plan share and submission submit; customer connection revoke, submission accept-as-prospect, and resolve-ownership. Feedback and packet reads run through the same redaction the UI uses, so the API can never expose more than the UI does — no evaluator identity, and no notes beyond what the UI already shows. Available over the API, not yet over the CLI or MCP. Every agency-collaboration operation is in the public API today and appears in the OpenAPI reference. The matching CLI commands and MCP tools are not available yet and will follow in a later release. Until then, call these operations through the public API directly with a token. The dashboard-only support routes for Agent approvals and Duplicate & ownership are not part of that public API set. They work only from a signed-in Yardstick app session, not secret-key API tokens, and do not add CLI or MCP tools. Use them in the Yardstick app until a later public contract is explicitly added. Where to find more This page is a short summary. For full detail, see: /docs/api/reference — the OpenAPI explorer for every endpoint shape, request body, and response. /docs/api/quickstart — first call walkthrough. CLI commands — every command, with its flags, scopes, and approval behavior. Support Questions? Need help? Email support@yardstick.team --- ## CLI commands URL: https://app.yardstick.team/docs/cli/commands Summary: Every Yardstick CLI command, grouped by category, with a one-line purpose and a realistic example. This page lists every command the CLI ships, kept in sync with the CLI itself. If a command here doesn't run, or a command you have doesn't appear here, your installed version may be out of date — run yardstick version --check. Run every public command through yardstick . Discovery commands Use root help for orientation, topic help for a command family, and command help for exact flags, scopes, idempotency behavior, approval requirements, and examples: yardstick yardstick help topics yardstick help scopes yardstick help jobs yardstick help applications transition-preview yardstick applications transition-preview --help yardstick help scopes lists the secret scope catalog, the packaged login defaults, and how to compare a command's required scopes with the effective scopes returned by yardstick whoami. yardstick help candidates is an alias/explainer only. It maps product language to people, applications, and opportunities; there is no runnable yardstick candidates ... namespace. Version and update commands are top-level packaged CLI commands, not API adapter commands: yardstick --version yardstick version yardstick version --check yardstick update yardstick version --check is the only version form that contacts npm. yardstick update is non-mutating update guidance: it prints the installed version, latest version when available, and the supported npm update command without running it. Identity whoami Return the current Yardstick API principal context. yardstick whoami Tasks tasks list List Yardstick tasks visible to the current principal. yardstick tasks list --limit 25 tasks deep-link Create a public task deep link for a caller-supplied task id. yardstick tasks deep-link --task-id task_123 People people list List people visible to the current principal. yardstick people list --limit 25 people read Read one person by public id. yardstick people read --person-id per_123 people create Create a person through the public Yardstick API. yardstick people create --email ada@example.com --name "Ada Lovelace" people update Update one person with schema-bound public API fields. yardstick people update --person-id per_123 --name "Ada L." Prospects prospects list List active Talent CRM prospects visible to the current principal. yardstick prospects list --limit 25 prospects read Read one Talent CRM prospect by public id. yardstick prospects read --prospect-id pro_123 prospects create Create Talent CRM prospect relationship state for an existing person. last_contacted_at must not be in the future. A value more than five minutes ahead of the server clock — the tolerance absorbs ordinary clock skew — is rejected with a 400 naming last_contacted_at. Anything at or before now, including a backdated value, is accepted. yardstick prospects create --person-id per_123 --source-label referral Who ends up owning it. Leave --owner-user-id off and the new prospect is owned by the human whose API key you are signed in with. That is a change in behavior: a prospect created this way used to have no owner at all, so a follow-up date set on it later produced no task for anybody. Now that it has an owner, a later prospects update --next-follow-up-at … puts a Follow up with … task on that owner's list in Yardstick. To keep a prospect deliberately unowned, send an explicit null — which needs --body-json, because --owner-user-id only takes a string: yardstick prospects create --person-id per_123 --body-json '{"owner_user_id":null}' Naming someone who is not an active member of your organization is refused with a 400 / invalid_request_body on owner_user_id, and nothing is written — the prospect is not created with the wrong owner. This command needs an existing --person-id, so a refusal here leaves no half-made records behind. The same rule is worded differently for recruiters inside the Yardstick app; match on the status and code, never on the message text. prospects convert-preview Preview converting one prospect into one canonical Application for a target Job Posting. yardstick prospects convert-preview --prospect-id pro_123 --job-posting-id jp_123 --idempotency-key prospect-convert-key prospects convert-bind Bind an approved prospect conversion preview. The idempotency key must match the approval binding. yardstick prospects convert-bind --prospect-id pro_123 --job-posting-id jp_123 --idempotency-key prospect-convert-key --body-json '{"binding":{"preview_hash":"...","approved_action_key":"prospect.convert_to_application","approved_input_hash":"...","approved_idempotency_key":"prospect-convert-key","resource_version_precondition":"..."}}' prospects outreach-preview Preview a one-off prospect outreach draft without creating a draft, sending email, enrolling a sequence, or creating an application. yardstick prospects outreach-preview --prospect-id pro_123 --job-posting-id jp_123 --outreach-intent-key staff-eng-warm prospects outreach-create-draft Create a pending review prospect outreach email draft. Sending stays on email-drafts send and requires communications:send. yardstick prospects outreach-create-draft --prospect-id pro_123 --job-posting-id jp_123 --idempotency-key prospect-outreach-draft-1 --subject "Staff Engineer conversation" prospects import-dry-run Preview a structured-row Prospect CRM import before any records are written. Rows are JSON only: no raw CSV reads, hosted MCP file access, or resume binaries. Exact same-org/same-mode email is the only automatic match; fuzzy suggestions require explicit apply decisions. A row whose last_contacted_at is more than five minutes ahead of the server clock is marked invalid in the preview, with the row error code last_contacted_at_in_future, and its proposed action becomes skip. This is per row, not per batch: one mistyped year costs that row, and every other row in the upload still previews and applies normally. yardstick prospects import-dry-run --idempotency-key prospect-import-preview-1 --body-json '{"rows":[{"name":"Ada Lovelace","email":"ada@example.com"},{"name":"Grace Hopper","current_company":"Navy"}]}' prospects import-read Read one import preview/apply batch by public id. yardstick prospects import-read --import-id pib_123 prospects import-apply Apply an import preview with the stored preview_hash. Include row decisions for advisory fuzzy suggestions; skipped rows and invalid rows remain inspectable. A row the preview marked invalid — including one with a future last_contacted_at — is skipped here while the rest of the batch is applied. Apply never sends outreach, creates applications, ranks source quality, merges people, or deletes people. yardstick prospects import-apply --import-id pib_123 --idempotency-key prospect-import-apply-1 --body-json '{"preview_hash":"...","decisions":[{"row_index":1,"input_hash":"...","decision":"link_existing","person_id":"per_123"}]}' Owners on imported rows. A row with no owner_user_id gives any prospect it creates to the human whose API key ran the apply; "owner_user_id": null leaves that prospect unowned; a user id gives it to that person. On a row that matches a prospect you already have, an omitted or null owner leaves the existing owner alone — import never quietly takes a prospect off a teammate. Import cannot set a follow-up date, so the owner it records creates no task by itself. A row naming someone who is not an active member of your organization is caught at import-dry-run: the row comes back invalid with owner_not_member in its errors list, so fix it there. Apply the batch anyway and that row is recorded skipped, not failed, with nothing written for it. The row only reaches failed if that owner loses active membership between the dry run and the apply — error_code owner_not_member that time — while the rest of the batch still applies. Apply checks again before creating a new person. Only the narrower race where the owner loses active membership after that check can leave the failed row's new person record behind. Recovering that row means a fresh import-dry-run, never a second import-apply. Applying is one-shot: it always leaves the batch applied, partially_applied, or failed, and any later apply on that batch is refused with a 409. (The row does remember which person it created, but that only covers replaying an apply that died mid-run and left the batch previewed.) The apply carries no owner of its own either — it reuses the one frozen into the row at dry-run time. On the fresh run the saved person is matched automatically when the row carries an email; a name-only row relies on an advisory suggestion drawn from a capped scan of your people, so add the email if you want the match to be certain. source-links list List source/referral attribution links. Reads return labels, state, and token hints only; raw public tokens are not exposed after create. yardstick source-links list --job-posting-id jp_123 --include-disabled true source-links read Read one source/referral attribution link by public id without raw token material. yardstick source-links read --source-link-id slink_123 source-links create Create an opaque public apply source/referral link for a published job posting. The raw source_token is returned only once on create. Reads return token_hint, and active token-bearing links also return a copyable public_url. yardstick source-links create --job-posting-id jp_123 --source-label "Founder referral" --referrer-name "Alex Referrer" source-links disable Disable a source/referral link so future public applies from that URL fail closed to normal attribution behavior without leaking source metadata. yardstick source-links disable --source-link-id slink_123 --reason "Campaign ended" prospects update Update bounded Talent CRM prospect relationship fields. last_contacted_at must not be in the future. A value more than five minutes ahead of the server clock — the tolerance absorbs ordinary clock skew — is rejected with a 400 naming last_contacted_at. Backdating is still allowed: an explicit write wins, and may move the date earlier, unlike the automatic updates described under prospects activities create. yardstick prospects update --prospect-id pro_123 --relationship-status archived Leaving --owner-user-id off an update never changes the current owner and never falls back to the key holder — only an explicit value reassigns a prospect, and an explicit null (via --body-json) unassigns it. Reassigning a prospect that already has a follow-up date moves its Follow up with … task to the new owner. prospects activities list List bounded activity records for one Talent CRM prospect. yardstick prospects activities list --prospect-id pro_123 --limit 25 prospects activities create Record something that happened with a prospect on their timeline. This has a side effect on the prospect record. A call or a meeting counts as having contacted the person, so creating one moves that prospect's last_contacted_at forward to the activity's occurred_at — which changes what the stale-prospect views and the "last touch" reporting figures say about them. A note, a source record, or a status_change does not count as contact and leaves the date alone. The date only ever moves forward this way: recording an older call never drags it back over a more recent one. occurred_at must not be in the future. A value more than five minutes ahead of the server clock is rejected with a 400 naming occurred_at; the five minutes absorb ordinary clock skew between your machine and the server. Backdating is unaffected — an occurred_at in the past is accepted, and simply does not move a contact date that is already later. yardstick prospects activities create --prospect-id pro_123 --activity-type note --body "Prefers to revisit after Q3" Talent Pools talent-pools list List Talent CRM pools visible to the current principal. Archived pools are left out unless you ask for them with --include-archived. yardstick talent-pools list --limit 25 Include archived pools alongside the active ones: yardstick talent-pools list --limit 25 --include-archived talent-pools read Read one Talent CRM pool by public id. yardstick talent-pools read --pool-id pool_123 talent-pools create Create a Talent CRM pool. yardstick talent-pools create --name "Founding engineers" talent-pools update Update bounded Talent CRM pool fields. yardstick talent-pools update --pool-id pool_123 --description "High-intent referrals" talent-pools members list List active prospect memberships for one Talent CRM pool. yardstick talent-pools members list --pool-id pool_123 --limit 25 talent-pools members add Add an existing prospect to a Talent CRM pool. yardstick talent-pools members add --pool-id pool_123 --prospect-id pro_123 talent-pools members remove Remove an active prospect membership from a Talent CRM pool. yardstick talent-pools members remove --pool-id pool_123 --prospect-id pro_123 ATS imports ats-imports dry-run Preview an ATS import of candidates, jobs, and applications before any records are written. A CSV import sends structured JSON rows (--source-kind csv); no raw CSV or archive file is read or stored. A Greenhouse import references an uploaded archive with --source-kind greenhouse --session-id (see ats-imports upload-archive). Exact same-org/same-mode candidate email is the only automatic match; fuzzy or low-confidence stage matches require explicit apply decisions. yardstick ats-imports dry-run --idempotency-key ats-import-preview-1 --body-json '{"source_kind":"csv","candidates":[{"name":"Ada Lovelace","email":"ada@example.com"}],"jobs":[{"title":"Staff Engineer"}],"applications":[{"candidate_email":"ada@example.com","job_title":"Staff Engineer","stage":"Applied"}]}' ats-imports read Read one ATS import dry-run/apply batch and its rows by public id. yardstick ats-imports read --import-id atim_123 ats-imports apply Apply an ATS import preview with its stored preview_hash. Apply creates people, jobs, stub interview plans, job postings, and applications with idempotent replay; a preview_hash that no longer matches the stored dry-run is rejected. Apply never sends outreach, merges people, or deletes records. yardstick ats-imports apply --import-id atim_123 --idempotency-key ats-import-apply-1 --body-json '{"preview_hash":"..."}' ats-imports upload-archive Upload a Greenhouse export archive (.zip) for import. The command reads the single file you point it at, requests a short-lived one-shot signed upload URL, and uploads the bytes over that URL — the archive never travels on the JSON wire. Requires a secret key. Not listed on hosted remote MCP; calling it there returns an explanation instead. Use the CLI, a local MCP client, or the dashboard. Then run ats-imports dry-run --source-kind greenhouse --session-id to preview it. yardstick ats-imports upload-archive --file ./greenhouse-export.zip People people upload-resume Upload a PDF or DOCX resume for a person. The command reads the single file you point it at, requests a short-lived signed upload URL, uploads the file, and attaches it to the person — the resume is then parsed exactly like a resume uploaded through the dashboard. Requires a secret key; the file is read from the exact path you pass (no wildcards or directories). Not listed on hosted remote MCP; calling it there returns an explanation instead. Use the CLI, a local MCP client, or the dashboard. yardstick people upload-resume --person-id per_123 --file ./resume.pdf people finalize-resume-upload Finalize a resume upload session you created earlier — re-validates the uploaded file, attaches it to the person, and parses it. Most callers use people upload-resume, which runs every step for you; reach for this only when you have driven the upload steps yourself. Not listed on hosted remote MCP; calling it there returns an explanation instead. Use the CLI, a local MCP client, or the dashboard. yardstick people finalize-resume-upload --person-id per_123 --session-id rus_123 Applications Applications are the person + Job attachment and the CLI write surface for application/applicant state. Use these commands for creating the attachment, updating application-owned fields, recording application evidence, status transitions, and archive approval flows. applications list List application person + Job attachments visible to the current principal. yardstick applications list --limit 25 applications read Read one application person + Job attachment by public id. yardstick applications read --application-id app_123 applications create Create a recruiter- or agent-sourced application for an existing person and job posting. yardstick applications create --person-id per_123 --job-posting-id jp_123 --idempotency-key application-123 applications update Update one application with schema-bound public API fields. yardstick applications update --application-id app_123 --stage Screening applications transition-direct Directly write a non-terminal application transition; approval-only statuses are rejected. yardstick applications transition-direct --application-id app_123 --status Screening applications transition-preview Preview approval-required application transitions only; bind fields and direct-write targets are rejected. Approval-required — pair with transition-bind. yardstick applications transition-preview --application-id app_123 --status Offer applications transition-bind Bind an already-previewed application transition with explicit approval metadata and matching idempotency key. Approval-required — must follow a preview. yardstick applications transition-bind --application-id app_123 --body-json '{"status":"Offer","binding":{...}}' applications archive-preview Preview application archive approval requirements only; bind fields are rejected. Approval-required — pair with archive-bind. yardstick applications archive-preview --application-id app_123 applications archive-bind Bind an already-previewed application archive with explicit approval metadata and matching idempotency key. Approval-required — must follow a preview. yardstick applications archive-bind --application-id app_123 --body-json '{"binding":{...}}' applications status-email-poc-preview Preview the fixed applications-owned Interviewing to Offer status/email approval flow without mutating status or email state. Approval-required — pair with status-email-poc-bind. yardstick applications status-email-poc-preview \ --application-id app_123 \ --current-status Interviewing \ --target-status Offer \ --email-type offer \ --decision review_edit \ --idempotency-key status-email-poc-preview-1 applications status-email-poc-bind Bind the fixed applications-owned status/email approval flow with explicit approval metadata and a matching idempotency key. Approval-required — must follow a preview. yardstick applications status-email-poc-bind \ --application-id app_123 \ --current-status Interviewing \ --target-status Offer \ --email-type offer \ --decision review_edit \ --idempotency-key status-email-poc-preview-1 \ --body-json '{"binding":{...}}' applications decision-brief read Read the decision brief for an application. yardstick applications decision-brief read --application-id app_123 applications decision-brief regenerate Regenerate a decision brief for an application with idempotency metadata. yardstick applications decision-brief regenerate --application-id app_123 applications final-recommendation record Record direct final-recommendation evidence; this does not mutate application status. yardstick applications final-recommendation record --application-id app_123 --interviewer-user-id usr_abc --rating 3 applications interview-sessions list List interview sessions for an application. yardstick applications interview-sessions list --application-id app_123 applications interview-sessions ensure Ensure an application interview session for an explicit round id. yardstick applications interview-sessions ensure --application-id app_123 --round-id rnd_123 Opportunities Opportunities are read-only enriched workflow views over application-backed candidate/interview-cycle work. This namespace is limited to list, read, next-action, and deep-link commands; create, update, transition, archive, and approval flows stay under applications. opportunities list List read-only opportunities visible to the current principal. yardstick opportunities list --limit 25 opportunities read Read one read-only opportunity workflow view by public id. yardstick opportunities read --opportunity-id opp_123 opportunities next-action Read the next action state for an opportunity without mutating it. yardstick opportunities next-action --opportunity-id opp_123 opportunities deep-link Create a public deep link for an opportunity workflow view. yardstick opportunities deep-link --opportunity-id opp_123 Departments departments list List Departments visible to the current principal. yardstick departments list --limit 25 departments read Read one Department by public id. yardstick departments read --department-id dpt_123 departments create Create a Department through the public Yardstick API. yardstick departments create --name "Engineering" departments update Update one Department with schema-bound public API fields. yardstick departments update --department-id dpt_123 --name "Platform Engineering" departments members list List Department members for an authorized Department. yardstick departments members list --department-id dpt_123 departments members add Add an existing person to a Department. yardstick departments members add --department-id dpt_123 --person-id per_123 departments members set-lead Set one Department member as lead. yardstick departments members set-lead --department-id dpt_123 --person-id per_123 departments members remove Remove a Department member, optionally with a replacement lead. yardstick departments members remove --department-id dpt_123 --person-id per_123 departments invitations list List redacted Department invitation views. yardstick departments invitations list --department-id dpt_123 departments invitations create Create a Department-scoped invitation without returning token material. yardstick departments invitations create --department-id dpt_123 --body-json '{"email":"ada@example.com"}' Access grants access-grants list List explicit access grants visible to the current principal. yardstick access-grants list --limit 25 access-grants read Read one explicit access grant by public id. yardstick access-grants read --access-grant-id agt_123 access-grants create Create a reasoned, revocable, audited access grant. yardstick access-grants create --body-json '{"subject_person_id":"per_123","scope":"applications:read","reason":"audit"}' access-grants revoke Revoke an explicit access grant with optional reason text. yardstick access-grants revoke --access-grant-id agt_123 --reason "rotated" Jobs jobs list List internal Job containers visible to the current principal. yardstick jobs list --limit 5 jobs create Create an internal Job container without mutating job postings, applications, or interview plans. yardstick jobs create --title "Senior Engineer" jobs read Read one internal Job container by public id. yardstick jobs read --job-id job_123 jobs prospect-matches List deterministic Talent CRM prospect matches for one Job. Requires jobs:read, prospects:read, and applications:read; returns evidence, caveats, blocked lifecycle states, and dashboard URLs without outreach, conversion, import, or AI ranking. yardstick jobs prospect-matches --job-id job_123 jobs update Update one internal Job container with schema-bound public API fields. yardstick jobs update --job-id job_123 --status paused jobs close Close a Job and atomically unpublish its live linked job postings. Applications and interview plans are not mutated. Reopening does not republish a posting. yardstick jobs close --job-id job_123 jobs archive Archive a Job and atomically unpublish its live linked job postings. Applications and interview plans are not mutated. yardstick jobs archive --job-id job_123 jobs attach-artifact Link an existing interview plan, job posting, or application to a Job. Re-attaching to the same Job succeeds without changes; attaching something already linked to a different Job returns a conflict. Requires both jobs:write and the artifact's own write scope. yardstick jobs attach-artifact --job-id job_123 --artifact-type job_posting --artifact-id jp_123 jobs detach-artifact Clear the link between an artifact and a Job. Detaching an artifact that is already unlinked succeeds without changes. Requires both jobs:write and the artifact's own write scope. yardstick jobs detach-artifact --job-id job_123 --artifact-type job_posting --artifact-id jp_123 Pipelines pipelines list List the organization's pipeline templates with their ordered stages. Canonical default stages are flagged canonical_locked. yardstick pipelines list pipelines read Read one pipeline template and its ordered stages by public id. yardstick pipelines read --pipeline-id pip_123 pipelines create Create a custom pipeline template with optional inline stages. Does not affect the org default pipeline or candidate tracking. yardstick pipelines create --name "Engineering" --slug engineering pipelines update Rename, re-describe, or toggle active for one pipeline template. yardstick pipelines update --pipeline-id pip_123 --name "Eng (2026)" pipelines stages create Append (or insert at a position) a stage to a pipeline with a kind and optional approval scope. yardstick pipelines stages create --pipeline-id pip_123 --name "Phone Screen" --slug phone_screen --stage-kind normal pipelines stages update Edit a pipeline stage. Canonical default stages allow display-name change only; slug, stage kind, approval scope, and terminal flag are locked. yardstick pipelines stages update --pipeline-id pip_123 --stage-id stg_123 --name "Recruiter Screen" pipelines reorder-stages Reorder all stages of a pipeline by supplying the complete stage id order. Constraint-safe single-transaction reorder; allowed for canonical stages. yardstick pipelines reorder-stages --pipeline-id pip_123 --stage-ids stg_2,stg_1,stg_3 pipelines stages delete-preview Preview deleting a pipeline stage; returns the candidate-count impact and approval binding fields without mutating. Canonical default stages are rejected. Requires pipelines:write. yardstick pipelines stages delete-preview --pipeline-id pip_123 --stage-id stg_123 pipelines stages delete-bind Bind an approved pipeline-stage delete with explicit approval metadata and a matching idempotency key. Refuses while candidates remain. Requires pipelines:write. yardstick pipelines stages delete-bind --pipeline-id pip_123 --stage-id stg_123 --binding @binding.json pipelines assign-to-job Assign a pipeline to a Job, or clear it with --pipeline-id null. Requires both pipelines:write and jobs:write. yardstick pipelines assign-to-job --job-id job_123 --pipeline-id pip_123 Automation rules Stage automation rules are inert configuration — authoring fires no side effect, and the execution engine runs rules in a later release. The whole surface is gated by the configurable_pipelines_enabled feature flag and the automation_rules:read / automation_rules:write scopes (admin-only). automation-rules list List the organization's stage automation rules. Rules are inert config — authoring fires no side effect; the executor child runs rules later. yardstick automation-rules list automation-rules read Read one stage automation rule by public id (its trigger, typed action, target stage, and is_active state). yardstick automation-rules read --rule-id aru_123 automation-rules create Create a stage automation rule (trigger plus a typed action from the 3-type palette: send_scheduling_link / create_task / send_email). Inert — fires no side effect. yardstick automation-rules create --pipeline-stage-id pst_123 --trigger stage_enter --action '{"type":"send_scheduling_link"}' automation-rules update Edit a stage automation rule's trigger, typed action, condition, position, or is_active state. yardstick automation-rules update --rule-id aru_123 --is-active false automation-rules delete Delete a stage automation rule. Plain delete (no approval preview→bind): rules are inert config, so deleting unfired config moves no candidates. yardstick automation-rules delete --rule-id aru_123 automation-rules preview Dry-run preview: resolve the active rules plus their resolved action params for a sample application entering or leaving a stage. INERT — mints no scheduling link, creates no task, sends no email; executes nothing. yardstick automation-rules preview --application-id app_123 --trigger stage_enter --pipeline-stage-id pst_123 automation-runs list List the organization's stage automation runs (what fired for which candidate, success or failure). Read-only — runs are system-written by the executor. Filter by --application-id and/or --rule-id; skipped (deferred) send_email rows are included so run state is fully observable. yardstick automation-runs list --application-id app_123 Built-in agents Built-in agents turn recurring hiring work into named outcomes. Chase missing scorecards reminds interviewers about missing feedback. Screen new applicants nightly prepares rejection drafts for applicants who clearly do not meet the role requirements. Prep interview kits for next week's sessions prepares current kits for assigned interviewers. Prepare a panel decision brief brings completed interview evidence together. Keep candidates informed prepares updates for interviewed candidates who are still waiting, using bounded personalization when available and the validated template as a fallback. Use built_in_agents:read for reads and built_in_agents:write for preview→bind changes. built-in-agents list List the hiring built-in agents available to your workspace, including each built-in agent's current settings and latest work summary. yardstick built-in-agents list built-in-agents read Read one built-in agent by catalog id, including what it does, what it never does without you, its current settings, and its latest work summary. yardstick built-in-agents read --built-in-agent-id scorecard-chaser built-in-agents runs List the selected built-in agent's work report. Scorecard runs include reminder activity. Nightly-screening runs include scheduled-work counts and count-only held, released, or invalidated review outputs. They do not include candidate, email-draft, or recipient details. Interview-kit runs report only the scheduled week and preparation counts. Yardstick marks an unconfirmed delivery as stopped, not delivered, and does not retry it automatically. Candidate-follow-through runs report count-only eligible, prepared, fallback, awaiting-review, suppression, failure, and output states, with an Email Drafts destination. They never mean an email was sent. yardstick built-in-agents runs --built-in-agent-id scorecard-chaser built-in-agents enable-preview Preview turning on a built-in agent. The preview explains the reminders that will start and returns the approval binding; it does not change settings or send a reminder. yardstick built-in-agents enable-preview --built-in-agent-id scorecard-chaser --idempotency-key scorecard-enable-1 built-in-agents enable-bind After a person approves the preview, turn on the built-in agent with its matching binding and idempotency key. The bind applies only the approved change. yardstick built-in-agents enable-bind --built-in-agent-id scorecard-chaser --idempotency-key scorecard-enable-1 --body-json '{"binding":{"preview_hash":"...","approved_action_key":"recipe.enable","approved_input_hash":"...","approved_idempotency_key":"scorecard-enable-1","resource_version_precondition":"..."}}' built-in-agents configure-preview Preview a built-in agent schedule or turn a built-in agent off. For Chase missing scorecards, provide one to five strictly increasing hours after the interview ends, each no later than 72 hours. For Screen new applicants nightly, owners and admins can set timezone, local_hour, and per_run_cap with the enabled switch. For Prep interview kits for next week's sessions, they can set enabled, timezone, local_day, and local_hour. Its disabled default is Friday at 09:00 in America/Los_Angeles. For Keep candidates informed, they can set enabled, timezone, local_hour, waiting_days, cooldown_days, and per_run_cap. It defaults off with 09:00 in America/Los_Angeles, a three-day initial wait, a seven-day recurrence cooldown, and a cap of 100 candidates per run. yardstick built-in-agents configure-preview --built-in-agent-id scorecard-chaser --idempotency-key scorecard-schedule-1 --body-json '{"config":{"intervals":[2,24,48]}}' built-in-agents configure-bind After approval, apply the same settings with the matching binding and idempotency key. To turn the built-in agent off, use "enabled": false in config. yardstick built-in-agents configure-bind --built-in-agent-id scorecard-chaser --idempotency-key scorecard-schedule-1 --body-json '{"config":{"intervals":[2,24,48]},"binding":{"preview_hash":"...","approved_action_key":"recipe.configure","approved_input_hash":"...","approved_idempotency_key":"scorecard-schedule-1","resource_version_precondition":"..."}}' Job postings job-postings list List job postings visible to the current principal. yardstick job-postings list --limit 25 job-postings read Read one job posting by public id. yardstick job-postings read --job-posting-id jp_123 job-postings validate Validate a draft job posting without mutating it. yardstick job-postings validate --job-posting-id jp_123 job-postings create Create a draft job posting through the public Yardstick API. Drafts may omit a country, but publishing requires one, including for remote roles. Country values use assigned ISO 3166-1 alpha-2 codes and are normalized to uppercase. yardstick job-postings create --title "Senior Engineer" --interview-plan-id ipd_123 --slug senior-engineer --location-country US job-postings update Update a job posting with schema-bound public API fields. Omit location_country to preserve it. To clear the country from an unpublished draft, send an explicit JSON null. yardstick job-postings update --job-posting-id jp_123 --title "Staff Engineer" yardstick job-postings update --job-posting-id jp_123 --body-json '{"location_country":null}' job-postings publish-preview Preview job-posting publish approval requirements only; bind fields are rejected. Approval-required — pair with publish-bind. yardstick job-postings publish-preview --job-posting-id jp_123 job-postings publish-bind Bind an already-previewed job-posting publish with explicit approval metadata and matching idempotency key. Approval-required — must follow a preview. yardstick job-postings publish-bind --job-posting-id jp_123 --body-json '{"binding":{...}}' job-postings archive-preview Preview job-posting archive approval requirements only; bind fields are rejected. Approval-required — pair with archive-bind. yardstick job-postings archive-preview --job-posting-id jp_123 job-postings archive-bind Bind an already-previewed job-posting archive with explicit approval metadata and matching idempotency key. Approval-required — must follow a preview. yardstick job-postings archive-bind --job-posting-id jp_123 --body-json '{"binding":{...}}' Job posting lifecycle states are Draft, Published, Unpublished, and Archived. Publishing opens the attached non-archived Job when needed. Closing, pausing, or archiving a Job takes its live postings down; reopening leaves them Unpublished until a user publishes them again. A retained published_at timestamp records prior publication and does not mean the posting is currently public. Interview plans interview-plans read Read one interview plan by public id. This narrow read intentionally omits the builder's outcome list; use interview-plan-drafts read below to inspect draft outcomes and their optional tags. yardstick interview-plans read --interview-plan-id ipd_123 interview-plans publish-preview Preview interview-plan publish approval requirements only; bind fields are rejected. Approval-required — pair with publish-bind. For a ready preview, read preserved outcome tags from proposed_state.outcomes. A preview blocked by publish preconditions keeps the mapper preview under data.preview, with outcomes at data.preview.values.outcomes; do not use that blocked-preview path for a ready response. yardstick interview-plans publish-preview --body-json '{"action":"interview_plan.publish_preview","resource":{"id":"ipd_123"},"input":{}}' interview-plans publish-bind Bind an already-previewed interview-plan publish with explicit approval metadata and matching idempotency key. Approval-required — must follow a preview. yardstick interview-plans publish-bind --body-json '{"action":"interview_plan.publish_bind","resource":{"id":"ipd_123"},"input":{},"binding":{...}}' interview-plans modify-active-preview Preview the effect of applying a draft's changes to an already-active interview plan: which rounds get a new version and which candidate sessions move versus stay locked. Future or not-started sessions use the newest active, unarchived version for their round; in-progress and completed sessions stay pinned to the version they were given. Bind fields are rejected. Approval-required — pair with modify-active-bind. yardstick interview-plans modify-active-preview --body-json '{"action":"interview_plan.modify_active","input":{"draft_id":"ipd_draft_123","active_plan_id":"ipd_456"}}' interview-plans modify-active-bind Apply a previously-previewed modification to an active interview plan, with explicit approval metadata and matching idempotency key. Approval-required — must follow a preview. yardstick interview-plans modify-active-bind --body-json '{"action":"interview_plan.modify_active","input":{"draft_id":"ipd_draft_123","active_plan_id":"ipd_456"},"binding":{...}}' Interview plan drafts interview-plan-drafts generate-outcomes Generate draft interview-plan outcomes from explicit role context, or pass accepted_outcomes to store caller-written outcomes verbatim with no AI generation — the deterministic, LLM-free way to bootstrap a draft (same item shape as confirm-outcomes). Optional source_job_id (a same-org Job UUID) seeds the draft's role context from that Job; caller-provided role_context keys override per-field. It cannot be combined with resource.id. yardstick interview-plan-drafts generate-outcomes --body-json '{"action":"interview_plan.generate_outcomes","input":{"role_context":{"role_title":"Engineer"}}}' yardstick interview-plan-drafts generate-outcomes --body-json '{"action":"interview_plan.generate_outcomes","input":{"role_context":{"role_title":"Engineer"},"accepted_outcomes":[{"id":"outcome_1","text":"Ship the v2 platform in two quarters.","tag":"Platform delivery"}]}}' Each outcome may include an optional tag beside its stable id and full statement. Generated tags and caller-supplied tags are preserved verbatim in the outcomes checkpoint and echoed in the action's data.outcomes. A missing tag remains valid for older outcomes, and the tag never replaces the full statement. The API-compatible title field is also a full outcome statement fallback, not a compact tag. Use tag for optional compact presentation. interview-plan-drafts confirm-outcomes Confirm draft interview-plan outcomes before generating later stages. Include the optional tag when you want to keep a compact label with the full outcome. yardstick interview-plan-drafts confirm-outcomes --body-json '{"action":"interview_plan.confirm_outcomes","resource":{"id":"ipd_123"},"input":{"accepted_outcomes":[{"id":"outcome_1","text":"Ship the v2 platform in two quarters.","tag":"Platform delivery"}]}}' interview-plan-drafts generate-competencies Generate draft interview-plan competencies from confirmed outcomes. yardstick interview-plan-drafts generate-competencies --body-json '{"action":"interview_plan.generate_competencies","resource":{"id":"ipd_123"},"input":{}}' interview-plan-drafts generate-skills Generate draft interview-plan skills from confirmed competencies. yardstick interview-plan-drafts generate-skills --body-json '{"action":"interview_plan.generate_skills","resource":{"id":"ipd_123"},"input":{}}' interview-plan-drafts generate-rounds Generate draft interview-plan rounds from confirmed skills. yardstick interview-plan-drafts generate-rounds --body-json '{"action":"interview_plan.generate_rounds","resource":{"id":"ipd_123"},"input":{}}' interview-plan-drafts generate-anchors Generate scorecard behavioral anchors (levels 1-4) for each draft competency, or one competency when competency_id is supplied. yardstick interview-plan-drafts generate-anchors --body-json '{"action":"interview_plan.generate_anchors","resource":{"id":"ipd_123"},"input":{}}' interview-plan-drafts generate-questions-directions Generate interview questions and interviewer/candidate directions for each draft round, or one round when round_id is supplied. yardstick interview-plan-drafts generate-questions-directions --body-json '{"action":"interview_plan.generate_questions_directions","resource":{"id":"ipd_123"},"input":{}}' interview-plan-drafts validate Validate an interview-plan draft without publishing it. yardstick interview-plan-drafts validate --body-json '{"action":"interview_plan.validate_draft","resource":{"id":"ipd_123"},"input":{}}' interview-plan-drafts read Read a draft in full: every stage checkpoint (outcomes, competencies, job skills, interview sequence, questions and directions), current stage_versions, and status. This is the fetch half of fetch-modify-submit editing — read the draft to discover item ids and stage versions, apply edits, then read again to verify. The outcomes checkpoint returns each saved outcome, including an optional tag, unchanged. Question ids are always present, so question edits can target them directly. yardstick interview-plan-drafts read --draft-id ipd_123 The verbatim edit commands below store your content exactly as written — no AI generation, same request in means same stored content out. They share three contracts: source_stage precondition. Optionally pass the mutated stage's name and the version you last read ({"source_stage":{"stage":"skills","version":3}}); a stale version returns 409 so concurrent edits never silently overwrite each other. Competency edits use stage competencies, skills use skills, rounds use interview_sequence, and question/direction/anchor edits use questions_and_directions. Prune-and-report deletes. Deleting a competency prunes its behavioral anchors; deleting a round prunes that round's questions and directions. The response reports the pruned ids and bumps every mutated stage version in the same write. Capacity-safe replacement. Each stage has a maximum (25 competencies, 50 skills, 20 rounds) and every add-* batch must fit within it. To replace a full stage at its maximum, prefer update-* in place where ids overlap — an item updated in place keeps its id, so its dependent data is preserved, not pruned. Otherwise interleave deletes and adds in capacity-sized batches. interview-plan-drafts add-competencies Add competencies to a draft exactly as written. Requires confirmed outcomes. Each item needs a name and a description; ids are minted by the server unless you supply your own. yardstick interview-plan-drafts add-competencies --body-json '{"action":"interview_plan.add_competencies","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"items":[{"name":"Structured judgment","description":"Weighs evidence before deciding."}]}}' interview-plan-drafts update-competencies Replace competencies by id and/or reorder them. order must be a complete permutation of the resulting competency ids; pure reorder works with order alone. yardstick interview-plan-drafts update-competencies --body-json '{"action":"interview_plan.update_competencies","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"items":[{"id":"competency_1","name":"Structured judgment","description":"Weighs evidence before deciding."}]}}' interview-plan-drafts delete-competencies Delete competencies by id. Each deleted competency's behavioral anchors are pruned in the same write and the pruned ids are reported; the stage must keep at least one competency. yardstick interview-plan-drafts delete-competencies --body-json '{"action":"interview_plan.delete_competencies","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"ids":["competency_2"]}}' interview-plan-drafts add-skills Add job skills to a draft exactly as written. Requires competencies. yardstick interview-plan-drafts add-skills --body-json '{"action":"interview_plan.add_skills","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"items":[{"name":"Structured interviewing"}]}}' interview-plan-drafts update-skills Replace job skills by id and/or reorder them with a complete order permutation. yardstick interview-plan-drafts update-skills --body-json '{"action":"interview_plan.update_skills","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"order":["skill_2","skill_1"]}}' interview-plan-drafts delete-skills Delete job skills by id; the stage must keep at least one skill. yardstick interview-plan-drafts delete-skills --body-json '{"action":"interview_plan.delete_skills","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"ids":["skill_2"]}}' interview-plan-drafts add-rounds Add interview rounds to a draft exactly as written. Requires skills. yardstick interview-plan-drafts add-rounds --body-json '{"action":"interview_plan.add_rounds","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"items":[{"title":"Structured interview","duration":60}]}}' interview-plan-drafts update-rounds Replace rounds by id and/or reorder them. A round updated in place keeps its id, so its questions and directions are preserved — replacing a round's content this way never prunes. yardstick interview-plan-drafts update-rounds --body-json '{"action":"interview_plan.update_rounds","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"items":[{"id":"round_1","title":"Structured interview","duration":45}]}}' interview-plan-drafts delete-rounds Delete rounds by id. Each deleted round's questions and directions are pruned in the same write and the pruned ids are reported; the sequence must keep at least one round. yardstick interview-plan-drafts delete-rounds --body-json '{"action":"interview_plan.delete_rounds","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"ids":["round_2"]}}' interview-plan-drafts add-questions Add questions to one round exactly as written. Requires rounds; each round holds at most 50 questions. yardstick interview-plan-drafts add-questions --body-json '{"action":"interview_plan.add_questions","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"round_id":"round_1","questions":[{"text":"Walk me through a recent decision you owned."}]}}' interview-plan-drafts update-questions Replace one round's questions by id and/or reorder them with a per-round order permutation. Read the draft first — stored questions always expose stable ids (question_1, question_2, …). yardstick interview-plan-drafts update-questions --body-json '{"action":"interview_plan.update_questions","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"round_id":"round_1","questions":[{"id":"question_2","text":"Tell me about a tradeoff you got wrong."}]}}' interview-plan-drafts delete-questions Delete questions from one round by question id. yardstick interview-plan-drafts delete-questions --body-json '{"action":"interview_plan.delete_questions","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"round_id":"round_1","ids":["question_2"]}}' interview-plan-drafts update-round-directions Set one round's interviewer and/or candidate directions exactly as written. Provide at least one of the two direction fields. yardstick interview-plan-drafts update-round-directions --body-json '{"action":"interview_plan.update_round_directions","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"round_id":"round_1","interviewer_directions":"Probe for concrete evidence."}}' interview-plan-drafts update-anchors Upsert behavioral anchors for draft items, keyed by item id with levels 1–4. Requires competencies; anchors keyed to unknown item ids are rejected by id. yardstick interview-plan-drafts update-anchors --body-json '{"action":"interview_plan.update_anchors","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"anchors":{"competency_1":[{"level":3,"description":"Consistently weighs evidence."}]}}}' interview-plan-drafts delete-anchors Delete behavioral-anchor entries for draft items by item id. yardstick interview-plan-drafts delete-anchors --body-json '{"action":"interview_plan.delete_anchors","resource":{"type":"interview_plan_draft","id":"ipd_123"},"input":{"item_ids":["competency_2"]}}' Interview sessions interview-sessions read Read one interview session by public id. yardstick interview-sessions read --interview-session-id is_123 interview-sessions interviewers list List interviewers assigned to an interview session. yardstick interview-sessions interviewers list --interview-session-id is_123 interview-sessions interviewers assign Assign an interviewer to an interview session. yardstick interview-sessions interviewers assign --interview-session-id is_123 --interviewer-user-id usr_abc interview-sessions interviewers unassign Unassign an interviewer from an interview session. yardstick interview-sessions interviewers unassign --interview-session-id is_123 --interviewer-user-id usr_abc interview-sessions start Start an interview session for an explicit interviewer. yardstick interview-sessions start --interview-session-id is_123 --interviewer-user-id usr_abc interview-sessions complete Complete an interview session for an explicit interviewer. yardstick interview-sessions complete --interview-session-id is_123 --interviewer-user-id usr_abc interview-sessions scorecard submit Submit an interview-session scorecard with explicit ratings. yardstick interview-sessions scorecard submit --interview-session-id is_123 --body-json '{"interviewer_user_id":"...","ratings":[...]}' interview-sessions readiness Read interview-session scheduling readiness. yardstick interview-sessions readiness --interview-session-id is_123 interview-sessions scheduling-link generate Generate a scheduling link for an interview session. yardstick interview-sessions scheduling-link generate --interview-session-id is_123 interview-sessions cancel Cancel a scheduled interview session, releasing the provider booking and invalidating its scheduling links. Both flags are optional. --reason is recorded on the resulting scheduling.session_cancelled event and is the only place it is stored. --skip-provider cancels in Yardstick without calling the scheduling provider — use it when the provider is failing and you need the round cancelled anyway. Cancelling an already-cancelled round succeeds and reports outcome: "already_cancelled"; it makes no provider call and sends no second email. Check candidate_email in the response: email_not_sent means the round was cancelled but the candidate was never told. yardstick interview-sessions cancel --interview-session-id is_123 --reason "Hiring manager unavailable" Events events list List public Yardstick API events visible to the current principal. yardstick events list --limit 25 Audit log audit-log list List public Yardstick audit log entries visible to the current principal. yardstick audit-log list --limit 25 Reporting reporting search Search redacted recruiting reporting summaries through the public reporting API. yardstick reporting search \ --query-family role_health_attention \ --window-start 2026-05-01 \ --window-end 2026-05-28 \ --role-label "AI Content Manager" \ --limit 10 yardstick reporting search \ --query-family prospect_ops_summary \ --window-start 2026-05-01 \ --window-end 2026-05-28 \ --job-id job_... \ --limit 10 Need help? Email support@yardstick.team Email communications applications email-decision preview Preview the candidate email decision for an application status change without mutating the application or drafts. yardstick applications email-decision preview --help applications email-decision apply Apply an application status-change email decision with idempotency metadata. yardstick applications email-decision apply --help email drafts list List candidate email drafts with optional status and email-type filters. yardstick email drafts list --help email drafts read Read a redacted candidate email draft. yardstick email drafts read --help email drafts preview Read rendered preview content for a candidate email draft. yardstick email drafts preview --help email drafts history Read candidate email draft history and provenance. yardstick email drafts history --help email drafts update Save mutable candidate email draft fields or set/clear a validated sender override for a pending draft. yardstick email drafts update --help email drafts send Send a pending candidate email draft with replay protection. --reclaim-not-delivered is the one optional flag. Use it when a draft is recorded as never delivered — the send was reserved but the email never left Yardstick, so the candidate was never told. The flag asks Yardstick to take that draft back and send it. The flag is a request, not permission. Yardstick refuses it unless the draft really is a never-delivered one, and refuses again if the round the email talks about has moved on since the draft was written — for example a cancellation email whose interview is no longer cancelled, or a confirmation email whose booking has since changed. In those cases nothing is sent and the command reports a conflict; write a fresh draft instead. Sending an ordinary pending draft is unchanged and needs no flag. yardstick email drafts send --help yardstick email drafts send --id ed_123 --reclaim-not-delivered email drafts discard Discard a pending candidate email draft without provider mutation. yardstick email drafts discard --help email automation-settings read Read candidate email automation settings. yardstick email automation-settings read --help email automation-settings update Update candidate email automation settings. yardstick email automation-settings update --help email sender-settings read Read redacted email sender settings with sanitized queue diagnostics. yardstick email sender-settings read --help email sender-connections list List redacted sender provider connection state. yardstick email sender-connections list --help email sender-connections prepare-oauth Prepare a browser OAuth handoff for an email sender connection. Not listed on hosted remote MCP; calling it there returns an explanation instead. Use the CLI, a local MCP client, or the dashboard. yardstick email sender-connections prepare-oauth --help email sender-connections refresh-discovery Refresh sender identity discovery for a provider connection. Not listed on hosted remote MCP; calling it there returns an explanation instead. Use the CLI, a local MCP client, or the dashboard. yardstick email sender-connections refresh-discovery --help email sender-connections disconnect Disconnect an email sender provider connection. Not listed on hosted remote MCP; calling it there returns an explanation instead. Use the CLI, a local MCP client, or the dashboard. yardstick email sender-connections disconnect --help email sender-defaults list List candidate email sender defaults. yardstick email sender-defaults list --help email sender-defaults set Set the default sender policy for a candidate email type. yardstick email sender-defaults set --help integrations workspace-health read Read sanitized Workspace integration health diagnostics. yardstick integrations workspace-health read --help email templates list List candidate email template policies without raw prompts. yardstick email templates list --help email templates read Read candidate email template detail without raw prompts. yardstick email templates read --help email templates preview Preview a candidate email template for sample variables. yardstick email templates preview --help email templates validate Validate candidate email template subject, HTML, and text bodies. yardstick email templates validate --help email templates publish Publish a validated candidate email template version. yardstick email templates publish --help email templates versions List immutable candidate email template versions. yardstick email templates versions --help email templates rollback Rollback a candidate email template to an immutable version. yardstick email templates rollback --help email templates preview-customization Preview AI sample customization for a candidate email template without publishing. yardstick email templates preview-customization --help --- ## Yardstick CLI URL: https://app.yardstick.team/docs/cli Summary: Install, authenticate, and run safe read commands against the Yardstick API from your terminal. The Yardstick CLI is a thin wrapper over the public Yardstick API. It runs as the yardstick binary from the @yardstick/cli npm package, authenticates against the same surface the API exposes, and prints redacted JSON to stdout. The same read commands you call from curl are available as named subcommands here. Throughout the CLI, the principal is whoever the credential acts as — the user or agent identity behind your token, along with the organization and scopes it was granted. Commands return only the records that principal can see. Install Install the public package from npm: npm install -g @yardstick/cli yardstick --help The package exposes only the yardstick binary. Repo-local scripts remain available for Yardstick development and diagnostics, but they are no longer the public install path: # From a checkout of the Yardstick repo: npm install npm run agent:cli -- whoami The packaged yardstick dispatcher defaults read commands to the first-party API origin at https://api.yardstick.team. Repo-local npm run agent:cli does not apply those packaged defaults; pass explicit endpoint flags or env vars when using the source checkout against production. Authenticate Authenticate once per machine with the packaged login flow. The default flow opens the Yardstick portal for approval and stores the resulting credential in the macOS Keychain. yardstick login --mode test --label "Local agent" Common flags (see yardstick login --help): --profile — store the credential under a named profile. Named profiles use deterministic profile: Keychain accounts; the unnamed default profile uses the default Keychain account. --mode test or --mode live — choose the API mode the credential is bound to. Test mode targets generic test-mode data in the is_test partition and never mutates live data. It does not expose the product's immutable Sample fixtures. --scopes — replace the complete requested scope set for this new login. Include every scope the new credential should have. Renew or add access Renew an existing profile without changing its access: yardstick reauthorize --profile Without --add-scopes, reauthorization carries forward every inherited scope that Yardstick can still issue. It lists any scope that must be dropped. To request more access, name only the additions: yardstick reauthorize \ --profile \ --add-scopes interview_plans:share,tasks:read The same flag works with yardstick auth reauthorize and yardstick mcp reauthorize. Yardstick combines the additions with the still-available scopes on the current credential, then opens the approval page. A signed-in approver must be allowed to grant every addition. If an addition is unavailable, approval stops instead of renewing with less access than you requested. Scope additions are always interactive. They are not available through the environment-token fallback. yardstick login --scopes ... starts a new login with the complete set you provide; it does not add to an existing credential. Inspect the saved credential without printing the token: yardstick status yardstick whoami Discover commands from the terminal The CLI help system is local metadata. Help commands do not read Keychain credentials, call the API, or check npm, so they are safe to run before login or inside an agent planning step. Start with the root overview, then drill into topics or exact commands: yardstick yardstick help topics yardstick help jobs yardstick help applications transition-preview yardstick applications transition-preview --help Use yardstick help scopes to see the secret scope catalog, the packaged login defaults, and how to compare command-required scopes with the effective scopes returned by yardstick whoami. candidates is a discovery alias, not a runnable namespace: yardstick help candidates yardstick help people yardstick help applications yardstick help opportunities There is no yardstick candidates ... command family. Candidate-facing work is split across person records, applications on jobs, and opportunity workflow items. Version and update checks Check the installed package version locally: yardstick --version yardstick version Ask npm for the latest published version only when you explicitly request it: yardstick version --check If the registry is unavailable, the command prints a non-secret "latest version unavailable" message and exits successfully. yardstick update is also informational: it prints the installed version, latest version when available, and the supported update command. It never runs a package manager on your machine. yardstick update # To update, run: npm install -g @yardstick/cli@latest Remove the credential when you're done: yardstick logout Agent note (cli) Each command inherits the profile's scope set. A 403 response means the call landed but the credential is under-scoped. Run yardstick reauthorize --add-scopes for the current profile, then review the additions in the browser. Use yardstick help or yardstick help to inspect required scopes before execution. Agent wrapper / scopes catalog: /docs/api/agent-wrapper API quickstart: /docs/api/quickstart Env-var fallback for CI / noninteractive use For headless environments (CI runners, container images, scheduled jobs) where the Keychain is unavailable, the CLI accepts an explicit env-var token. The supported variables are: YARDSTICK_API_TOKEN — the access token. The CLI uses this only when no Keychain credential is found. YARDSTICK_PROFILE — optional profile name to load. YARDSTICK_FUNCTIONS_BASE_URL — explicit Supabase functions base URL for the raw-functions fallback endpoint mode. YARDSTICK_API_BASE_URL plus YARDSTICK_API_ENDPOINT_MODE=api-origin — target the production API origin. Use placeholder tokens in any example you commit; never check in real tokens. YARDSTICK_API_TOKEN= \ YARDSTICK_API_ENDPOINT_MODE=api-origin \ YARDSTICK_API_BASE_URL=https://api.yardstick.team \ yardstick whoami Per-command flags like --token, --api-token, and --access-token are intentionally rejected — the only supported credential sources are the Keychain and YARDSTICK_API_TOKEN. Profiles, live vs test mode A profile bundles three things: a Keychain credential, an endpoint mode (production origin vs raw Supabase functions), and a live/test mode flag on the credential itself. Pass --profile to any CLI invocation to use a non-default profile; omit it to use default. yardstick login --profile sandbox --mode test yardstick jobs list --profile sandbox --limit 5 Live mode credentials hit production data. Test mode credentials hit the test partition and are the right default for local development, smoke tests, and CI. Request and response logging, redaction The CLI prints structured JSON to stdout. Every response object includes: credential_source — "keychain" or "env", so you can confirm the intended profile was loaded. idempotency_key_fingerprint (writes and previews only) — a stable short hash of the idempotency key the wrapper applied. The public API response body, with secrets redacted by the same redaction layer the rest of Yardstick uses. Errors are preserved verbatim from the public API (status code, error shape, request id). The CLI exits non-zero on any non-2xx response so shell pipelines fail loud. Try it A handful of safely-redacted read calls to verify the install works: yardstick whoami yardstick jobs list --limit 5 yardstick people list --limit 5 yardstick applications list --limit 5 See /docs/cli/commands for the full command reference and /docs/cli/safe-use for the approval-required mutation flow. Need help? Email support@yardstick.team --- ## CLI safe use URL: https://app.yardstick.team/docs/cli/safe-use Summary: Safe-by-default reads, approval-required mutations, transition-preview/bind, denied-state language, and the V1 boundary. This guide is for anyone — human or agent — running the Yardstick CLI in a context where a mistake matters. Reads run unattended. Mutations are typed and explicit, and the riskiest ones (status transitions, archives, publishes) require a separate human approval step before they commit. Safe by default Read commands (*-list, *-read, and the whoami / readiness / next-action family) do not mutate anything. They are safe to call repeatedly in tight loops, from CI, or from agent reasoning chains. They emit redacted JSON to stdout and exit non-zero only on HTTP errors. Help and version-discovery commands are also safe local metadata paths. yardstick, yardstick help topics, yardstick help scopes, yardstick help , and yardstick help do not read credentials or call the API. yardstick version is local-only; yardstick version --check and yardstick update may check npm for the latest version, but they do not mutate the installation. Anything that creates, updates, or deletes data is a mutation. Mutations fall into two buckets — direct writes and approval-required writes. CLI test mode operates only on generic test-mode data in the is_test partition. It is not the product's Sample mode: immutable Sample fixtures are browse-only and cannot be read, seeded, reset, retried, or mutated through CLI commands or generic API tokens. Direct mutations Most writes apply immediately when called. The wrapper still attaches an idempotency fingerprint and the public API audit log records the change, but no second confirmation step is required. Examples include people create, people update, jobs create, jobs close, departments members add, and access-grants revoke. See /docs/cli/commands for the full list — every command that isn't tagged "approval-required" is a direct write or a read. Pass --idempotency-key on retries to avoid duplicate writes: yardstick people create \ --email ada@example.com \ --idempotency-key create-ada-1 Approval-required mutations A small set of high-impact transitions require a two-call flow: a preview call that returns the binding requirements, and a bind call that commits using those binding fields and a matching idempotency key. The preview never mutates anything; the bind only succeeds if a human has approved the preview output and the idempotency key matches. The pairs in V1 are: applications transition-preview → applications transition-bind applications archive-preview → applications archive-bind job-postings publish-preview → job-postings publish-bind job-postings archive-preview → job-postings archive-bind interview-plans publish-preview → interview-plans publish-bind The wrapper enforces the boundary itself: passing binding fields to a preview call is rejected, and calling a bind without a matching preview idempotency key is rejected. Walk-through: an application transition The canonical example is moving an application to an approval-only status like Offer. Preview. Ask for the binding requirements. The response includes the binding shape, the idempotency key fingerprint, and any policy checks the bind call will enforce. yardstick applications transition-preview \ --application-id app_123 \ --status Offer \ --idempotency-key offer-app_123-2026-05-26 Human approval. Surface the preview output to a human approver. The approver returns a binding object — typically a signed approval id plus the approver's user id. Bind. Commit the transition using the same idempotency key and the approver's binding payload. yardstick applications transition-bind \ --application-id app_123 \ --body-json '{"status":"Offer","binding":{"approval_id":"apr_abc","approver_user_id":"usr_xyz"}}' \ --idempotency-key offer-app_123-2026-05-26 The bind fails closed if the binding payload doesn't match what the preview required or if the idempotency key has drifted. For the full binding-envelope reference, see /docs/api/agent-wrapper. Idempotency keys and request IDs Two flags shape how the CLI handles retries and tracing: --idempotency-key — required on bind calls (must match the paired preview), optional on direct writes and previews. The wrapper hashes the key into an idempotency_key_fingerprint returned in the response so callers can confirm matches without seeing the raw key. --request-id — propagates as the public API request_id. The same id appears in audit-log entries and event records, so passing a stable id makes correlated logs easy to grep. Both flags accept caller-chosen strings. Reuse the same idempotency key across preview → bind for a single approved action; use a new key for a new action. Before running an unfamiliar write, inspect command help: yardstick help applications transition-bind yardstick help job-postings publish-preview yardstick help scopes The command page lists required scopes and whether the operation is a read, direct write, approval preview, approval bind, archive bind, or publish bind. Denied states A non-2xx response is never silent — the CLI exits non-zero and prints the public API error verbatim. The three most common error shapes when running interactively: 401 — the access token is missing or expired. For Keychain credentials the CLI automatically exchanges the stored refresh secret for a fresh access token once and retries the request, so a single expired access token is invisible. The local MCP server (yardstick mcp serve) does the same: an access token that expires mid-session is refreshed and the tool call is retried once, so a session keeps working past the one-hour access-token lifetime without re-authenticating. The session model is a sliding window with secret rotation: each refresh slides the 90-day refresh window forward (so a continuously-active credential never lapses) and rotates the refresh secret — the server returns a new secret and the CLI persists it atomically, replacing the old one. You never manage the secret yourself; the rotation is invisible in normal use. Two hard limits still apply. (1) An absolute lifetime ceiling of 365 days from the original login caps the credential no matter how active it is; past it, refresh fails with absolute_lifetime_exceeded and you must reauthorize. (2) Reuse detection: a retired refresh secret is single-use for one dropped-response retry; replaying an older retired secret revokes the credential and logs a security event — so a stolen secret cannot be replayed indefinitely. If a 401 still surfaces, run yardstick auth refresh to mint a new access token. If the refresh secret has expired, been rotated out, hit the ceiling, or been revoked, run yardstick auth reauthorize. Without --add-scopes, it reopens browser approval with every still-issuable scope from the current credential selected. Scopes that are no longer issuable are dropped and shown on the approval page. To request more access, add --add-scopes ; Yardstick proposes the union and requires browser approval from someone allowed to grant every addition. An unavailable addition blocks approval instead of disappearing from the request. After a successful exchange, Yardstick revokes the old credential. Use yardstick login --scopes ... only to start a new credential with the complete scope set you provide, or to change identity or mode. In CI the env-token source (YARDSTICK_API_TOKEN) is never auto-refreshed — set or rotate the env var and retry. 403 — the credential is present but lacks a required scope, or the principal isn't authorized for the resource. Run yardstick reauthorize --add-scopes for the current profile. A human must review the addition in the browser, and Yardstick rejects it if that person cannot grant the scope. Do not retry the original command until approval succeeds. 404 — either the resource doesn't exist or the principal isn't authorized to see it. The CLI deliberately does not distinguish these two cases to avoid leaking the existence of records the caller can't read. Treat 404 as "not visible to me" rather than "definitely absent" when reporting back to a human. The full error envelope (status, error code, message, request id) is in the JSON response — agents should quote the envelope verbatim back to a human approver rather than paraphrasing. V1 wrapper boundary The CLI is a typed wrapper. Every call maps to one of the named commands on this site, and the CLI rejects anything else rather than forwarding an arbitrary request. The following are out of scope: CLI-backed hosted MCP tunneling. Hosted remote MCP is a separate HTTPS resource at https://api.yardstick.team/mcp; it is not a way to tunnel arbitrary CLI commands or raw HTTP requests through a remote transport. See /docs/mcp for hosted safety classes, explicit idempotency, insufficient-scope denial, and dashboard-required refusal behavior. OAuth via marketplace. There is no marketplace-driven OAuth authorization flow. Credentials are issued through yardstick login against the same backend the in-app sign-in uses. Raw arbitrary-request tool. The CLI does not expose a generic "send any HTTP request to the API" tool. If you need a surface that isn't enumerated in /docs/cli/commands, call the public API directly. Candidate namespace. yardstick help candidates is a product-language bridge to people, applications, and opportunities; it does not imply a runnable yardstick candidates ... command family. Need help? Email support@yardstick.team --- ## Yardstick Docs URL: https://app.yardstick.team/docs Summary: Documentation for the Yardstick interview planning platform — API, CLI, agents, and support. Welcome to Yardstick docs. Product guides Yardstick covers the full hiring workflow. Start with an overview of each part: Jobs, applications, and candidates — manage open jobs, track applications, and view candidate profiles. Interview plan builder — author interview plans for a job with the staged builder. Interview scheduling — generate scheduling links and let candidates self-schedule. Google and Microsoft integrations — understand provider access, data boundaries, and support status. Prospects, pools, activity & follow-ups — track prospects, log activity, and schedule follow-ups. Outreach sequences & auto-send — build outreach sequences, enroll prospects, and use auto-send. Scorecards and decisions — submit interview scorecards and record final recommendations. Built-in agents — keep feedback, interview preparation, and candidate updates moving with built-in workflows. Team, admin, and departments — manage org members, departments, roles, and admin settings. API token setup — create and use Yardstick API tokens. API OpenAPI explorer plus the cross-cutting concepts shared by every endpoint. API overview — entry point and surface tour. API quickstart — first successful call in a few minutes. API reference — OpenAPI explorer. Reporting search API — bounded role-health, funnel, stale-opportunity, missing-feedback, candidate-pool, and source-signal reporting families. Agent-auth + API wrapper concepts — scopes, key types, idempotency, request IDs, error envelopes, and the approval-preview flow. CLI First-party command-line interface that wraps the API with safe defaults. Yardstick CLI — install and authenticate. CLI commands — every command, grouped by category. CLI safe use — safe-by-default reads, approval-required mutations, and the V1 boundary. MCP Model Context Protocol access for chat apps, coding agents, local stdio hosts, and approved hosted remote clients. Yardstick MCP — choose the right setup path for your AI tool. MCP for chat apps — connect ChatGPT, Claude, or Perplexity to hosted Yardstick MCP. Yardstick in developer tools — ask Claude Code, Codex, or a local agent to install and configure Yardstick. MCP tool reference — local tool catalog plus hosted safety classes. Agents How AI agents and tools should evaluate, describe, and operate Yardstick. Agent guidance — how agents should interpret these docs. Using Yardstick from an agent — safe operation across API, CLI, and MCP. Agent note (ui-only) Agent notes flag the operability mode of the surrounding section — this hub is a UI-only landing page; agents should follow the API links above to reach machine-callable surfaces. API overview: /docs/api Need help? Email support@yardstick.team --- ## MCP for chat apps URL: https://app.yardstick.team/docs/mcp/chat-apps Summary: Connect Yardstick hosted MCP to ChatGPT, Claude, or Perplexity. Use this page when you want Yardstick inside a chat product: ChatGPT, Claude, or Perplexity. Connecting through the Model Context Protocol (MCP) lets the AI tool read your approved Yardstick data, and make changes when you allow it. These products connect to the hosted Yardstick MCP endpoint: https://api.yardstick.team/mcp Once connected, the AI tool sees the hosted Yardstick tool list. That list is a fixed 176 tools and is the same for everyone — it does not vary with your credential, organization, test/live partition, scopes, or which features your organization has turned on. What does vary per credential is which of those tools succeed when the AI tool actually calls them. The full tool reference documents 182 tools. Six are left off the hosted list because a chat app cannot carry them out: three file uploads and three email sender provider operations that need browser sign-in or a direct change at the provider. Those six stay callable over the hosted connection and return a short explanation instead of running. Use the Yardstick CLI, a local MCP client, or the Yardstick dashboard for them. Each tool carries a safety mode saying whether it only reads, changes data, needs an extra preview/approval step, or has to be finished in Yardstick itself. A tool that changes data also needs the credential's required write scopes and an idempotency key, which keeps an action from running twice. Hosted MCP has no global write switch: scopes, organization and mode isolation, tool safety, idempotency, and preview/bind checks govern each call independently. Hosted MCP does not offer raw HTTP passthrough, direct SQL access, or local shell access. Before you start You need: A Yardstick account with access to the organization you want the AI tool to read from. An approved hosted MCP credential or connector configuration for the chat app. The scopes required for the tools you plan to use, such as people:read or tasks:read. For a directory or integration review, use a dedicated organization populated with fake data. The reviewer credential normally defaults to mode=test, so supported writes affect only that fake partition. The consent page shows the verified relying-party host, a server-backed organization selector, the test data context, and the scopes that will be granted. It does not trust a client name or image supplied by the connector. Never paste bearer tokens into prompts, URLs, screenshots, or shared docs. If a chat product asks for authentication details, use its connector/app authentication form. Hosted OAuth and discovery The hosted resource is: https://api.yardstick.team/mcp The public discovery endpoints are: https://api.yardstick.team/.well-known/oauth-protected-resource/mcp https://api.yardstick.team/.well-known/oauth-authorization-server/api-agent-auth https://api.yardstick.team/api-agent-auth/.well-known/oauth-authorization-server Chat products use their own client metadata URL and registered callback. The Yardstick authorization server verifies that metadata through the supported authenticated CIMD path and binds the exact redirect before showing consent. If the relying party, callback, or organization is not verified, restart the connector and contact the integration owner; do not paste a token or use a different organization as a workaround. Sign-in resume carries only an opaque yao_... transaction reference, and approval is one-time and replay-safe. ChatGPT ChatGPT uses apps for MCP-backed integrations. Private or workspace apps can be created in Developer Mode; public distribution goes through the ChatGPT App Directory review flow. Open ChatGPT and go to Settings. Open Apps. If you are testing privately, enable Developer Mode if your plan and workspace settings allow it. Choose Create or Add custom app. Enter the Yardstick MCP server URL: https://api.yardstick.team/mcp Choose the authentication method your Yardstick workspace was provisioned for, then complete the authorization flow. Click Scan Tools and wait for ChatGPT to discover the Yardstick tools. Create the app, then start a new chat and enable the Yardstick app from the tools menu. For a shared workspace rollout, an admin or owner should publish the app from workspace settings after review. For public distribution, submit the app through OpenAI's app review flow after the hosted MCP endpoint, metadata, screenshots, privacy policy, and support links are ready. Claude Claude can add custom remote MCP connectors from the Connectors settings. Team and Enterprise workspaces usually require an owner or primary owner to add the connector before members can connect their own accounts. For individual Claude plans: Open Claude. Go to Settings. Open Connectors. Click Add custom connector. Enter the Yardstick MCP server URL: https://api.yardstick.team/mcp Open Advanced settings if your connector setup requires a client ID, client secret, or other authentication details. Click Add, then complete the Yardstick authorization flow. In a chat, open the tools/connectors menu and enable Yardstick for that conversation. For Team and Enterprise workspaces, an owner should add the connector from organization settings first. After that, members connect their own Yardstick accounts from personal connector settings. Claude also has a Connectors Directory for reviewed integrations. Treat that as the public-distribution path once the hosted MCP server is production-ready, with OAuth details, tool annotations, documentation, a privacy policy, and support links in place. Perplexity Perplexity supports custom remote MCP connectors on plans where MCP connectors are enabled. Availability and admin controls can vary by plan, so use this path only if your Perplexity account shows custom connector setup. For individual Pro/Max accounts when custom connectors are available: Open Perplexity. Go to Account settings. Open Connectors. Click Custom connector or Add custom connector. Choose Remote. Enter the Yardstick MCP server URL: https://api.yardstick.team/mcp Choose the authentication method your Yardstick workspace was provisioned for, then add any required client details. Add the connector and complete the Yardstick authorization flow. In a new conversation, open the connectors or sources menu and enable Yardstick. For Enterprise accounts, an admin may need to allow members to add custom connectors or add the Yardstick connector for the organization first. Staying connected After you complete the authorization flow once, the chat product keeps the connection alive on its own. Hosted access tokens are short-lived (about an hour), and the Yardstick authorization server supports the standard OAuth 2.0 refresh_token grant at its token endpoint. When an access token expires, the chat product silently exchanges its stored refresh token for a fresh access token in the background — you are not asked to approve the connector again. Each refresh rotates the refresh token: the server issues a new one and retires the old one. The chat product stores the rotated value automatically, so there is nothing to manage. You only need to re-authorize when the credential is revoked, when it reaches its maximum lifetime, or after a long period with no activity (the refresh window lapses). In those cases the product surfaces a normal re-connect prompt. Troubleshooting The product cannot list tools: confirm the server URL is exactly https://api.yardstick.team/mcp and the chat product can reach public HTTPS MCP servers. Authentication succeeds but tool calls fail: confirm the Yardstick credential has the required public API scopes. Write actions are denied: confirm the credential has the required write scope, targets the intended organization and test/live partition, and includes the required idempotency_key. Some approval tools require a preview before a bind call. Dashboard-confirmed tools return dashboard_confirmation_required and must be completed in Yardstick. A test-mode credential cannot mint live-only public links or perform provider mutations. If a correctly scoped fake-data write still fails, use the support link at the end of this page. The connector asks for a local command: you are in a local MCP setup screen. Use Yardstick in developer tools instead. Perplexity does not show custom connectors: your current plan, platform, or workspace settings may not have remote MCP connector access enabled. The connector keeps asking you to re-authorize: routine access-token expiry is refreshed silently and should not prompt you. A repeated re-connect prompt means the refresh token is no longer valid — the credential was revoked, it hit its maximum lifetime, or the refresh window lapsed after a long idle period. Complete the authorization flow once more to reconnect. References OpenAI: Apps in ChatGPT OpenAI: Submit and maintain your app Claude: custom connectors using remote MCP Claude: submitting to the Connectors Directory Perplexity: custom remote MCP connectors announcement Support Questions? Need help? Email support@yardstick.team --- ## Yardstick in developer tools URL: https://app.yardstick.team/docs/mcp/developer-tools Summary: Connect Claude Code, Cursor, Codex, or another coding agent to Yardstick over the hosted MCP endpoint, a local MCP server, or the CLI. Use this page when you want Claude Code, Codex, Cursor, or another coding agent to work with Yardstick. The recommended path is to copy a setup request into your agent first. The agent can install the CLI, inspect command help, and edit local MCP config; you only need to step in for browser approval, macOS Keychain prompts, or organization selection. There are two valid patterns: CLI-first: install the Yardstick CLI, then tell your coding tool or agent that it may use yardstick commands. MCP-first: set up the coding tool so it can discover Yardstick tools through the Model Context Protocol (MCP), an open standard that lets AI tools connect to outside services. Choose one as the primary integration. You do not need to configure MCP just because you installed the CLI, and you do not need to teach the agent CLI commands if you want it to operate through MCP tools. If you are using ChatGPT, Claude in the browser, or Perplexity, use MCP for chat apps instead. Two ways to connect MCP MCP-first setups come in two shapes, and most coding tools support both: Hosted: point the tool at https://api.yardstick.team/mcp and sign in through your browser once. Nothing to install, and Yardstick keeps the server up to date. Use this unless you have a reason not to. Local: the tool launches yardstick mcp serve on your machine and talks to it over stdio. Use this when the tool must run offline, when you want tool activity tied to a named local credential profile, or when you need one of the six tools the hosted connection does not publish. Hosted publishes 176 of the 182 tools in the tool reference. The six it leaves off — three file uploads and three email sender provider operations — stay callable over hosted but return a short explanation rather than running. The CLI and a local MCP server carry all of them. Both shapes use scoped Yardstick credentials, and neither wants a bearer token written into a config file: hosted signs in through the browser, and local reads the credential from the profile you approved. One prerequisite applies to hosted only. Yardstick identifies a connecting tool by a Client ID Metadata Document (CIMD) and deliberately does not offer OAuth Dynamic Client Registration. A tool that supports CIMD discovers this on its own and the sign-in just works; Claude Code does. A tool that can only register dynamically stops with an error about the server not supporting dynamic client registration. That is not a misconfiguration on your side — use the local shape with that tool. Start with your agent Paste one of these requests into the coding tool you want to use with Yardstick. CLI-first agent request Use this when you want the agent to treat Yardstick like any other command line tool. Install and configure Yardstick CLI access for this repo. Use the npm package `@yardstick/cli`. Run `yardstick --help` and inspect the relevant `yardstick --help` output before using a command you have not used in this repo. Use a dedicated CLI profile named `agent` unless I name a different profile. If authentication opens a browser, asks for macOS Keychain access, or asks me to choose an organization, stop and ask me to complete that step. After setup, add a short repo instruction that says agents may use `yardstick --profile agent` for approved Yardstick tasks. Do not put bearer tokens, refresh secrets, OTPs, or API tokens in repo files, prompts, MCP config, or command arguments. MCP-first agent request Use this when you want the coding tool to discover Yardstick as typed MCP tools. Install and configure Yardstick MCP access for this local agent host. Use the npm package `@yardstick/cli`. Run `yardstick mcp --help` before editing MCP config. Create one dedicated MCP profile for this host: - Claude Code: `claude-code-mcp` - Cursor: `cursor-mcp` - Codex: `codex-mcp` - Other local clients: `local-agent` Register a stdio MCP server that runs: `yardstick mcp serve --profile ` If authentication opens a browser, asks for macOS Keychain access, or asks me to choose an organization, stop and ask me to complete that step. Do not put bearer tokens, refresh secrets, OTPs, or API tokens in repo files, prompts, MCP config, or command arguments. Manual setup: CLI-first Use these commands if you prefer to run setup yourself, or if your agent asks you to complete a terminal step. npm install -g @yardstick/cli yardstick --help Authenticate the CLI: yardstick login \ --profile agent \ --mode test \ --scopes people:read,tasks:read \ --label "Local agent CLI" yardstick whoami --profile agent Then tell the coding tool what it is allowed to do. In a repo-level instruction file such as AGENTS.md or CLAUDE.md, write the operating rule in plain language: # Yardstick CLI Agents may use the installed `yardstick` CLI for approved Yardstick tasks. Use `yardstick --help` and `yardstick --help` before running a command you have not used in this repository. Use `--profile agent` unless the user names a different profile. Do not pass bearer tokens in prompts, config files, or command arguments. For the CLI command catalog and safety model, read Yardstick CLI and CLI safe use. Manual setup: MCP-first Use these commands if you prefer to register MCP yourself. The host launches the Yardstick MCP server and communicates with it over stdio. Install the package that contains the local MCP server: npm install -g @yardstick/cli yardstick mcp --help Create one named MCP profile per host. This keeps tool activity attributable and makes it easier to rotate credentials later. yardstick mcp login \ --profile claude-code-mcp \ --mode test \ --scopes people:read,tasks:read \ --label "Claude Code MCP" yardstick mcp status --profile claude-code-mcp The browser approval flow stores the credential in macOS Keychain for normal local use. MCP host config should include only the command and profile selector, not bearer tokens, refresh secrets, or OTPs. Claude Code For CLI-first use, paste the CLI-first agent request into Claude Code, or add the project instruction from Manual setup: CLI-first to your repo's CLAUDE.md and let Claude Code run yardstick commands. Claude Code, hosted Add the hosted endpoint as an HTTP MCP server: claude mcp add --transport http yardstick https://api.yardstick.team/mcp Verify it registered: claude mcp list Start a Claude Code session and run /mcp. Choose Yardstick and complete the browser sign-in. Claude Code stores the resulting credential itself and refreshes it in the background, so there is no token to copy and nothing to put in a config file. After the sign-in finishes, /mcp shows Yardstick as connected and its tools become available in the session. Add --scope user to the claude mcp add command to make Yardstick available in every project rather than only the current directory. Claude Code, local Paste the MCP-first agent request into Claude Code, or register the local server yourself after creating an MCP profile: claude mcp add --transport stdio yardstick \ -- yardstick mcp serve --profile claude-code-mcp Verify the server is registered: claude mcp list Then start a Claude Code session and use /mcp to inspect or authenticate MCP servers if Claude prompts you to do so. Cursor Cursor, hosted Cursor reads MCP servers from ~/.cursor/mcp.json for every project, or from .cursor/mcp.json inside one project. Create the file if it does not exist and add the hosted endpoint: { "mcpServers": { "yardstick": { "url": "https://api.yardstick.team/mcp" } } } Save the file, then open Cursor's settings and find the MCP section. If Yardstick appears there with a sign-in prompt, complete the browser approval and the tool list should load. Cursor holds the credential and refreshes it on its own — do not add an Authorization header or a token to mcp.json. If Cursor reports that it cannot register with the server, it is trying to register dynamically, which Yardstick does not offer (see Two ways to connect MCP). Use Cursor, local instead. Cursor, local Use the same file with the local server instead. Create a profile first with yardstick mcp login --profile cursor-mcp (see Manual setup: MCP-first), then: { "mcpServers": { "yardstick": { "command": "yardstick", "args": ["mcp", "serve", "--profile", "cursor-mcp"] } } } Cursor launches yardstick itself, so the command must be on the PATH Cursor sees. If it is not found, install the CLI globally with npm install -g @yardstick/cli and restart Cursor. Codex For CLI-first use, paste the CLI-first agent request into Codex, or add the project instruction from Manual setup: CLI-first to your repo's AGENTS.md and let Codex run yardstick commands. For MCP-first use, paste the MCP-first agent request into Codex, or add Yardstick to the Codex MCP registry: codex mcp add yardstick \ -- yardstick mcp serve --profile codex-mcp Verify the server is registered: codex mcp list If you prefer editing config directly, add the equivalent stdio server entry to ~/.codex/config.toml: [mcp_servers.yardstick] command = "yardstick" args = ["mcp", "serve", "--profile", "codex-mcp"] Other MCP clients Most MCP clients use the same mcpServers shape, so the two entries below work in any of them. Any client that speaks MCP can reach Yardstick over one of these two transports; only the location of the config file differs. For a hosted connection, give the client the URL and let it run the browser sign-in. This needs a client that supports CIMD; if it only registers dynamically, use the local entry below instead (see Two ways to connect MCP): { "mcpServers": { "yardstick": { "url": "https://api.yardstick.team/mcp" } } } For a local connection, use the profile name you approved for that client: { "mcpServers": { "yardstick": { "command": "yardstick", "args": ["mcp", "serve", "--profile", "local-agent"] } } } Restart or reload the client after editing its MCP config. Credentials CLI-first and MCP-first both use scoped Yardstick credentials, but they should be created as separate profiles so audit and revocation stay clear. The local MCP server resolves credentials this way: Keychain first: if the host has run yardstick mcp login --profile , the token lives in the OS keychain under that profile. Environment fallback: if no keychain entry resolves, the server reads YARDSTICK_API_TOKEN from the environment. Use the environment fallback only for CI or sandboxed hosts that cannot reach the keychain. Do not put long-lived tokens in shared MCP config files. A hosted connection does not use a CLI profile at all. The coding tool runs the browser sign-in itself, stores the credential in its own store, and renews it in the background, so a hosted mcp.json entry holds only the URL. A hosted credential is tied to the https://api.yardstick.team/mcp endpoint and is rejected on the direct /v1/* API routes, so it is not interchangeable with a CLI token. Troubleshooting CLI command fails with yardstick: command not found: confirm the global npm bin directory is on the PATH visible to the AI host. MCP server starts but has no access: run yardstick mcp status --profile and confirm the profile exists. Access stopped after ~90 days (refresh secret lapsed): run yardstick mcp reauthorize --profile . Without --add-scopes, it opens browser approval with every still-issuable scope from the profile selected and lists any dropped scope. To request more access, add --add-scopes . Yardstick combines the additions with the inherited scopes and requires a human who can grant them to approve the request. An unavailable addition blocks approval instead of being removed. After a successful exchange, the renewed credential replaces the old one. Use yardstick mcp login --scopes ... only to start a new profile with the complete scope set you provide. The wrong organization appears: create a separate profile for this host and approve it against the intended Yardstick organization. For a hosted connection, disconnect it in the tool and sign in again, choosing the intended organization on the Yardstick approval page. The host expects a URL: it wants a hosted connection, not a local command. Use https://api.yardstick.team/mcp — see Claude Code, hosted or Cursor, hosted for the exact config. If the host is ChatGPT, Claude in the browser, or Perplexity, use MCP for chat apps instead. The tool says the server does not support dynamic client registration: that is expected. Yardstick identifies connecting tools by a Client ID Metadata Document instead — see Two ways to connect MCP. Tools that support CIMD connect with no extra step; tools that do not cannot use the hosted endpoint yet, so set that tool up with the local stdio server. A tool you expected is missing over a hosted connection: hosted publishes 176 of the 182 tools in the tool reference. The six file upload and email sender provider tools are not listed there; calling one returns an explanation rather than running. Use the CLI, a local MCP server, or the Yardstick dashboard for those. References Claude Code MCP docs Cursor MCP docs OpenAI Codex MCP docs Support Questions? Need help? Email support@yardstick.team --- ## Yardstick MCP URL: https://app.yardstick.team/docs/mcp Summary: Connect Yardstick to ChatGPT, Claude, Perplexity, Claude Code, Codex, and other MCP-compatible tools. The Model Context Protocol (MCP) is an open standard that lets AI tools connect to outside services. Yardstick MCP uses it to give an AI tool read access to approved Yardstick data, and write access when you allow it. Start with the tool you use: ChatGPT, Claude, and Perplexity: use hosted MCP. The AI product connects to Yardstick over HTTPS at https://api.yardstick.team/mcp. Claude Code, Codex, and local coding agents: choose either CLI-first or MCP-first. CLI-first means the agent runs yardstick commands. MCP-first means the agent connects to a Yardstick MCP server. You do not need to choose "hosted" or "local" as a product concept before you begin. Pick the page for your AI tool, then follow that setup path. Connect ChatGPT, Claude, or Perplexity Use Yardstick from Claude Code, Codex, or local agents MCP tool reference What you can connect Hosted connection: a public HTTPS endpoint at https://api.yardstick.team/mcp. Chat products such as ChatGPT, Claude, and Perplexity connect here. Hosted tool list: the hosted endpoint publishes a fixed list of 176 tools, and that list is the same for every caller — it does not vary by credential, organization, test/live partition, scopes, or enabled features. Each tool carries safety metadata saying whether it is read-only, changes data, or needs an extra approval step. Six tools are not on that list: three file uploads and three email sender provider operations, because the hosted transport cannot carry them out. They stay callable on hosted — asking for one returns a short explanation naming a surface that can run it. Use the Yardstick CLI, a local MCP client, or the dashboard for those six. See the tool reference for the full set of 182 documented tools. Hosted writes: scoped credentials, organization and test/live partition isolation, tool safety rules, and a one-time idempotency key let supported tools make the changes you request without repeating them. Preview/bind tools also require the matching approval binding. Local connection: the yardstick command-line tool runs a Yardstick MCP server on your own machine for coding agents. Command-line option: an agent can also run yardstick commands directly, without connecting through MCP at all. The package to install: @yardstick/cli, which gives you the yardstick command. Where credentials live: the macOS Keychain for normal local use; an environment variable only for CI or sandboxed machines that can't reach the Keychain. Which setup should I use? Use the hosted setup when the AI product has a connector or app screen and asks for an MCP server URL. ChatGPT, Claude, and Perplexity work this way. Hosted MCP is the best fit for chat workflows because nothing runs on your machine, and a workspace admin can approve or share the connector for everyone. Use CLI-first setup when you want a coding tool or agent to call Yardstick the same way a person would in a terminal. Install the Yardstick CLI, then document the approved commands and safety rules in the agent's project instructions. Use MCP-first setup when you want the coding tool to discover typed Yardstick tools through its MCP registry. Claude Code, Codex, Cursor, and other local agent hosts can fit either model, depending on how you want agents to operate. Hosted connection Hosted MCP is available at: https://api.yardstick.team/mcp The protected-resource metadata endpoint is public: https://api.yardstick.team/.well-known/oauth-protected-resource/mcp A hosted credential works only with the MCP endpoint at https://api.yardstick.team/mcp. The same token is rejected if you try to use it on the regular /v1/* API routes. Hosted credentials are bound to an organization, a test/live mode partition, and an approved scope set. Create a hosted MCP credential with the yardstick command: yardstick mcp login \ --hosted \ --profile hosted-agent \ --mode test \ --scopes people:read,people:write,tasks:read \ --label "Hosted MCP agent" Hosted MCP shows the approved set of tools and what each one can do. A connected tool can read data, check status, and create deep links right away. A supported write can make a change when the credential has the right scope, the call stays inside its organization and mode partition, and the call includes the required idempotency key. Preview/bind operations additionally require a matching approval binding. There is no global hosted-write switch. Some tools appear in the list but won't run directly: A tool can be unavailable because its scope, organization, mode partition, or feature/provider prerequisite does not allow the requested operation. Tools that need approval run in two steps: a preview, then a confirm. A few actions must be finished in Yardstick itself. These return dashboard_confirmation_required until you complete them in the app. Hosted MCP also rejects a call that's missing its credential, uses a token in the URL, uses a token meant for something else, lacks the right scopes, or sends a malformed or oversized request. Hosted MCP does not offer raw HTTP passthrough, direct SQL access, or local shell access. MCP test mode operates only on generic test-mode data in the is_test partition. It is not the product's Sample mode: immutable Sample fixtures are browse-only and cannot be read, seeded, reset, retried, or mutated through MCP tools or generic API tokens. For chat-product setup steps, read Connect ChatGPT, Claude, or Perplexity. Local connection For coding agents, the yardstick mcp serve command runs a Yardstick MCP server on your own machine. Your agent launches it and talks to it directly. Nothing listens on the network, and the server shuts down when your agent closes. Every tool you can call this way has a matching yardstick command, so the same actions are available whether your agent connects through MCP or runs commands in a terminal. A long session keeps working on its own. Access expires about once an hour, but the server renews it for you in the background and retries the call, so you are not asked to log in again. You only need to log in again if your credential is revoked or expires after a long time without use. When that happens, you get a clear message telling you to run yardstick auth refresh or yardstick login. The YARDSTICK_API_TOKEN environment variable is never renewed automatically. For coding-agent setup choices, read Use Yardstick from Claude Code, Codex, or local agents. Credentials The MCP server finds your credentials the same way the yardstick command does: Keychain first. If you've run yardstick mcp login --profile , your token is stored in the OS keychain under that profile. Environment variable. If there's no keychain entry, the server reads YARDSTICK_API_TOKEN from the environment. Use this only for CI or sandboxed machines that can't reach the keychain. For the full credential setup — profiles, scopes, and rotation — read /docs/cli. MCP credentials are tracked separately from regular command-line credentials, so you can check status, review usage, and revoke them on their own. Tokens are hidden from error messages. If you see a token shown as redacted in a tool response, the server removed it on purpose before returning the result. Approval boundaries Some actions need explicit approval before they can change anything. These are split into two tools: *_preview — returns a preview of the action, including the exact input the next step must confirm. *_bind — confirms the previewed action with a matching binding object and idempotency key. An agent can't change a protected resource by calling the preview alone, and the confirm step rejects any input that doesn't match the preview it saw. The yardstick command enforces the same rule — see /docs/cli/safe-use for more. Every tool also accepts request_id and idempotency_key fields. Both are honored end to end, so retrying a tool call returns the same result instead of writing the same change twice. Support Questions? Need help? Email support@yardstick.team --- ## MCP tool reference URL: https://app.yardstick.team/docs/mcp/tools Summary: Every Yardstick MCP tool, grouped by resource, with safety mode and an example input. This page documents all 182 Yardstick MCP tools. The local MCP server offers every one of them, and each tool has a matching yardstick command, so the same actions are available whether you connect through MCP or run commands in a terminal. The hosted endpoint at https://api.yardstick.team/mcp publishes 176 of those 182. That list is fixed: every caller gets the same 176 tools, whatever the credential, organization, test/live partition, scopes, or feature prerequisites. Six tools are left off it because the hosted transport cannot carry them out — three file uploads and three email sender provider operations. They are still callable on hosted: asking for one returns a short explanation naming a surface that can run it. Use the Yardstick CLI, a local MCP client, or the dashboard for those six. Whether a listed tool succeeds is a separate question from whether it appears. A call is checked against your credential's scopes, its organization and test/live partition, and the tool's safety mode. A tool that changes data needs the right credential scope and an idempotency_key; preview/bind tools also need their matching approval binding. There is no global hosted-write switch. A tool that must be finished in the app returns dashboard_confirmation_required until you complete it in Yardstick. Each entry below lists the canonical MCP tool name, its CLI equivalent, a safety mode chip, a one-line description, and one realistic input example. The request_id and idempotency_key fields are accepted by every tool but omitted from the per-tool examples for brevity. Modes read — query-only, no mutation, safe to call without explicit user intent. write — mutates state; pair with an idempotency key on retries. approval-required — split into *_preview (returns approval metadata) and *_bind (binds the previewed action). The bind tool rejects any input that doesn't match the preview. binary-upload — moves a file over a signed upload URL rather than the MCP message channel. Carried by the CLI and local MCP. Not listed on hosted remote MCP, because that transport has no byte channel; calling it there still works and returns an explanation pointing at the dashboard, the CLI, or a local MCP client. hosted unsupported — carried by the CLI and local MCP. Not listed on hosted remote MCP, because the operation needs browser OAuth or a direct change at the email provider; calling it there still works and returns an explanation pointing at the dashboard, the CLI, or a local MCP client. Identity yardstick_identity CLI equivalent: whoami. Mode: read. Return who you're acting as — the current Yardstick principal (the account and scopes the connection is using). Other tools return what this principal is allowed to see. {} Tasks yardstick_tasks_list CLI equivalent: tasks list. Mode: read. List Yardstick tasks visible to the current principal. { "limit": 20 } yardstick_tasks_deep_link CLI equivalent: tasks deep-link. Mode: read. Create a public task deep link for a caller-supplied task id. { "task_id": "tsk_abc123" } People yardstick_people_list CLI equivalent: people list. Mode: read. List people visible to the current principal. { "limit": 20 } yardstick_people_read CLI equivalent: people read. Mode: read. Read one person by public id. { "person_id": "per_abc123" } yardstick_people_create CLI equivalent: people create. Mode: write. Create a person through the public Yardstick API. { "name": "Avery Quinn", "email": "avery@example.com" } yardstick_people_update CLI equivalent: people update. Mode: write. Update one person with schema-bound public API fields. { "person_id": "per_abc123", "phone": "+15551234567" } yardstick_people_resume_upload_create CLI equivalent: people upload-resume. Mode: binary-upload. Upload a PDF or DOCX resume for a person, then attach and parse it. Reads a single local file path. Not listed on hosted remote MCP; calling it there returns an explanation instead. Use the CLI, a local MCP client, or the dashboard. { "person_id": "per_abc123", "file": "./resume.pdf" } yardstick_people_resume_upload_finalize CLI equivalent: people finalize-resume-upload. Mode: binary-upload. Finalize a resume upload session created earlier: re-validate, attach, and parse. Not listed on hosted remote MCP; calling it there returns an explanation instead. Use the CLI, a local MCP client, or the dashboard. { "person_id": "per_abc123", "session_id": "rus_abc123" } Prospects yardstick_prospects_list CLI equivalent: prospects list. Mode: read. List active Talent CRM prospects visible to the current principal. { "limit": 20 } yardstick_prospects_read CLI equivalent: prospects read. Mode: read. Read one Talent CRM prospect by public id. { "prospect_id": "pro_abc123" } yardstick_prospects_create CLI equivalent: prospects create. Mode: write. Create Talent CRM prospect relationship state for an existing person. last_contacted_at must not be in the future. A value more than five minutes ahead of the server clock — the tolerance absorbs ordinary clock skew — is rejected with a 400 naming last_contacted_at. Anything at or before now, including a backdated value, is accepted. { "person_id": "per_abc123", "source_label": "referral" } Omitting owner_user_id gives the new prospect to the human whose API key you are using; "owner_user_id": null leaves it deliberately unowned; a user id gives it to that person, who must be an active member of the same organization or the call is refused with 400 invalid_request_body and nothing is written. This matters for follow-ups: a prospect created here used to have no owner, so setting a follow-up date on it afterwards produced no task at all. Now that it has an owner, a later yardstick_prospects_update setting next_follow_up_at puts a Follow up with … task on that owner's list. Send "owner_user_id": null for the old ownerless behavior, or name someone else to route the task to them. This tool takes an existing person_id and never creates a person, so a refused create leaves nothing behind. yardstick_prospects_convert_preview CLI equivalent: prospects convert-preview. Mode: approval-required. Preview one Prospect-to-Application conversion without imports, merge, outreach, ranking, or Opportunity writes. { "prospect_id": "pro_abc123", "job_posting_id": "jp_abc123", "idempotency_key": "prospect-convert-key" } yardstick_prospects_convert_bind CLI equivalent: prospects convert-bind. Mode: approval-required. Bind an approved conversion preview with matching idempotency key and approval metadata. { "prospect_id": "pro_abc123", "job_posting_id": "jp_abc123", "idempotency_key": "prospect-convert-key", "binding": { "preview_hash": "...", "approved_action_key": "prospect.convert_to_application", "approved_input_hash": "...", "approved_idempotency_key": "prospect-convert-key", "resource_version_precondition": "..." } } yardstick_prospects_outreach_preview CLI equivalent: prospects outreach-preview. Mode: read. Preview one prospect outreach draft without creating a draft, sending email, enrolling a sequence, or creating an application. { "prospect_id": "pro_abc123", "job_posting_id": "jp_abc123", "outreach_intent_key": "staff-eng-warm" } yardstick_prospects_outreach_create_draft CLI equivalent: prospects outreach-create-draft. Mode: write. Create a pending review prospect outreach email draft. Sending remains on email-drafts send and requires communications:send. { "prospect_id": "pro_abc123", "job_posting_id": "jp_abc123", "idempotency_key": "prospect-outreach-draft-1", "subject": "Staff Engineer conversation" } yardstick_prospect_imports_dry_run CLI equivalent: prospects import-dry-run. Mode: approval-required. Preview a structured-row Prospect CRM import. Accepts JSON rows only: no raw CSV reads, hosted MCP file access, or resume binaries. Exact same-org/same-mode email is the only automatic match; fuzzy suggestions require explicit apply decisions. A row whose last_contacted_at is more than five minutes ahead of the server clock is marked invalid in the preview, with the row error code last_contacted_at_in_future, and its proposed action becomes skip. This is per row, not per batch: one mistyped year costs that row, and every other row in the upload still previews and applies normally. { "idempotency_key": "prospect-import-preview-1", "rows": [{ "name": "Ada Lovelace", "email": "ada@example.com" }, { "name": "Grace Hopper", "current_company": "Navy" }] } yardstick_prospect_imports_read CLI equivalent: prospects import-read. Mode: read. Read one Prospect CRM import preview/apply batch by public id. { "import_id": "pib_abc123" } yardstick_prospect_imports_apply CLI equivalent: prospects import-apply. Mode: approval-required. Apply a stored import preview with preview_hash and explicit row decisions for advisory fuzzy suggestions. A row the preview marked invalid — including one with a future last_contacted_at — is skipped here while the rest of the batch is applied. Never sends outreach, creates applications, ranks source quality, merges people, or deletes people. { "import_id": "pib_abc123", "idempotency_key": "prospect-import-apply-1", "preview_hash": "...", "decisions": [{ "row_index": 1, "input_hash": "...", "decision": "link_existing", "person_id": "per_abc123" }] } Owners follow the same three-way rule per row: no owner_user_id gives a newly created prospect to the human behind the key, null leaves it unowned, and a user id names an owner. On a row that matches a prospect you already have, an omitted or null owner never reassigns it — import does not quietly take a prospect off a teammate. An import row cannot set a follow-up date, so the owner it records creates no task by itself. A row naming someone who is not an active member is caught at the dry run, coming back invalid with owner_not_member in its errors list. Applying the batch anyway records that row skipped rather than failed. It only reaches failed if that owner loses active membership between the dry run and the apply, with error_code owner_not_member while the rest of the batch applies. Apply checks again before creating a new person. Only the narrower race where the owner loses active membership after that check can leave the failed row's new person record behind. Recovering it means a fresh dry run, not a second apply: applying is one-shot, and a batch that already reported applied, partially_applied, or failed refuses the next attempt with a 409. (The remembered person only covers replaying an apply that died mid-run and left the batch previewed.) On the fresh run the saved person is matched automatically when the row carries an email; a name-only row relies on an advisory suggestion from a capped scan of your people, so add the email if you want the match to be certain. yardstick_source_links_list CLI equivalent: source-links list. Mode: read. List source/referral attribution links without raw token material or source quality ranking. { "job_posting_id": "jp_abc123", "include_disabled": true } yardstick_source_links_read CLI equivalent: source-links read. Mode: read. Read one source/referral attribution link by public id without raw token material. { "source_link_id": "slink_abc123" } yardstick_source_links_create CLI equivalent: source-links create. Mode: write. Create an opaque public apply source/referral link for a published job posting. The raw source_token is returned only once on create. Reads return token_hint, and active token-bearing links also return a copyable public_url. { "job_posting_id": "jp_abc123", "source_label": "Founder referral", "referrer_name": "Alex Referrer" } yardstick_source_links_disable CLI equivalent: source-links disable. Mode: write. Disable a source/referral link so future public applies from that URL fail closed without leaking source metadata. { "source_link_id": "slink_abc123", "reason": "Campaign ended" } yardstick_prospects_update CLI equivalent: prospects update. Mode: write. Update bounded Talent CRM prospect relationship fields. last_contacted_at must not be in the future. A value more than five minutes ahead of the server clock — the tolerance absorbs ordinary clock skew — is rejected with a 400 naming last_contacted_at. Backdating is still allowed: an explicit write wins, and may move the date earlier, unlike the automatic updates described under yardstick_prospect_activities_create. { "prospect_id": "pro_abc123", "relationship_status": "archived" } Omitting owner_user_id on an update leaves the current owner untouched — it never falls back to the key holder. Only an explicit user id reassigns a prospect, and an explicit null unassigns it. Reassigning a prospect that already has a follow-up date moves its Follow up with … task to the new owner. yardstick_prospect_activities_list CLI equivalent: prospects activities list. Mode: read. List bounded activity records for one Talent CRM prospect. { "prospect_id": "pro_abc123", "limit": 20 } yardstick_prospect_activities_create CLI equivalent: prospects activities create. Mode: write. Record something that happened with a prospect on their timeline. This has a side effect on the prospect record. A call or a meeting counts as having contacted the person, so creating one moves that prospect's last_contacted_at forward to the activity's occurred_at — which changes what the stale-prospect views and the "last touch" reporting figures say about them. A note, a source record, or a status_change does not count as contact and leaves the date alone. The date only ever moves forward this way: recording an older call never drags it back over a more recent one. occurred_at must not be in the future. A value more than five minutes ahead of the server clock is rejected with a 400 naming occurred_at; the five minutes absorb ordinary clock skew between the calling machine and the server. Backdating is unaffected — an occurred_at in the past is accepted, and simply does not move a contact date that is already later. { "prospect_id": "pro_abc123", "activity_type": "note", "body": "Prefers to revisit after Q3" } Talent Pools yardstick_talent_pools_list CLI equivalent: talent-pools list. Mode: read. List Talent CRM pools visible to the current principal. Archived pools are left out unless include_archived is true. { "limit": 20, "include_archived": false } yardstick_talent_pools_read CLI equivalent: talent-pools read. Mode: read. Read one Talent CRM pool by public id. { "pool_id": "pool_abc123" } yardstick_talent_pools_create CLI equivalent: talent-pools create. Mode: write. Create a Talent CRM pool. { "name": "Founding engineers" } yardstick_talent_pools_update CLI equivalent: talent-pools update. Mode: write. Update bounded Talent CRM pool fields. { "pool_id": "pool_abc123", "description": "High-intent referrals" } yardstick_talent_pool_members_list CLI equivalent: talent-pools members list. Mode: read. List active prospect memberships for one Talent CRM pool. { "pool_id": "pool_abc123", "limit": 20 } yardstick_talent_pool_members_add CLI equivalent: talent-pools members add. Mode: write. Add an existing prospect to a Talent CRM pool. { "pool_id": "pool_abc123", "prospect_id": "pro_abc123" } yardstick_talent_pool_members_remove CLI equivalent: talent-pools members remove. Mode: write. Remove an active prospect membership from a Talent CRM pool. { "pool_id": "pool_abc123", "prospect_id": "pro_abc123" } ATS imports yardstick_ats_imports_dry_run CLI equivalent: ats-imports dry-run. Mode: approval-required. Preview an ATS import of candidates, jobs, and applications. A CSV import sends structured JSON rows (source_kind: csv); no raw CSV or archive file is read or stored. A Greenhouse import references an uploaded archive (source_kind: greenhouse, session_id). Exact same-org/same-mode candidate email is the only automatic match; fuzzy or low-confidence stage matches require explicit apply decisions. { "idempotency_key": "ats-import-preview-1", "source_kind": "csv", "candidates": [{ "name": "Ada Lovelace", "email": "ada@example.com" }], "jobs": [{ "title": "Staff Engineer" }], "applications": [{ "candidate_email": "ada@example.com", "job_title": "Staff Engineer", "stage": "Applied" }] } yardstick_ats_imports_read CLI equivalent: ats-imports read. Mode: read. Read one ATS import dry-run/apply batch and its rows by public id. { "import_id": "atim_abc123" } yardstick_ats_imports_apply CLI equivalent: ats-imports apply. Mode: approval-required. Apply an ATS import preview with its stored preview_hash. Creates people, jobs, stub interview plans, job postings, and applications with idempotent replay; a preview_hash that no longer matches the stored dry-run is rejected. Never sends outreach, merges people, or deletes records. { "import_id": "atim_abc123", "idempotency_key": "ats-import-apply-1", "preview_hash": "..." } yardstick_ats_imports_archive_upload_create CLI equivalent: ats-imports upload-archive. Mode: binary-upload. Upload a Greenhouse export archive (.zip) over a single-use, short-TTL signed upload URL, then preview it with ats-imports dry-run --source-kind greenhouse --session-id . Reads a single local file path; the bytes never travel on the JSON wire. Not listed on hosted remote MCP; calling it there returns an explanation instead. Use the CLI, a local MCP client, or the dashboard. { "file": "./greenhouse-export.zip" } Applications Applications are the person + Job attachment and the MCP write-capable surface for application/applicant state. Use these tools for creating the attachment, updating application-owned fields, recording application evidence, status transitions, and archive approval flows. yardstick_applications_list CLI equivalent: applications list. Mode: read. List application person + Job attachments visible to the current principal. { "limit": 20 } yardstick_applications_read CLI equivalent: applications read. Mode: read. Read one application person + Job attachment by public id. { "application_id": "app_abc123" } yardstick_applications_create CLI equivalent: applications create. Mode: write. Create a recruiter- or agent-sourced application for an existing person and job posting. { "person_id": "per_abc123", "job_posting_id": "jp_abc123", "idempotency_key": "application-123" } yardstick_applications_update CLI equivalent: applications update. Mode: write. Update one application with schema-bound public API fields. { "application_id": "app_abc123", "stage": "Onsite" } yardstick_applications_transition_direct CLI equivalent: applications transition-direct. Mode: write. Directly write a non-terminal application transition; approval-only statuses are rejected. { "application_id": "app_abc123", "status": "Interviewing", "reason": "Phone screen passed" } yardstick_applications_transition_preview CLI equivalent: applications transition-preview. Mode: approval-required. Preview approval-required application transitions only; bind fields and direct-write targets are rejected. { "application_id": "app_abc123", "status": "Offer", "reason": "Strong loop" } yardstick_applications_transition_bind CLI equivalent: applications transition-bind. Mode: approval-required. Bind an already-previewed application transition with explicit approval metadata and matching idempotency key. { "application_id": "app_abc123", "status": "Offer", "reason": "Strong loop", "binding": { "preview_hash": "ph_...", "approved_action_key": "ak_...", "approved_input_hash": "ih_...", "approved_idempotency_key": "ik_...", "resource_version_precondition": "rv_..." } } yardstick_applications_archive_preview CLI equivalent: applications archive-preview. Mode: approval-required. Preview application archive approval requirements only; bind fields are rejected. { "application_id": "app_abc123", "reason": "Candidate withdrew" } yardstick_applications_archive_bind CLI equivalent: applications archive-bind. Mode: approval-required. Bind an already-previewed application archive with explicit approval metadata and matching idempotency key. { "application_id": "app_abc123", "reason": "Candidate withdrew", "binding": { "preview_hash": "ph_...", "approved_action_key": "ak_...", "approved_input_hash": "ih_...", "approved_idempotency_key": "ik_...", "resource_version_precondition": "rv_..." } } yardstick_applications_status_email_poc_preview CLI equivalent: applications status-email-poc-preview. Mode: approval-required. Preview moving an application from Interviewing to Offer together with its candidate email, without changing the status or sending the email. { "application_id": "app_abc123", "current_status": "Interviewing", "target_status": "Offer", "email_type": "offer", "decision": "review_edit", "idempotency_key": "status-email-poc-preview-1" } yardstick_applications_status_email_poc_bind CLI equivalent: applications status-email-poc-bind. Mode: approval-required. Confirm a previewed Interviewing to Offer status and email change with explicit approval metadata and a matching idempotency key. { "application_id": "app_abc123", "current_status": "Interviewing", "target_status": "Offer", "email_type": "offer", "decision": "review_edit", "idempotency_key": "status-email-poc-preview-1", "binding": { "preview_hash": "ph_...", "approved_action_key": "application.status_email_approval_poc", "approved_input_hash": "ih_...", "approved_idempotency_key": "status-email-poc-preview-1", "resource_version_precondition": "rv_..." } } yardstick_decision_brief_read CLI equivalent: applications decision-brief read. Mode: read. Read the decision brief for an application. { "application_id": "app_abc123" } yardstick_decision_brief_regenerate CLI equivalent: applications decision-brief regenerate. Mode: write. Regenerate a decision brief for an application with idempotency metadata. { "application_id": "app_abc123" } yardstick_final_recommendation_record CLI equivalent: applications final-recommendation record. Mode: write. Record direct final-recommendation evidence; this does not mutate application status. { "application_id": "app_abc123", "interviewer_user_id": "00000000-0000-0000-0000-000000000000", "rating": 3, "notes": "Strong systems thinking." } yardstick_application_interview_sessions_list CLI equivalent: applications interview-sessions list. Mode: read. List interview sessions for an application. { "application_id": "app_abc123" } yardstick_application_interview_sessions_ensure CLI equivalent: applications interview-sessions ensure. Mode: write. Ensure an application interview session for an explicit round id. { "application_id": "app_abc123", "round_id": "round_1" } Opportunities Opportunities are read-only enriched workflow views over application-backed candidate/interview-cycle work. This resource exposes only list, read, next-action, and deep-link tools; create, update, transition, archive, and approval flows stay under applications. yardstick_opportunities_list CLI equivalent: opportunities list. Mode: read. List read-only opportunities visible to the current principal. { "limit": 20 } yardstick_opportunities_read CLI equivalent: opportunities read. Mode: read. Read one read-only opportunity workflow view by public id. { "opportunity_id": "opp_abc123" } yardstick_opportunities_next_action CLI equivalent: opportunities next-action. Mode: read. Read the next action state for an opportunity without mutating it. { "opportunity_id": "opp_abc123" } yardstick_opportunities_deep_link CLI equivalent: opportunities deep-link. Mode: read. Create a public deep link for an opportunity workflow view. { "opportunity_id": "opp_abc123" } Departments yardstick_departments_list CLI equivalent: departments list. Mode: read. List Departments visible to the current principal. { "limit": 20 } yardstick_departments_read CLI equivalent: departments read. Mode: read. Read one Department by public id. { "department_id": "dpt_abc123" } yardstick_departments_create CLI equivalent: departments create. Mode: write. Create a Department through the public Yardstick API. { "name": "Engineering", "slug": "engineering" } yardstick_departments_update CLI equivalent: departments update. Mode: write. Update one Department with schema-bound public API fields. { "department_id": "dpt_abc123", "description": "Product engineering" } yardstick_departments_members_list CLI equivalent: departments members list. Mode: read. List Department members for an authorized Department. { "department_id": "dpt_abc123", "limit": 50 } yardstick_departments_members_add CLI equivalent: departments members add. Mode: write. Add an existing person to a Department. { "department_id": "dpt_abc123", "person_id": "per_abc123" } yardstick_departments_members_set_lead CLI equivalent: departments members set-lead. Mode: write. Set one Department member as lead. { "department_id": "dpt_abc123", "person_id": "per_abc123", "role": "lead" } yardstick_departments_members_remove CLI equivalent: departments members remove. Mode: write. Remove a Department member, optionally with a replacement lead. { "department_id": "dpt_abc123", "person_id": "per_abc123" } yardstick_departments_invitations_list CLI equivalent: departments invitations list. Mode: read. List redacted Department invitation views. { "department_id": "dpt_abc123" } yardstick_departments_invitations_create CLI equivalent: departments invitations create. Mode: write. Create a Department-scoped invitation without returning token material. { "department_id": "dpt_abc123", "email": "lead@example.com", "role": "department_lead" } Access grants yardstick_access_grants_list CLI equivalent: access-grants list. Mode: read. List explicit access grants visible to the current principal. { "limit": 20 } yardstick_access_grants_read CLI equivalent: access-grants read. Mode: read. Read one explicit access grant by public id. { "access_grant_id": "agr_abc123" } yardstick_access_grants_create CLI equivalent: access-grants create. Mode: write. Create a reasoned, revocable, audited access grant. { "subject_person_id": "per_abc123", "scope": "job", "target_id": "job_abc123", "artifact_classes": ["application", "interview_plan"], "reason": "Hiring manager needs review access for Q3 backfill." } yardstick_access_grants_revoke CLI equivalent: access-grants revoke. Mode: write. Revoke an explicit access grant with optional reason text. { "access_grant_id": "agr_abc123", "reason": "Role filled" } Jobs yardstick_jobs_list CLI equivalent: jobs list. Mode: read. List internal Job containers visible to the current principal. { "limit": 20, "include_archived": false } yardstick_jobs_create CLI equivalent: jobs create. Mode: write. Create an internal Job container without mutating job postings, applications, or interview plans. { "title": "Senior Backend Engineer", "department": "Engineering", "location_type": "remote" } yardstick_jobs_read CLI equivalent: jobs read. Mode: read. Read one internal Job container by public id. { "job_id": "job_abc123" } yardstick_jobs_prospect_matches CLI equivalent: jobs prospect-matches. Mode: read. List deterministic Talent CRM prospect matches for one Job. Requires jobs:read, prospects:read, and applications:read; returns evidence, caveats, blocked lifecycle states, and dashboard URLs without outreach, conversion, import, or AI ranking. { "job_id": "job_abc123" } yardstick_jobs_update CLI equivalent: jobs update. Mode: write. Update one internal Job container with schema-bound public API fields. { "job_id": "job_abc123", "status": "open" } yardstick_jobs_close CLI equivalent: jobs close. Mode: write. Close a Job and atomically unpublish its live linked job postings. Applications and interview plans are not mutated. Reopening does not republish a posting. { "job_id": "job_abc123" } yardstick_jobs_archive CLI equivalent: jobs archive. Mode: write. Archive a Job and atomically unpublish its live linked job postings. Applications and interview plans are not mutated. { "job_id": "job_abc123" } yardstick_jobs_attach_artifact CLI equivalent: jobs attach-artifact. Mode: write. Link an existing interview plan, job posting, or application to a Job. Idempotent when already linked to the same Job; conflicts when linked elsewhere. Requires jobs:write and the artifact's own write scope. { "job_id": "job_abc123", "artifact_type": "job_posting", "artifact_id": "jp_abc123" } yardstick_jobs_detach_artifact CLI equivalent: jobs detach-artifact. Mode: write. Clear the link between an artifact and a Job. Idempotent when already unlinked. Requires jobs:write and the artifact's own write scope. { "job_id": "job_abc123", "artifact_type": "job_posting", "artifact_id": "jp_abc123" } Pipelines yardstick_pipelines_list CLI equivalent: pipelines list. Mode: read. List the organization's pipeline templates with their ordered stages. Canonical default stages are flagged canonical_locked. { "limit": 20 } yardstick_pipelines_read CLI equivalent: pipelines read. Mode: read. Read one pipeline template and its ordered stages by public id. { "pipeline_id": "pip_abc123" } yardstick_pipelines_create CLI equivalent: pipelines create. Mode: write. Create a custom pipeline template with optional inline stages. Does not affect the org default pipeline or candidate tracking. { "name": "Engineering", "slug": "engineering" } yardstick_pipelines_update CLI equivalent: pipelines update. Mode: write. Rename, re-describe, or toggle active for one pipeline template. { "pipeline_id": "pip_abc123", "name": "Eng (2026)" } yardstick_pipelines_stages_create CLI equivalent: pipelines stages create. Mode: write. Append (or insert at a position) a stage to a pipeline with a kind and optional approval scope. { "pipeline_id": "pip_abc123", "name": "Phone Screen", "slug": "phone_screen", "stage_kind": "normal" } yardstick_pipelines_stages_update CLI equivalent: pipelines stages update. Mode: write. Edit a pipeline stage. Canonical default stages allow display-name change only; slug, stage kind, approval scope, and terminal flag are locked. { "pipeline_id": "pip_abc123", "stage_id": "pst_abc123", "name": "Recruiter Screen" } yardstick_pipelines_reorder_stages CLI equivalent: pipelines reorder-stages. Mode: write. Reorder all stages of a pipeline by supplying the complete stage id order. Constraint-safe single-transaction reorder; allowed for canonical stages. { "pipeline_id": "pip_abc123", "stage_ids": ["pst_def456", "pst_abc123", "pst_ghj789"] } yardstick_pipelines_stages_delete_preview CLI equivalent: pipelines stages delete-preview. Mode: approval preview. Preview deleting a pipeline stage; returns the candidate-count impact and approval binding fields without mutating. Canonical default stages are rejected. Requires pipelines:write. { "pipeline_id": "pip_abc123", "stage_id": "pst_abc123" } yardstick_pipelines_stages_delete_bind CLI equivalent: pipelines stages delete-bind. Mode: approval bind. Bind an approved pipeline-stage delete with explicit approval metadata and a matching idempotency key. Refuses while candidates remain. Requires pipelines:write. { "pipeline_id": "pip_abc123", "stage_id": "pst_abc123", "binding": { "approved_action_key": "pipeline.delete_stage" } } yardstick_pipelines_assign_to_job CLI equivalent: pipelines assign-to-job. Mode: write. Assign a pipeline to a Job, or clear it with pipeline_id: null. Requires both pipelines:write and jobs:write. { "job_id": "job_abc123", "pipeline_id": "pip_abc123" } Automation rules Stage automation rules are inert configuration — authoring fires no side effect, and the execution engine runs rules in a later release. The whole surface is gated by the configurable_pipelines_enabled feature flag and the admin-only automation_rules:read / automation_rules:write scopes. yardstick_automation_rules_list CLI equivalent: automation-rules list. Mode: read. List the organization's stage automation rules. Rules are inert config — authoring fires no side effect; the executor child runs rules later. { "limit": 20 } yardstick_automation_rules_read CLI equivalent: automation-rules read. Mode: read. Read one stage automation rule by public id (its trigger, typed action, target stage, and is_active state). { "rule_id": "aru_abc123" } yardstick_automation_rules_create CLI equivalent: automation-rules create. Mode: write. Create a stage automation rule (trigger plus a typed action from the 3-type palette: send_scheduling_link / create_task / send_email). Inert — fires no side effect. { "pipeline_stage_id": "pst_abc123", "trigger": "stage_enter", "action": { "type": "send_scheduling_link" } } yardstick_automation_rules_update CLI equivalent: automation-rules update. Mode: write. Edit a stage automation rule's trigger, typed action, condition, position, or is_active state. { "rule_id": "aru_abc123", "is_active": false } yardstick_automation_rules_delete CLI equivalent: automation-rules delete. Mode: write. Delete a stage automation rule. Plain delete (no approval preview→bind): rules are inert config, so deleting unfired config moves no candidates. { "rule_id": "aru_abc123" } yardstick_automation_rules_preview CLI equivalent: automation-rules preview. Mode: read. Dry-run preview: resolve the active rules plus their resolved action params for a sample application entering or leaving a stage. INERT — mints no scheduling link, creates no task, sends no email; executes nothing. { "application_id": "app_abc123", "trigger": "stage_enter", "pipeline_stage_id": "pst_abc123" } yardstick_automation_runs_list CLI equivalent: automation-runs list. Mode: read. List the organization's stage automation runs (what fired for which candidate, success or failure). Read-only — runs are system-written by the executor. Filter by application_id and/or rule_id; skipped (deferred) send_email rows are included so run state is fully observable. { "application_id": "app_abc123" } Built-in agents Built-in agents turn recurring hiring work into named outcomes. Chase missing scorecards reminds interviewers about missing feedback. Screen new applicants nightly prepares rejection drafts for applicants who clearly do not meet the role requirements. Prep interview kits for next week's sessions prepares current kits for assigned interviewers. Prepare a panel decision brief brings completed interview evidence together. Keep candidates informed prepares updates for interviewed candidates who are still waiting, using bounded personalization when available and the validated template as a fallback. Read tools require built_in_agents:read; the preview and bind tools require built_in_agents:write. yardstick_built_in_agents_list CLI equivalent: built-in-agents list. Mode: read. List the hiring built-in agents available to your workspace, including each built-in agent's current settings and latest work summary. {} yardstick_built_in_agents_read CLI equivalent: built-in-agents read. Mode: read. Read one built-in agent by catalog id, including what it does, what it never does without you, its current settings, and its latest work summary. { "built_in_agent_id": "scorecard-chaser" } yardstick_built_in_agents_runs CLI equivalent: built-in-agents runs. Mode: read. List the selected built-in agent's work report. Scorecard runs include reminder activity. Nightly-screening runs include scheduled-work counts and count-only held, released, or invalidated review outputs. They do not include candidate, email-draft, or recipient details. Interview-kit runs report only the scheduled week and preparation counts. An unconfirmed delivery is marked stopped, not delivered, and not retried automatically. Candidate-follow-through runs report count-only eligible, prepared, fallback, awaiting-review, suppression, failure, and output states, with an Email Drafts destination. They never mean an email was sent. { "built_in_agent_id": "scorecard-chaser" } yardstick_built_in_agents_enable_preview CLI equivalent: built-in-agents enable-preview. Mode: approval-required. Preview turning on a built-in agent. It explains the reminders that will start and returns the approval binding without changing settings or sending a reminder. { "built_in_agent_id": "scorecard-chaser", "idempotency_key": "scorecard-enable-1" } yardstick_built_in_agents_enable_bind CLI equivalent: built-in-agents enable-bind. Mode: approval-required. After a person approves the preview, turn on the built-in agent with the matching binding and idempotency key. The bind applies only the approved change. { "built_in_agent_id": "scorecard-chaser", "idempotency_key": "scorecard-enable-1", "binding": { "preview_hash": "...", "approved_action_key": "recipe.enable", "approved_input_hash": "...", "approved_idempotency_key": "scorecard-enable-1", "resource_version_precondition": "..." } } yardstick_built_in_agents_configure_preview CLI equivalent: built-in-agents configure-preview. Mode: approval-required. Preview a built-in agent schedule or turn a built-in agent off. For Chase missing scorecards, intervals are one to five strictly increasing hours after the interview ends, each no later than 72 hours. For Screen new applicants nightly, owners and admins can set timezone, local_hour, and per_run_cap with the enabled switch. For Prep interview kits for next week's sessions, they can set enabled, timezone, local_day, and local_hour. Its disabled default is Friday at 09:00 in America/Los_Angeles. For Keep candidates informed, they can set enabled, timezone, local_hour, waiting_days, cooldown_days, and per_run_cap. It defaults off with 09:00 in America/Los_Angeles, a three-day initial wait, a seven-day recurrence cooldown, and a cap of 100 candidates per run. { "built_in_agent_id": "scorecard-chaser", "idempotency_key": "scorecard-schedule-1", "config": { "intervals": [2, 24, 48] } } yardstick_built_in_agents_configure_bind CLI equivalent: built-in-agents configure-bind. Mode: approval-required. After approval, apply the same settings with the matching binding and idempotency key. To turn the built-in agent off, set enabled to false in config. { "built_in_agent_id": "scorecard-chaser", "idempotency_key": "scorecard-schedule-1", "config": { "intervals": [2, 24, 48] }, "binding": { "preview_hash": "...", "approved_action_key": "recipe.configure", "approved_input_hash": "...", "approved_idempotency_key": "scorecard-schedule-1", "resource_version_precondition": "..." } } Job postings yardstick_job_postings_list CLI equivalent: job-postings list. Mode: read. List job postings visible to the current principal. { "limit": 20 } yardstick_job_postings_read CLI equivalent: job-postings read. Mode: read. Read one job posting by public id. { "job_posting_id": "jp_abc123" } yardstick_job_postings_validate CLI equivalent: job-postings validate. Mode: read. Validate a draft job posting without mutating it. { "job_posting_id": "jp_abc123" } yardstick_job_postings_create CLI equivalent: job-postings create. Mode: write. Create a draft job posting through the public Yardstick API. Drafts may omit a country, but publishing requires one, including for remote roles. Send an assigned ISO 3166-1 alpha-2 code; lowercase input is normalized to uppercase. { "title": "Senior Backend Engineer", "interview_plan_id": "ipd_abc123", "slug": "senior-backend-engineer", "location_country": "US" } yardstick_job_postings_update CLI equivalent: job-postings update. Mode: write. Update a job posting with schema-bound public API fields. Omit location_country to preserve it, or send JSON null to clear it from an unpublished draft. { "job_posting_id": "jp_abc123", "location_country": null } yardstick_job_postings_publish_preview CLI equivalent: job-postings publish-preview. Mode: approval-required. Preview job-posting publish approval requirements only; bind fields are rejected. { "job_posting_id": "jp_abc123" } yardstick_job_postings_publish_bind CLI equivalent: job-postings publish-bind. Mode: approval-required. Bind an already-previewed job-posting publish with explicit approval metadata and matching idempotency key. { "job_posting_id": "jp_abc123", "binding": { "preview_hash": "ph_...", "approved_action_key": "ak_...", "approved_input_hash": "ih_...", "approved_idempotency_key": "ik_...", "resource_version_precondition": "rv_..." } } yardstick_job_postings_archive_preview CLI equivalent: job-postings archive-preview. Mode: approval-required. Preview job-posting archive approval requirements only; bind fields are rejected. { "job_posting_id": "jp_abc123" } yardstick_job_postings_archive_bind CLI equivalent: job-postings archive-bind. Mode: approval-required. Bind an already-previewed job-posting archive with explicit approval metadata and matching idempotency key. { "job_posting_id": "jp_abc123", "binding": { "preview_hash": "ph_...", "approved_action_key": "ak_...", "approved_input_hash": "ih_...", "approved_idempotency_key": "ik_...", "resource_version_precondition": "rv_..." } } Job posting lifecycle states are Draft, Published, Unpublished, and Archived. Publishing opens the attached non-archived Job when needed. Closing, pausing, or archiving a Job unpublishes its live postings; reopening leaves them Unpublished until a user publishes them again. A retained published_at timestamp records prior publication and does not mean the posting is currently public. Interview plans and drafts yardstick_interview_plans_read CLI equivalent: interview-plans read. Mode: read. Read one interview plan by public id. This narrow read omits the builder's outcome list; use the full draft read below to inspect optional outcome tags. { "interview_plan_id": "ipd_abc123" } yardstick_interview_plan_drafts_generate_outcomes CLI equivalent: interview-plan-drafts generate-outcomes. Mode: write. Generate draft interview-plan outcomes from explicit role context, or pass accepted_outcomes to store caller-written outcomes verbatim with no AI generation (the deterministic draft bootstrap). Each outcome may include an optional tag beside its stable id and full statement. Generated and caller-supplied tags are preserved in the outcomes checkpoint and echoed in data.outcomes; omitting tag remains valid for older outcomes. Optional source_job_id (a same-org Job UUID) seeds the draft's role context from that Job; caller-provided role_context keys override per-field. It cannot be combined with resource.id. { "action": "interview_plan.generate_outcomes", "input": { "role_context": { "role_title": "Senior Backend Engineer" }, "accepted_outcomes": [ { "id": "outcome_1", "text": "Ship the v2 platform in two quarters.", "tag": "Platform delivery" } ] } } yardstick_interview_plan_drafts_confirm_outcomes CLI equivalent: interview-plan-drafts confirm-outcomes. Mode: write. Confirm draft interview-plan outcomes before generating later stages. Include the optional tag to preserve a compact label with the full outcome; the tag never replaces the full statement. The API-compatible title field is a full outcome statement fallback, not a compact tag. Use tag for optional compact presentation. { "action": "interview_plan.confirm_outcomes", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "accepted_outcomes": [ { "id": "outcome_1", "text": "Ship a service end-to-end", "tag": "Service delivery" } ] } } yardstick_interview_plan_drafts_generate_competencies CLI equivalent: interview-plan-drafts generate-competencies. Mode: write. Generate draft interview-plan competencies from confirmed outcomes. { "action": "interview_plan.generate_competencies", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "source_stage": { "stage": "outcomes" } } } yardstick_interview_plan_drafts_generate_skills CLI equivalent: interview-plan-drafts generate-skills. Mode: write. Generate draft interview-plan skills from confirmed competencies. { "action": "interview_plan.generate_skills", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "source_stage": { "stage": "competencies" } } } yardstick_interview_plan_drafts_generate_rounds CLI equivalent: interview-plan-drafts generate-rounds. Mode: write. Generate draft interview-plan rounds from confirmed skills. { "action": "interview_plan.generate_rounds", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "source_stage": { "stage": "skills" } } } yardstick_interview_plan_drafts_generate_anchors CLI equivalent: interview-plan-drafts generate-anchors. Mode: write. Generate scorecard behavioral anchors (levels 1-4) for each draft competency, or one competency when competency_id is supplied. { "action": "interview_plan.generate_anchors", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "source_stage": { "stage": "competencies" } } } yardstick_interview_plan_drafts_generate_questions_directions CLI equivalent: interview-plan-drafts generate-questions-directions. Mode: write. Generate interview questions and interviewer/candidate directions for each draft round, or one round when round_id is supplied. { "action": "interview_plan.generate_questions_directions", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "source_stage": { "stage": "interview_sequence" } } } yardstick_interview_plan_drafts_validate CLI equivalent: interview-plan-drafts validate. Mode: read. Validate an interview-plan draft without publishing it. { "action": "interview_plan.validate_draft", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "include_warnings": true } } yardstick_interview_plan_drafts_read CLI equivalent: interview-plan-drafts read. Mode: read. Read a draft in full — every stage checkpoint, stage_versions, and status — the fetch half of fetch-modify-submit editing. The outcomes checkpoint returns saved optional tag values unchanged. Question ids are always present, so edits can target them directly. { "draft_id": "ipd_abc123" } The verbatim edit tools below store caller content exactly as written — deterministic, no AI generation. All accept an optional source_stage version precondition on the mutated stage (409 when stale); deletes prune dependent stage data and report the pruned ids. yardstick_interview_plan_drafts_add_competencies CLI equivalent: interview-plan-drafts add-competencies. Mode: write. Add competencies to a draft exactly as written; requires confirmed outcomes and fits within the 25-competency stage maximum. { "action": "interview_plan.add_competencies", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "items": [ { "name": "Structured judgment", "description": "Weighs evidence before deciding." } ], "source_stage": { "stage": "competencies", "version": 2 } } } yardstick_interview_plan_drafts_update_competencies CLI equivalent: interview-plan-drafts update-competencies. Mode: write. Replace competencies by id and/or reorder them with order (a complete permutation of resulting ids). { "action": "interview_plan.update_competencies", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "items": [ { "id": "competency_1", "name": "Structured judgment", "description": "Weighs evidence before deciding." } ] } } yardstick_interview_plan_drafts_delete_competencies CLI equivalent: interview-plan-drafts delete-competencies. Mode: write. Delete competencies by id; prunes each deleted competency's behavioral anchors in the same write and reports the pruned ids. { "action": "interview_plan.delete_competencies", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "ids": ["competency_2"] } } yardstick_interview_plan_drafts_add_skills CLI equivalent: interview-plan-drafts add-skills. Mode: write. Add job skills to a draft exactly as written; requires competencies and fits within the 50-skill stage maximum. { "action": "interview_plan.add_skills", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "items": [{ "name": "Structured interviewing" }] } } yardstick_interview_plan_drafts_update_skills CLI equivalent: interview-plan-drafts update-skills. Mode: write. Replace job skills by id and/or reorder them; pure reorder works with order alone. { "action": "interview_plan.update_skills", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "order": ["skill_2", "skill_1"] } } yardstick_interview_plan_drafts_delete_skills CLI equivalent: interview-plan-drafts delete-skills. Mode: write. Delete job skills by id; the stage must keep at least one skill. { "action": "interview_plan.delete_skills", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "ids": ["skill_2"] } } yardstick_interview_plan_drafts_add_rounds CLI equivalent: interview-plan-drafts add-rounds. Mode: write. Add interview rounds to a draft exactly as written; requires skills and fits within the 20-round sequence maximum. { "action": "interview_plan.add_rounds", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "items": [{ "title": "Structured interview", "duration": 60 }] } } yardstick_interview_plan_drafts_update_rounds CLI equivalent: interview-plan-drafts update-rounds. Mode: write. Replace rounds by id and/or reorder them. A round updated in place keeps its id, so its questions and directions are preserved (not pruned). { "action": "interview_plan.update_rounds", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "items": [{ "id": "round_1", "title": "Structured interview", "duration": 45 }] } } yardstick_interview_plan_drafts_delete_rounds CLI equivalent: interview-plan-drafts delete-rounds. Mode: write. Delete rounds by id; prunes each deleted round's questions and directions in the same write and reports the pruned ids. { "action": "interview_plan.delete_rounds", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "ids": ["round_2"] } } yardstick_interview_plan_drafts_add_questions CLI equivalent: interview-plan-drafts add-questions. Mode: write. Add questions to one round exactly as written; each round holds at most 50 questions. { "action": "interview_plan.add_questions", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "round_id": "round_1", "questions": [{ "text": "Walk me through a recent decision you owned." }] } } yardstick_interview_plan_drafts_update_questions CLI equivalent: interview-plan-drafts update-questions. Mode: write. Replace one round's questions by id and/or reorder them with a per-round order permutation. Read the draft first — stored questions always expose stable ids. { "action": "interview_plan.update_questions", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "round_id": "round_1", "questions": [{ "id": "question_2", "text": "Tell me about a tradeoff you got wrong." }] } } yardstick_interview_plan_drafts_delete_questions CLI equivalent: interview-plan-drafts delete-questions. Mode: write. Delete questions from one round by question id. { "action": "interview_plan.delete_questions", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "round_id": "round_1", "ids": ["question_2"] } } yardstick_interview_plan_drafts_update_round_directions CLI equivalent: interview-plan-drafts update-round-directions. Mode: write. Set one round's interviewer and/or candidate directions exactly as written; provide at least one of the two. { "action": "interview_plan.update_round_directions", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "round_id": "round_1", "interviewer_directions": "Probe for concrete evidence." } } yardstick_interview_plan_drafts_update_anchors CLI equivalent: interview-plan-drafts update-anchors. Mode: write. Upsert behavioral anchors for draft items, keyed by item id with levels 1-4; anchors keyed to unknown item ids are rejected by id. { "action": "interview_plan.update_anchors", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "anchors": { "competency_1": [{ "level": 3, "description": "Consistently weighs evidence." }] } } } yardstick_interview_plan_drafts_delete_anchors CLI equivalent: interview-plan-drafts delete-anchors. Mode: write. Delete behavioral-anchor entries for draft items by item id. { "action": "interview_plan.delete_anchors", "resource": { "type": "interview_plan_draft", "id": "ipd_abc123" }, "input": { "item_ids": ["competency_2"] } } yardstick_interview_plans_publish_preview CLI equivalent: interview-plans publish-preview. Mode: approval-required. Preview interview-plan publish approval requirements only; bind fields are rejected. For a ready preview, read preserved outcome tags from proposed_state.outcomes. A preview blocked by publish preconditions keeps the mapper preview under data.preview, with outcomes at data.preview.values.outcomes; do not use that blocked-preview path for a ready response. { "action": "interview_plan.publish", "input": { "draft_id": "ipd_abc123" } } yardstick_interview_plans_publish_bind CLI equivalent: interview-plans publish-bind. Mode: approval-required. Bind an already-previewed interview-plan publish with explicit approval metadata and matching idempotency key. { "action": "interview_plan.publish", "input": { "draft_id": "ipd_abc123" }, "binding": { "preview_hash": "ph_...", "approved_action_key": "ak_...", "approved_input_hash": "ih_...", "approved_idempotency_key": "ik_...", "resource_version_precondition": "rv_..." } } yardstick_interview_plans_modify_active_preview CLI equivalent: interview-plans modify-active-preview. Mode: approval-required. Preview the effect of applying a draft's changes to an already-active interview plan — which rounds get a new version and which candidate sessions move versus stay locked. Future or not-started sessions use the newest active, unarchived version for their round; in-progress and completed sessions stay pinned to the version they were given. Bind fields are rejected. { "action": "interview_plan.modify_active", "input": { "draft_id": "ipd_abc123", "active_plan_id": "ipd_def456" } } yardstick_interview_plans_modify_active_bind CLI equivalent: interview-plans modify-active-bind. Mode: approval-required. Apply a previously-previewed modification to an active interview plan, with explicit approval metadata and matching idempotency key. { "action": "interview_plan.modify_active", "input": { "draft_id": "ipd_abc123", "active_plan_id": "ipd_def456" }, "binding": { "preview_hash": "ph_...", "approved_action_key": "ak_...", "approved_input_hash": "ih_...", "approved_idempotency_key": "ik_...", "resource_version_precondition": "rv_..." } } Interview sessions yardstick_interview_sessions_read CLI equivalent: interview-sessions read. Mode: read. Read one interview session by public id. { "interview_session_id": "is_abc123" } yardstick_interview_sessions_interviewers_list CLI equivalent: interview-sessions interviewers list. Mode: read. List interviewers assigned to an interview session. { "interview_session_id": "is_abc123" } yardstick_interview_sessions_interviewers_assign CLI equivalent: interview-sessions interviewers assign. Mode: write. Assign an interviewer to an interview session. { "interview_session_id": "is_abc123", "interviewer_user_id": "00000000-0000-0000-0000-000000000000" } yardstick_interview_sessions_interviewers_unassign CLI equivalent: interview-sessions interviewers unassign. Mode: write. Unassign an interviewer from an interview session. { "interview_session_id": "is_abc123", "interviewer_user_id": "00000000-0000-0000-0000-000000000000" } yardstick_interview_sessions_start CLI equivalent: interview-sessions start. Mode: write. Start an interview session for an explicit interviewer. { "interview_session_id": "is_abc123", "interviewer_user_id": "00000000-0000-0000-0000-000000000000" } yardstick_interview_sessions_complete CLI equivalent: interview-sessions complete. Mode: write. Complete an interview session for an explicit interviewer. { "interview_session_id": "is_abc123", "interviewer_user_id": "00000000-0000-0000-0000-000000000000" } yardstick_interview_sessions_scorecard_submit CLI equivalent: interview-sessions scorecard submit. Mode: write. Submit an interview-session scorecard with explicit ratings. { "interview_session_id": "is_abc123", "interviewer_user_id": "00000000-0000-0000-0000-000000000000", "ratings": [{ "item_type": "competency", "item_id": "competency_1", "item_title": "Systems design", "rating": 3 }] } yardstick_interview_sessions_readiness CLI equivalent: interview-sessions readiness. Mode: read. Read interview-session scheduling readiness. { "interview_session_id": "is_abc123" } yardstick_interview_sessions_scheduling_link_generate CLI equivalent: interview-sessions scheduling-link generate. Mode: write. Generate a scheduling link for an interview session. { "interview_session_id": "is_abc123" } yardstick_interview_sessions_cancel CLI equivalent: interview-sessions cancel. Mode: write. Cancel a scheduled interview session, releasing the provider booking and invalidating its scheduling links. reason and skip_provider are both optional. reason is recorded on the resulting scheduling.session_cancelled event and is the only place it is stored. skip_provider cancels in Yardstick without calling the scheduling provider — use it when the provider is failing and you need the round cancelled anyway. Cancelling an already-cancelled round succeeds and reports outcome: "already_cancelled"; it makes no provider call and sends no second email. Check candidate_email in the response: email_not_sent means the round was cancelled but the candidate was never told. { "interview_session_id": "is_abc123", "reason": "Hiring manager unavailable" } Events and audit log yardstick_events_list CLI equivalent: events list. Mode: read. List public Yardstick API events visible to the current principal. { "limit": 20 } yardstick_audit_log_list CLI equivalent: audit-log list. Mode: read. List public Yardstick audit log entries visible to the current principal. { "limit": 20 } Reporting yardstick_reporting_search CLI equivalent: reporting search. Mode: read. Search redacted recruiting reporting summaries through the public reporting API. { "query_family": "role_health_attention", "window_start": "2026-05-01", "window_end": "2026-05-28", "role_label": "AI Content Manager", "limit": 10 } Prospect CRM operations summary: { "query_family": "prospect_ops_summary", "window_start": "2026-05-01", "window_end": "2026-05-28", "job_id": "job_abc123", "limit": 10 } Email communications yardstick_applications_email_decision_preview CLI equivalent: applications email-decision preview. Mode: read. Preview the candidate email decision for an application status change without mutating the application or drafts. yardstick_applications_email_decision_apply CLI equivalent: applications email-decision apply. Mode: write. Apply an application status-change email decision with idempotency metadata. yardstick_email_drafts_list CLI equivalent: email drafts list. Mode: read. List candidate email drafts with optional status and email-type filters. yardstick_email_drafts_read CLI equivalent: email drafts read. Mode: read. Read a redacted candidate email draft. yardstick_email_drafts_preview CLI equivalent: email drafts preview. Mode: read. Read rendered preview content for a candidate email draft. yardstick_email_drafts_history CLI equivalent: email drafts history. Mode: read. Read candidate email draft history and provenance. yardstick_email_drafts_update CLI equivalent: email drafts update. Mode: write. Save mutable candidate email draft fields or set/clear a validated sender override for a pending draft. yardstick_email_drafts_send CLI equivalent: email drafts send. Mode: write. Send a pending candidate email draft with replay protection, or reclaim a never-delivered draft and send it. Set reclaim_not_delivered: true only for a draft Yardstick recorded as never delivered — the send was reserved but the email never left Yardstick. The option asks for the reclaim; it does not grant it. Yardstick refuses unless the draft really is a never-delivered one, and refuses again if the interview round the email describes has changed since the draft was written, so a stale cancellation or confirmation is never sent to a candidate. yardstick_email_drafts_discard CLI equivalent: email drafts discard. Mode: write. Discard a pending candidate email draft without provider mutation. yardstick_email_automation_settings_read CLI equivalent: email automation-settings read. Mode: read. Read candidate email automation settings. yardstick_email_automation_settings_update CLI equivalent: email automation-settings update. Mode: write. Update candidate email automation settings. yardstick_email_sender_settings_read CLI equivalent: email sender-settings read. Mode: read. Read redacted email sender settings with sanitized queue diagnostics. yardstick_email_sender_connections_list CLI equivalent: email sender-connections list. Mode: read. List redacted sender provider connection state. yardstick_email_sender_oauth_prepare CLI equivalent: email sender-connections prepare-oauth. Mode: hosted unsupported. Prepare a browser OAuth handoff for an email sender connection. Not listed on hosted MCP; calling it there returns an explanation instead. Use the dashboard, the CLI, or a local MCP client. yardstick_email_sender_connections_refresh_discovery CLI equivalent: email sender-connections refresh-discovery. Mode: hosted unsupported. Refresh sender identity discovery for a provider connection. Not listed on hosted MCP; calling it there returns an explanation instead. Use the dashboard, the CLI, or a local MCP client. yardstick_email_sender_connections_disconnect CLI equivalent: email sender-connections disconnect. Mode: hosted unsupported. Disconnect an email sender provider connection. Not listed on hosted MCP; calling it there returns an explanation instead. Use the dashboard, the CLI, or a local MCP client. yardstick_email_sender_defaults_list CLI equivalent: email sender-defaults list. Mode: read. List candidate email sender defaults. yardstick_integrations_workspace_health_read CLI equivalent: integrations workspace-health read. Mode: read. Read sanitized Workspace integration health diagnostics. yardstick_email_sender_defaults_set CLI equivalent: email sender-defaults set. Mode: write. Set the default sender policy for a candidate email type. yardstick_email_templates_list CLI equivalent: email templates list. Mode: read. List candidate email template policies without raw prompts. yardstick_email_templates_read CLI equivalent: email templates read. Mode: read. Read candidate email template detail without raw prompts. yardstick_email_templates_preview CLI equivalent: email templates preview. Mode: read. Preview a candidate email template for sample variables. yardstick_email_templates_validate CLI equivalent: email templates validate. Mode: read. Validate candidate email template subject, HTML, and text bodies. yardstick_email_templates_publish CLI equivalent: email templates publish. Mode: write. Publish a validated candidate email template version. yardstick_email_template_versions_list CLI equivalent: email templates versions. Mode: read. List immutable candidate email template versions. yardstick_email_templates_rollback CLI equivalent: email templates rollback. Mode: write. Rollback a candidate email template to an immutable version. yardstick_email_templates_preview_customization CLI equivalent: email templates preview-customization. Mode: read. Preview AI sample customization for a candidate email template without publishing. --- ## Agency collaboration overview URL: https://app.yardstick.team/docs/product/agency-collaboration-overview Summary: Work with outside recruiting partners: connect with a customer, keep your candidates private until you submit, share interview plans, and read the feedback you're allowed to see. Agency collaboration is how an outside recruiting agency and the company it recruits for work together inside Yardstick without sharing one another's data. If you're at an agency, you get your own workspace where your prospects and candidates stay private until you choose to submit them. If you're the company hiring, you decide which agencies you work with, what they can see, and which of their candidates you accept. This article gives you the lay of the land; the companion guide walks through a submission end to end. Agency collaboration is a newer capability and may not be turned on for your account yet. If you expect it and don't see it, ask your administrator, or email support using the contact at the bottom of this page. Getting an agency workspace Agency collaboration is in a pilot right now, so agency workspaces are turned on by hand rather than the moment you sign up. If you're an outside recruiter who wants one, you start by requesting access — our team reviews each request before your workspace goes live. Here's how it works: Sign up through the recruiter signup page at /recruiters/signup. You create a normal Yardstick account with your email and password (or with Google or Microsoft), and you tell us your agency or company name. You can also pick what kind of recruiter you are, though that's optional. Our team reads every request, so this isn't instant. While it's under review you'll see a status page telling you your request is pending — there's nothing else for you to do. We email you when there's a decision. If you're approved, your agency workspace is set up and you can open it and start working. If we can't approve the request right now, we'll let you know by email so you can follow up with us. We don't commit to a specific turnaround time, but you'll hear from us by email either way. If your request is taking longer than you expect, or you signed up through the wrong page by mistake, email support using the contact at the bottom of this page and we'll sort it out. Self-serve agency signup — where requesting an account instantly gives you a live agency workspace — isn't available yet. The pilot review is how we make sure agency collaboration is the right fit before turning it on. Two sides of the same connection Every agency collaboration has two parties, and Yardstick keeps them strictly separated: The agency — an outside recruiting firm sourcing candidates. Agency members work from an agency workspace and only ever see their own agency's data. The customer — the company doing the hiring. Customer admins decide which agencies to connect with and make the final call on every candidate an agency submits. A connection links one agency to one customer. Neither side can see into the other's workspace; the only things that cross the line are the ones you deliberately share — a submitted candidate, a shared interview plan, or the feedback a customer chooses to release back to the agency. The agency workspace If you're at an agency, your workspace is where you do your sourcing work. It looks and behaves like the rest of Yardstick — you track prospects, build pools, and manage candidates — with one important difference: everything you add stays private to your agency. A customer you're connected with cannot see your prospects, your notes, or your pipeline. They only see a candidate once you submit that candidate to them. This means you can work a candidate fully — research, conversations, your own assessment — before deciding whether and when to put them in front of a customer. Trusted partner connections Connections are how the two sides opt in to working together. A connection moves through a few steps: An agency requests a connection with a customer, or a customer invites an agency. The other side accepts. Once accepted, the connection is active. The customer controls the connection's settings — including how much an agency can see and which of their people are assigned to it. Either side can wind a connection down. A customer can revoke a connection, which stops new submissions and shared plans flowing across it. A customer can be connected to several agencies at once, and an agency can work with several customers. Each connection is its own boundary — what you share on one never leaks into another. Sharing interview plans A customer can share an interview plan with a connected agency so the agency knows exactly how the customer interviews for a role — the stages, what each one looks for, and how candidates are evaluated. Sharing a plan is the customer's choice, and the customer can stop sharing at any time. When a plan is shared with you as an agency, you can accept it to use as a reference, or copy it into your own workspace to adapt. Sharing a plan never gives the agency access to the customer's other data — just that one plan. Submitting candidates Submitting is the moment a candidate crosses from the agency's private workspace into the customer's review. You decide who to submit and when, you assemble what the customer sees, and the customer decides whether to accept. The full lifecycle — the submission packet, customer review and acceptance, clarifications, and revisions — is covered in its own guide: Submitting a candidate to a customer Reading feedback and reporting After a customer reviews or interviews a submitted candidate, some of that feedback can flow back to the agency so you learn how your candidates are doing. You only ever see what the customer is willing to share. Yardstick deliberately holds back the parts that aren't yours to see — for example, who on the customer's side gave a particular assessment, and any internal notes the customer hasn't released. You see the outcome and the shared context, not the customer's private deliberations. Reporting follows the same rule. Each side sees its own performance — an agency sees how its submissions are doing across the customers it works with; a customer sees how its connected agencies are performing — and neither side sees the other's private numbers. One agency can never see another agency's results for the same customer. Reviewing guarded actions and ownership questions Your agency workspace also has two support areas for work that needs a human review before it moves forward: Agent approvals shows guarded actions that are waiting for an agency approver. You can review where the request came from, what it will affect, and the decision history before you approve or deny. Candidate-facing communication stays blocked from this queue unless a separate reviewed send path allows it. Duplicate & ownership shows ownership or duplicate questions tied to your own submissions. You can add context, evidence, revisions, or responses. The customer still makes the ownership decision, and other agencies stay hidden from you. These support areas are available in the Yardstick dashboard. They are not public API, CLI, or MCP workflows yet. Agent note (api) Agency-collaboration workflows are available in the Yardstick dashboard and through the public typed API, with separate agency-side and customer-side access — a token holds one or the other, never both, so an agency integration can't reach customer-only actions and vice versa. The Yardstick CLI and MCP do not cover these workflows yet; that's a deliberate first-version deferral. Agent approvals and standalone duplicate/ownership support are dashboard-only support routes, not public API operations. The feature is also release-gated and may be off for an account. Recruiter signup itself is browser- and operator-driven: requesting and approving an agency workspace is not a public API surface, so there is no self-serve agency-provisioning endpoint to call. API token setup: /docs/product/api-token-setup Submitting a candidate to a customer: /docs/product/agency-submission-workflow Common questions Can a customer see my prospects before I submit them? No. Everything in your agency workspace stays private to your agency. A customer only sees a candidate once you submit that candidate to them. Can two agencies working the same customer see each other? No. Each agency's workspace and each connection are separate boundaries. One agency never sees another agency's candidates, submissions, or results — even for the same customer and the same role. Why can't I see who left a particular piece of feedback? The customer chooses what to share back, and Yardstick redacts the parts that aren't the agency's to see, including evaluator identities and unreleased internal notes. You get the outcome and shared context, not the customer's private deliberation. How do I get an agency workspace as an outside recruiter? Request one through the recruiter signup page at /recruiters/signup. Agency collaboration is in a pilot, so our team reviews each request by hand and emails you with a decision — it isn't turned on automatically when you sign up. See Getting an agency workspace above. I requested agency access — how long until I hear back? We don't commit to a set turnaround, but a person reviews every request and you'll get an email either way: an approval when your workspace is ready, or a note from us if we can't approve it right now. I'm expecting agency collaboration but don't see it. It may not be turned on for your account yet. Check with your administrator, or email support using the contact at the bottom of this page. Related Submitting a candidate to a customer — the submission packet, customer review and acceptance, clarifications, and revisions, step by step. API token setup — create a token to drive the agency-collaboration API. Need help? Email support@yardstick.team --- ## Submitting a candidate to a customer URL: https://app.yardstick.team/docs/product/agency-submission-workflow Summary: Submit an agency candidate to a connected customer: build the packet, what the customer sees, how acceptance and rejection work, and how clarifications and revisions go back and forth. A submission is how an agency puts a candidate in front of a connected customer. Until you submit, the candidate stays private in your agency workspace; submitting hands the customer a packet to review and decide on. This article walks through the whole loop — building the packet, what the customer sees, acceptance and rejection, and the back-and-forth of clarifications and revisions. For the bigger picture of agencies, customers, and connections, see the agency collaboration overview. Agency collaboration may not be turned on for your account yet. If you expect it and don't see it, check with your administrator, or email support using the contact at the bottom of this page. Before you submit: the duplicate check Before you submit a candidate, Yardstick can tell you whether the customer may already know this person — for example, the candidate applied directly or another agency already submitted them. This duplicate check returns a safe signal only: it tells you there's a possible match so you can decide how to proceed, without exposing the customer's private records. Use it to avoid submitting someone the customer is already working with. Build the submission packet The packet is what the customer sees about your candidate. You assemble it deliberately, so you control what's shared: Open the candidate in your agency workspace and start a submission to a connected customer. Choose the connection (which customer) and the role you're submitting for. Add the supporting material the customer needs to evaluate the candidate — your notes, attachments, and context. You can keep adding evidence to a submission as you go. Submit. Submitting is a deliberate, confirmed step — Yardstick shows you what's about to be shared before it commits, so you don't share a candidate by accident. Once submitted, the candidate appears in the customer's review queue, and the submission moves into the customer's hands. What the customer sees The customer sees the packet you built — and only the packet. They don't get access to your agency workspace, your other candidates, or your private notes. Yardstick shares only what's in the packet — nothing in your workspace beyond it, whether the customer looks on screen or through an integration. The customer reviews submissions from a queue of everything their connected agencies have sent, organized by connection and role. Customer review: accept, reject, or ask When a customer reviews a submission, they have a few choices: Accept. The customer brings your candidate into their own process as a candidate for the role. Like submitting, accepting is a deliberate, confirmed step, and only a customer admin can do it. Reject. The customer declines the candidate and picks a reason from a set list of categories. You see that the candidate was passed on and the category — not free-form internal commentary the customer kept to itself. Ask for a clarification. Instead of deciding right away, the customer can send a question or request back to the agency (see below). Customer decisions are made by an admin on the customer's side — not just anyone with access — so accepting or rejecting a candidate is always a deliberate, authorized action. Clarifications: a two-way thread A clarification is the channel for the customer and agency to talk about a specific submission without exposing anything else: The customer can request a clarification — a question, a note, or a nudge for more information — attached to the submission. The agency responds to that request with an answer or additional detail. This keeps the conversation tied to the candidate and the submission, and it's the controlled way information moves between the two sides during review. Revise or withdraw a submission As the agency, you stay in control of a submission after you've sent it: Revise. Update the submission — strengthen the packet, add evidence, or answer a clarification — without starting over. Withdraw. Pull the candidate back if the situation changes (the candidate drops out, takes another role, or you decide not to proceed). Withdrawing removes the candidate from the customer's active review for that submission. When ownership needs sorting out Sometimes two agencies submit the same person, or a candidate the customer already knew turns up as an agency submission. The customer resolves who "owns" that candidate for the role. This is a deliberate, confirmed customer-admin action, and Yardstick keeps the competing agencies from seeing each other — the agency that doesn't win the candidate never learns who did. If the customer needs more context before deciding, the agency can use the Duplicate & ownership area in its workspace to respond, add evidence, revise the submission, or withdraw it. That area is for participation only. The customer still owns the final accept, reject, and ownership decision. Agent note (api) The submission lifecycle is available in the dashboard and through the public typed API, with separate agency-side and customer-side access. The high-risk steps — submitting a candidate, and a customer accepting one — preview what will happen and require an explicit confirm before they commit, so an agent never submits or accepts silently. Customer decisions require a customer admin. The Yardstick CLI and MCP don't cover these workflows yet (a deliberate first-version deferral), and the feature is release-gated. Standalone duplicate/ownership support is a dashboard route, not a public API operation. Agency collaboration overview: /docs/product/agency-collaboration-overview API token setup: /docs/product/api-token-setup Common questions Does submitting share my whole candidate record? No. The customer sees only the packet you built — your notes, attachments, and context for that submission. Your agency workspace, other candidates, and private notes stay yours. Can I take a candidate back after submitting? Yes. Withdraw the submission to pull the candidate out of the customer's active review. You can also revise a submission in place if you just need to update it. The customer rejected my candidate — why don't I see more detail? You see that the candidate was passed on and the reason category the customer chose. The customer's private internal notes aren't shared, by design. Another agency and I both submitted the same person. What happens? The customer resolves who owns that candidate for the role. The two agencies can't see each other, so you won't learn whether or to whom the candidate went if it isn't you. Related Agency collaboration overview — agency workspaces, customers, trusted partner connections, shared interview plans, and how feedback and reporting stay scoped to each side. API token setup — create a token to drive the agency-collaboration API. Need help? Email support@yardstick.team --- ## API token setup URL: https://app.yardstick.team/docs/product/api-token-setup Summary: Create, store, and use Yardstick API tokens for the public API, CLI, and MCP surfaces. Yardstick issues two kinds of bearer tokens for the public /v1/* API. This page covers the in-app screens where organization members create and approve credentials within their allowed access, how the CLI / MCP wrappers consume them, and the env-var pattern for non-interactive use. For the conceptual contract — scopes catalog, idempotency, request IDs, error envelope — see /docs/api/agent-wrapper. Agent auth approval Where this lives in the app API tokens settings at /settings/api-tokens — organization members manage their own tokens and agent credentials here. Owners and admins also see organization-wide credential inventory. Older /admin/api-tokens links open the same page. It is structured as a page header (with the owner-only API-access toggle inline next to "New token"), a three-card metric strip (Active tokens · Coverage warnings · Expiring), and one unified table that mixes Secret, Publishable, and Agent rows. Clicking a row opens a side drawer with scopes, refresh grant, current token, and revocation history. Agent auth approval at /settings/agent-auth/approve — the browser screen that the CLI's yardstick login opens. It shows the requested scopes, the requested mode (test vs live), and the credential type (cli vs mcp) so you can review (or narrow) the request before issuing a credential. Renew or add scopes — when an agent credential's refresh window lapses, run yardstick auth reauthorize or yardstick mcp reauthorize. Without --add-scopes, the approval page selects every scope from the current credential that Yardstick can still issue and lists any dropped scope. To request more access, pass --add-scopes . Yardstick combines the additions with the inherited scopes and labels them separately for approval. An organization member who can grant every scope must confirm the final set, including the acknowledgement for sensitive scopes. An unavailable addition blocks approval instead of being removed. After the replacement credential is minted, Yardstick revokes the old credential's refresh secret and access token. If renewal fails before the replacement is created, the old credential stays active. Key types Yardstick issues two bearer-token shapes. Both are validated by the same pipeline; the difference is which routes they can call. Publishable keys — prefixes ys_pk_live_… / ys_pk_test_…. Intake-safe keys for browser-mediated forms. The API treats requests carrying a publishable key as browser-origin and clamps them to a small allow-list of intake routes (think public job-posting submit). Secret / agent keys — prefixes ys_sk_live_… / ys_sk_test_…. Server-side keys that can call any route in the scopes the approving user selected. Issued either statically from /settings/api-tokens or dynamically through the agent-auth approval flow. The full secret is shown EXACTLY ONCE in a blocking modal that the creator must explicitly acknowledge ("I've saved it") before it is dismissed. There is no way to retrieve it afterward — only the prefix and metadata are stored. Use test-mode credentials for smoke writes; reach for live-mode only when a reviewer explicitly requests it. Issuing a static API token Sign in and visit /settings/api-tokens. Toggle the org-level API access switch on (owner only — admins see it as read-only until an owner enables it). Click New token, choose the type (Secret or Publishable), choose live or test mode, and set the access each resource needs in the scope picker (see below). The picker disables access you cannot grant. Save. The page surfaces the full secret in a blocking modal — copy it into your secret manager immediately, then click "I've saved it" to dismiss the dialog. Selecting scopes Scopes are set per resource with a segmented None / Read / Write control rather than a flat list of checkboxes. Each resource (People, Jobs, Applications, …) shows one segment row: pick None to grant nothing, Read for read-only access, or Write for full access. Write includes Read — selecting Write grants both the :read and :write scope for that resource, so you never have to tick two boxes. Resources that only expose reads (Reporting, Audit logs, …) show a two-segment None / Read control. For a Publishable key, the picker shows only the two browser-intake resources (People and Applications) as a two-segment None / Create control — publishable keys are intake-only and cannot read. Each section has one-click Read / Write roll-ups that set every resource in that group at once. Roll-ups move the segments only; they never enable the sensitive action toggles below. A few resources (Applications, Interview plans, Job postings) carry extra action scopes — discrete operations like moving a candidate to offer, hire, or reject. These appear as individual toggles in an expandable sub-list under the resource, separate from the None/Read/Write segment. Sensitive actions are flagged and require an explicit acknowledgement before the token can be created; granting Write does not turn them on. The new row appears in the unified tokens table with its prefix, mode, scopes, and creator. Click the row to open the side drawer for scope changes or revocation. Editing scopes in place You no longer have to create a new credential and revoke the old one to change what it can do. In the detail drawer, an active secret token (and any active agent credential) shows an Edit scopes button. It swaps the read-only scope list for the same segmented None / Read / Write picker used at creation, pre-set to the credential's current scopes. Adjust the segments and Save scopes — both widening and narrowing are allowed. The edit is entitlement-bounded: the resulting scope set must stay within what you are allowed to grant, computed server-side from your own role permissions. The picker disables any segment you cannot grant (defense in depth), and the server rejects an over-broad edit even if the client tries to bypass the UI — see the PATCH contract for the rejection error. Every successful change is written to the audit log with the before/after scope sets. Effect timing differs by surface: API tokens — the edit is immediate. Scopes live on the token row and are read at verify time, so the very next request reflects the new set with no re-issue (the prefix and secret are unchanged). Agent credentials (CLI / MCP) — the live access token is a frozen snapshot, so saving the edit also revokes the current access token. The agent's next call gets a 401 and transparently auto-refreshes onto the new scope set. No re-login is required. Publishable tokens are not editable from this drawer (they use the intake-only catalog); revoked or expired credentials cannot be edited. Approving a CLI / MCP login The CLI's yardstick login opens /settings/agent-auth/approve in your browser with the requested scope set and a PKCE challenge. The approval page shows: Which organization the credential is being issued for. The credential type (cli or mcp) and client profile label. The requested hosted MCP resource/audience, when the login was started with yardstick mcp login --hosted. The requested mode (test or live) — live is flagged with a destructive badge so you do not approve it by accident. The requested scopes, rendered in the same per-resource None / Read / Write picker described above (with action-scope sub-lists and the sensitive-action acknowledgement where they apply). The picker is bounded by the requested scopes: you can narrow the set before approving — for example downgrade a resource from Write to Read or None — but you cannot broaden it. Any permission that would reach beyond the requested scopes (such as a Write segment whose :read is not in the request) is shown disabled, so the approval can never widen past what the CLI asked for. Once you approve, the page completes the loopback callback and the CLI stores the resulting secret in the macOS Keychain. See /docs/cli for the install and login walkthrough and the /docs/mcp article for the MCP equivalent. Hosted MCP credentials are different from normal API or local stdio MCP credentials: they are bound to the protected resource https://api.yardstick.team/mcp. They can initialize, list, and call the hosted endpoint's tools — reads and writes alike, subject to the credential's own scopes and each tool's safety class — but the same token is rejected on direct /v1/* API routes. Env-var pattern for CI Headless environments (CI runners, container images, scheduled jobs) have no Keychain. The CLI falls back to env-vars only when no Keychain credential is present: YARDSTICK_API_TOKEN — the bearer token. Use a test-mode token in CI unless you have an explicit reason to hit live data. YARDSTICK_PROFILE — optional profile label loaded from the credential metadata; useful when multiple credentials are intermixed. YARDSTICK_API_BASE_URL plus YARDSTICK_API_ENDPOINT_MODE=api-origin — point at the production API origin. Use placeholder tokens in any example you commit; never check in real tokens. Store the actual token in your CI's secret manager (GitHub Actions secret, Vercel env var, etc.) and inject it at runtime only. Rotation and revocation Token rotation is per-row from the side drawer on /settings/api-tokens. Revoking a token kills it immediately — the next API call returns unauthorized with the request ID for correlation. Agent credentials issued through the approval flow also support yardstick logout to clear the local Keychain entry. Common questions Which token type should I create? Use a Secret key for anything that runs server-side or from a CLI/MCP wrapper — it can call any route in the scopes you grant. Use a Publishable key only for browser-mediated intake forms (a public job-posting submit); it is clamped to a short allow-list of intake routes and cannot read. I lost the secret right after creating the token. Can I see it again? No. The full secret is shown exactly once in the blocking modal at creation. Only the prefix and metadata are stored afterward, so there is no way to retrieve it. Revoke the token and create a new one. How do I check what a token can actually do before I use it for writes? Call /v1/whoami with the token — it returns the effective scopes the token resolves to at verify time. Confirm the resource and Read/Write level you expect before issuing any write. Can I change a token's scopes without re-issuing it? Yes, for Secret tokens and agent credentials. Open the row drawer on /settings/api-tokens and click Edit scopes. API-token edits take effect immediately; agent credentials revoke the current access token and auto-refresh onto the new scopes on the next call. Publishable tokens are not editable. Troubleshooting The org API access toggle is greyed out. Only an owner can turn org-level API access on. Everyone else sees it as read-only until an owner enables it. Ask an owner to flip the toggle on /settings/api-tokens. My hosted MCP credential gets rejected on a /v1/* call. Hosted MCP credentials are bound to the protected resource https://api.yardstick.team/mcp and only work against the hosted MCP endpoint. For direct /v1/* API calls, issue a Secret key instead. yardstick login can't complete the approval. Approving a CLI or MCP login requires membership in the target organization and scopes you are allowed to grant. If the approve page shows scopes disabled, the request asked for more than your role can grant — narrow the request, or ask someone with broader access to approve it. An agent credential started returning unauthorized after 90 days. The refresh window lapsed. Run yardstick auth reauthorize or yardstick mcp reauthorize. Without --add-scopes, Yardstick preserves every inherited scope it can still issue. To request more access, add --add-scopes and approve the union in the browser. You can renew only credentials you are allowed to manage, and every addition must be available to the approver. I need to add a scope to an existing credential. Run yardstick reauthorize --add-scopes for a CLI profile or yardstick mcp reauthorize --add-scopes for an MCP profile. Do not use login --scopes as an add operation: it starts a new login whose scope list is exactly the complete set you provide. If a token behaves unexpectedly after you have checked its scopes with /v1/whoami, capture the request ID from the error response and reach out to Need help? Email support@yardstick.team so we can correlate it. --- ## Built-in agents URL: https://app.yardstick.team/docs/product/built-in-agents Summary: Use built-in agents to keep feedback moving, prepare interview work, and draft timely candidate updates. Recurring hiring work is easy to miss when recruiters have to check every candidate, interview, and scorecard by hand. Each Built-in agent watches for a specific outcome, prepares the next piece of work, and shows the result in one place. You choose which Built-in agents are active and configure their available schedules. Availability and access The agent catalog appears in the primary navigation when it is available for your workspace. Every active workspace member can see the built-in agent catalog and recent work. Only people who can manage the organization can change its schedule or turn it on or off. If you expect Built-in agents but do not see it, ask an organization owner or administrator to confirm whether it is available for your workspace. Chase missing scorecards The first built-in agent, Chase missing scorecards, helps keep interview feedback moving. When an interviewer has not submitted a scorecard, Yardstick emails a reminder. By default, reminders go out 2, 24, and 48 hours after the interview ends. If feedback is still missing at the final step, Yardstick also emails the hiring manager. The built-in agent is on by default. If your workspace has never saved a reminder setting, the 2/24/48-hour schedule is already active. A saved setting can turn the built-in agent off or use a different schedule of one to five increasing reminder times, up to 72 hours after the interview ends. These are direct reminder emails. They do not first create an email draft or enter an email review queue. The built-in agent never contacts candidates, writes or edits feedback, or sends reminders to people who have opted out. Screen new applicants nightly Screen new applicants nightly looks for new applicants who clearly do not meet the role's requirements. It is off until an organization owner or administrator turns it on. You choose a timezone, a top-of-hour schedule, and the maximum number of applicants it can review in one run. The built-in agent prepares a rejection draft for review. It does not change a candidate's status or send candidate email by itself. A run may be empty, reach its cap, finish with some work skipped or failed, or fail. The agent catalog shows the outcome and counts so you can see what happened without exposing candidate or email details there. Confirm a prepared rejection You can find prepared rejection drafts in Email Drafts. Each draft shows one of these states: Held — the draft is waiting for an organization owner or administrator to confirm the candidate's rejection. You cannot send, edit, or discard it. Released — the rejection has been confirmed and the existing draft is ready for normal email review. It still has not been sent. Invalidated — the candidate or their screening information changed. The draft will not send and cannot be retried. Review the candidate's current details before taking another action. To confirm a held rejection, open the candidate and choose Disqualified. Yardstick checks that the candidate and prepared draft are still current, then changes the status and releases that same draft for review. Confirmation never sends the email. Prepare a panel decision brief Prepare a panel decision brief is off by default. When an organization owner or administrator enables it, Yardstick waits until every assigned scorecard is complete, then prepares one brief from that completed panel evidence. It does not change a candidate's status. Normally, the brief appears as a Decision Brief item in Email Drafts. Open the Decision Brief queue to find those records. The built-in agent is event-triggered, not scheduled: a partially completed panel does not create a brief, and changing scorecard evidence after a brief exists never creates a new one automatically. Review the current evidence and use the existing manual regenerate action when a new brief is needed. Some organizations enabled decision briefs before Built-in agents existed. Those preserved settings appear as Active through existing email automation. That label is historical compatibility information, not a claim that a person approved a Built-in agent at that time. Automatic delivery is a separate Email Automation policy. The Built-in agent switch does not turn that policy on or off. If automatic delivery has an unconfirmed provider outcome, Yardstick labels the queue record Delivery unconfirmed and stopped. It is not marked sent and never retries automatically. An organization owner or administrator may record either a provider-confirmed delivery or a provider-confirmed non-delivery; the latter returns the existing record to normal review without sending an email. Prep interview kits for next week's sessions Prep interview kits for next week's sessions is off by default. An organization owner or administrator can choose an IANA timezone, weekday, and local hour, then review and confirm the schedule. The default schedule is Friday at 09:00 in America/Los_Angeles. Each weekly run prepares current kits for assigned interviewers with sessions in the following week. It does not change an interview or candidate. In live work, a kit may also be sent to the assigned interviewer. In test data, Yardstick prepares test-mode work but never calls an email provider. To open a kit, sign in and use the kit view for your assigned session. Access is checked for that assignment, an active workspace membership, the organization, and live or test mode. An unassigned interviewer, former member, or person in another workspace or mode receives the same intentionally generic Unavailable result; it does not reveal whether a session or kit exists. If Yardstick cannot confirm a provider outcome, it labels that delivery Unconfirmed and stopped. It is not marked delivered and is never retried automatically. The recent-work view shows only the scheduled week and counts; it does not show interviewer names, candidates, kit contents, or provider references. Keep candidates informed Keep candidates informed finds interviewed candidates who are still waiting for an update and prepares a message for your team to review. It is off by default. When you turn it on, Yardstick checks once a day at the local hour you choose. The default schedule is 09:00 in America/Los_Angeles. A candidate becomes eligible after every known interview session is complete, the application is still Interviewing, and the initial wait has passed. The defaults are three days before the first update, seven days between later updates, and at most 100 candidates in one run. The Built-in agent can prepare another update after the cooldown when a candidate is still waiting. It uses interview completion, application movement, and candidate email activity recorded in Yardstick. An email or workflow change that happens outside Yardstick does not reset its timing, so review the candidate's current context before you send. Prepared updates appear in Email Drafts. The Built-in agent decides which candidates are due and when to prepare a draft. Email Automation supplies the active template, personalization rules, sender, review workflow, and delivery. A safe personalized update starts from your active template; if personalization is unavailable, Yardstick prepares the validated template instead and records that fallback in the work report. Active workspace members can read prepared updates. Editing, discarding, or sending requires organization owner or administrator access. Every update remains a draft until one of those people sends it. The Built-in agent does not change application status. If the candidate, interview, recipient, template, or Built-in agent settings change first, Yardstick marks the draft Invalidated and prevents edit, send, or discard. The draft remains in history, and a later valid cycle can prepare a current update. New drafts require both Built-in agents and Email Automation to be available. If Email Automation is paused, Yardstick keeps the Built-in agent's saved schedule and history but prepares no new updates. An organization owner or administrator can still edit or discard a current draft; sending resumes only after both features are available again and the source facts are still current. Review a change before it takes effect People with organization-management access can change the built-in agent from Built-in agents: Open Built-in agents and select the built-in agent you want to change. Set its reminder schedule, nightly schedule, weekly interview-kit schedule, candidate-update schedule, decision-brief on/off setting, or other available configuration. Review the preview. It shows the proposed change before anything changes. Select Confirm to save the reviewed change. If the setting changes while you are reviewing it, Yardstick asks you to make a fresh preview. It does not apply an outdated change. Read recent work Built-in agents shows recent work for each built-in agent. Scorecard reminder counts are an activity signal, not a delivery guarantee. Nightly screening reports scheduled work and review-output counts only. Decision-brief history shows counts for automatic preparation, source freshness, and delivery state. Weekly interview-kit history shows the scheduled week, preparation counts, and a stopped unconfirmed-delivery count when needed. It does not show candidate names, recipients, kit or brief content, or recovery identifiers. Interview-kit history is not a kit-data lookup; open the signed-in kit view for an assigned session instead. Candidate-update history shows how many candidates were checked, how many drafts were prepared, whether a validated template fallback was used, and count-only reasons work was skipped. It never means an email was sent; use Email Drafts to review current messages. When a scorecard reminder run has an available application destination, you can open it from the built-in agent. Use built-in agents from an integration The same built-in agent catalog is also available to integrations. Use the existing API reference for request details, CLI commands for terminal use, or the MCP tool reference for agent tools. Those surfaces use the same preview-and-confirm change flow for Built-in agent configuration. Existing decision-brief read and manual-regenerate tools remain separate from the automatic Built-in agent trigger. Agent note (api) Built-in agents are available in the Yardstick dashboard and through the existing token-authenticated API, CLI, and MCP built-in agent tools. A signed-in dashboard session does not expose a public API route. Built-in agent changes require an explicit preview and confirmation. Keep candidates informed uses the existing Built-in agent tools for its schedule and the existing communications tools for draft review; it adds no separate candidate-messaging command. API reference: /docs/api#built-in-agents CLI commands: /docs/cli/commands#built-in-agents MCP tool reference: /docs/mcp/tools#built-in-agents Support Questions about Built-in agents? Need help? Email support@yardstick.team --- ## Google and Microsoft integrations URL: https://app.yardstick.team/docs/product/google-microsoft-integrations Summary: Which Google Workspace and Microsoft 365 connections Yardstick supports, what data they use, and where booking support stops. Yardstick connects to Google Workspace and Microsoft 365 for the hiring workflows it owns: sending email, keeping interview calendar events reliable, and showing setup health. It does not manage Google Appointment Schedules or Microsoft Bookings pages. This guide explains what Yardstick can access, what stays outside Yardstick, and when a manual provider booking page is the right fallback. Support status | Capability | Current status | What that means | | --- | --- | --- | | Google Workspace email sending | Available | Connect Google when your team sends Yardstick email from a customer-owned sender account. | | Microsoft 365 email sending | Available | Connect Microsoft when your team sends Yardstick email from a customer-owned sender account. | | Google calendar event sync | Available | Connect a Google calendar-event account so Yardstick can create, update, and cancel interview events after scheduling. | | Microsoft calendar event sync | Available for calendar events | Use Microsoft calendar event sync for interview events. This is separate from Microsoft Bookings. | | Google Appointment Schedules | Manual fallback only | You can use your own Google booking page outside Yardstick, but Yardstick does not create or manage it. | | Microsoft Bookings | Deferred | Yardstick does not manage Microsoft Bookings pages yet. Use a manual booking page if your team needs Bookings today. | | Teams transcript import | Deferred | Use manual transcript upload paths until Teams transcript import is available. | | Mailbox reply sync | Deferred | Yardstick does not read mailbox replies or sync mailbox threads today. | | Admin consent, directory sync, and SCIM | Deferred | Enterprise directory setup is separate from per-user Google and Microsoft connections. | What Yardstick accesses Yardstick uses each provider connection only for the purpose shown in the dashboard. The same Google or Microsoft account can appear in more than one place if you use it for separate purposes, such as email sending and calendar event sync. Email sending uses the connected sender account to send approved Yardstick messages. Sender health tells you when the account needs attention. Candidate booking links still come from Cal.com or Calendly. Google Appointment Schedules and Microsoft Bookings are manual fallbacks, not Yardstick-managed booking providers. Calendar event sync keeps Yardstick interview events current after a session is scheduled. It is separate from the candidate booking-link flow. Integration health gives admins a redacted setup view: what is connected, what is blocked, and where to fix it. What Yardstick does not expose Yardstick health views do not expose provider OAuth tokens, Vault IDs, raw provider account identifiers, raw provider event payloads, mailbox content, transcript text, participant emails, or provider secrets. The Yardstick API, CLI, and MCP can show redacted Workspace integration health. They cannot perform browser OAuth setup, reconnect or disconnect providers, expand scopes, write calendar events directly, manage booking pages, sync mailbox replies, or read transcript content. Agent note (api) Agents can use Workspace integration health for read-only readiness checks. Provider setup and provider changes still happen in the dashboard or in the specific Yardstick workflow that performs the change. Agent wrapper concepts: /docs/api/agent-wrapper Setup and reconnects Owners and admins manage provider setup from Admin -> Integrations. Open the affected provider to connect an account, reconnect an expired account, review missing scopes, or open scheduling settings. If a candidate scheduling link is blocked, start with Admin -> Integrations -> Scheduling. The assigned scheduler needs a healthy Cal.com or Calendly connection and an event type for the interview length. If an interview event is missing or stale after a session is scheduled, check the Office Suite or calendar-event sync status in Admin -> Integrations. That is the Google or Microsoft event path. It is separate from Google Appointment Schedules and Microsoft Bookings. Manual provider fallbacks Some teams keep using Google or Microsoft booking pages outside Yardstick. That is fine as a manual fallback, but Yardstick will not manage those booking pages or automatically map bookings back to interview sessions. For Google Appointment Schedules, create and manage the booking page in Google Calendar. For Microsoft Bookings, create and manage the booking page in Microsoft Bookings. In Yardstick, record the agreed interview time manually when the provider page is outside the supported scheduling flow. Support Questions about which provider setup applies to your team? Need help? Email support@yardstick.team --- ## Interview plan builder URL: https://app.yardstick.team/docs/product/interview-plan-builder Summary: Build and save a structured hiring process with outcomes, competencies, skills, scorecards, typed stages, and questions. Use the interview plan builder to design a consistent hiring process for a role. Define the outcomes the hire must deliver, the competencies and skills your team will evaluate, and the ordered stages that move a candidate through the process. A saved plan can be linked to a Job and used as the team's shared scoring rubric. Builder — Role Definition step Where it lives You'll find the builder at /builder. To edit a plan you already started, open it at /builder/:planId. The builder walks you through a fixed seven-step sequence and saves your work on each step as you go. The seven steps, in order: Role Definition — confirm the role, optional Department, and location. Starting from a Job prefills the details that Job already has. Outcomes — the measurable results the hire is expected to produce. Competencies — the predictive traits behind those outcomes. Job Skills — the concrete skills you evaluate against. Scorecard — the rating items the interviewer will mark. Interview Sequence — arrange candidate interviews, reference checks, internal debriefs, and offer meetings as typed hiring-process stages. Set each stage's focus, length, and facilitator roles. Interview Plan — review the assembled plan, generate or edit questions, and save the finished work. To generate Outcomes, Competencies, or Job Skills with AI, complete Role Definition first. When the role name is missing, the generation control stays unavailable and tells you what to finish. Add the role name, then return to the step to generate content. The bottom navigation lets you jump to any visited or completed step; unvisited steps are gated until a prior step is saved. The builder auto-saves as you work and again when you move between steps. A status above the builder shows whether changes are waiting to save, saving, or saved. The final step also has a Save button that confirms the latest version before you leave the builder. One guard is worth knowing up front: you can't leave Role Definition until the role has a name of at least three characters and Yardstick has confirmed the plan's first save. Creation begins once the name is valid. The Next: Define Outcomes button waits while that save is in progress, and the URL changes from /builder to /builder/:planId only after Yardstick receives the saved plan's unique ID. If the first save fails, you stay on Role Definition and your entries remain on the device. Use Retry save in the error message before continuing. This prevents later AI generation, questions, sharing, or export from running against a plan that does not exist yet. Check whether changes are saved The status above the builder updates as you work: Changes waiting to save — you have a newer edit that Yardstick has not confirmed yet. Saving changes… — the save is in progress. All changes saved — Yardstick has confirmed the latest edit. Changes not saved — the save failed. Your work remains on the device; use Retry save before leaving the builder. In Sample Data mode, the status says that changes are saved on this device. Sample plans do not create a saved online plan or a reusable /builder/:planId route. Choosing a Department Department is optional on Role Definition. Leave it blank, or clear a selection, when the plan should belong to the organization without belonging to one Department. Yardstick labels that choice No Department in the Interview Plans list, Job plan picker, and Job Posting plan picker. A No Department plan is still saved in the current organization. Teammates who can access that organization can find it in Interview Plans and attach it to an eligible Job later. The builder is available on both the Free and Hiring-Plan tiers. Exporting a finished plan (Markdown or Excel from the Export menu on the Interview Plan step) is available only when your subscription includes export. Seeding from a job When you start a plan from a Job, the Role Definition step prefills from that Job — its title and role details — and shows a Started from Job link back to the source so the connection is clear. You can edit any prefilled value; nothing inherited is locked. If you start the builder without a source Job, every field begins empty and you author from scratch. The two routes produce the same kind of plan — starting from a Job is a head start, not a different builder. Finishing a plan started from a Job On the Interview Plan step, Save waits for the latest changes, confirms the saved plan's unique ID, and confirms that the plan is linked to its source Job. If any of those checks fail, the builder keeps you on the final step and shows Retry save. After a successful save, Yardstick returns you to the Job. The Job page shows Interview plan saved and linked, the saved plan in the Interview Plan card, and the next action for its public posting. This saves and links the plan; it does not publish a Job Posting or make the posting public. Plans created without a source Job remain available from Interview Plans. You can also attach an eligible unlinked plan from a Job. Publishing a plan through the API Saving in the browser and publishing through the staged-builder API are separate actions. The browser's final Save confirms persistence and any Job link. It does not perform the API publish action. Publishing takes two steps, and the second one needs a person to approve it: Preview. The API returns the finished plan and the exact changes publishing will make. Confirm. An approver reviews that preview and confirms it. Only then does the plan go live. If anything about the plan changes between the preview and the confirm, the publish is held back rather than using stale content — preview it again, then confirm. This is the same review step Yardstick uses for other actions that need approval — see the CLI safe-use guide for the broader pattern. Driving the builder from an agent The builder is fully API-callable. Each step's payload maps to a typed endpoint in the staged-builder API surface, and the CLI exposes typed wrappers around them. The canonical agent path is: # Inspect the current plan state for a job npm run agent:cli -- interview-plans read --interview-plan-id ipd_123 # Preview the publish action — returns binding requirements npm run agent:cli -- interview-plans publish-preview \ --body-json '{"action":"interview_plan.publish_preview","resource":{"id":"ipd_123"},"input":{}}' # After human approval, bind the publish npm run agent:cli -- interview-plans publish-bind \ --body-json '{"action":"interview_plan.publish_bind","resource":{"id":"ipd_123"},"input":{},"binding":{...}}' Authoring the individual builder steps (outcomes, competencies, skills) uses the staged-builder endpoints. The CLI surface is intentionally narrow — every command is a typed wrapper, not a generic HTTP forwarder. Common questions Where's the save button? The builder auto-saves throughout all seven steps. On the final Interview Plan step, Save confirms the latest version before you leave. To resume later, reopen the plan at /builder/:planId. Why won't the builder let me move past Role Definition? Role Definition needs a role name of at least three characters before you can advance to Outcomes. Add the name and wait for Yardstick to confirm the first save. The route gains its :planId only after that confirmation. If the save fails, use Retry save without leaving Role Definition. Can I jump straight to a later step? You can jump to any step you've already visited or completed from the bottom navigation, but steps you haven't reached yet stay locked until the earlier step is saved — the sequence builds on itself. Do I have to start from a Job? No. Starting from a Job prefills Role Definition and adds a Started from Job link, but starting blank is fully supported — you author every field yourself. Both routes produce the same kind of plan. Do I have to choose a Department? No. Leave Department blank when the plan should be available at the organization level. Yardstick shows it as No Department in plan lists and pickers. How do I get the plan out of Yardstick? On the Interview Plan step, the Export menu offers Markdown (.md) and Excel (.xlsx). If your subscription doesn't include export, the menu isn't available. Troubleshooting My changes seem to have disappeared. Check the status above the builder. If it says Changes not saved, use Retry save. If a step looks empty after reopening, confirm you're on the same plan (/builder/:planId) rather than a new blank session started from /builder. I saved the final step but didn't return to the Job. The builder leaves you on the final step when it cannot confirm either the latest save or the source Job link. Read the inline error and use Retry save. Starting without a source Job does not create a Job link; find that plan in Interview Plans or attach it from a Job later. Publishing fails when I try to confirm it. Publishing happens in two steps: a preview of the finished plan, then a person confirming it. If the plan changed after the preview was generated, the confirm is held back so nothing stale goes live. Preview the plan again, then confirm against that fresh preview. I don't see the Export option on the published plan. Export (Markdown/Excel) is gated separately from the builder. If your plan doesn't include export, the option is hidden even though you can still build and publish. I started from a Job but a field looks wrong. Prefilled values are editable, not locked. Correct anything inherited from the source Job directly in the step; the Started from Job link only records where the plan began, it doesn't keep overwriting your edits. Related CLI commands — full list of interview-plans * wrappers and the staged-builder surface. CLI safe-use — the publish preview/bind ceremony applies the same idempotency + binding contract documented here. Scheduling — once a plan is published, scheduling links it to candidate sessions. Scorecards and decisions — the scorecard step of the builder is what interviewers fill out during a scored stage. Need help? Email support@yardstick.team --- ## Getting your jobs onto Google, ZipRecruiter, and job boards URL: https://app.yardstick.team/docs/product/job-distribution Summary: How published Yardstick job pages become eligible for Google, how XML feeds connect to ZipRecruiter and open aggregators, and how to share tracked apply links to other boards. Yardstick creates three things that help people find your open roles: public job pages that Google can understand and Yardstick can notify Google about, board-specific XML feeds you can connect to ZipRecruiter, Careerjet, Talent.com, or Jooble when those channels are available, and tracked apply links you can share anywhere. Yardstick does not automatically post your jobs to third-party job boards. This article explains what happens on its own, what you connect, and what you share yourself. Review distribution settings in Yardstick Organization admins with job distribution enabled can open Settings → Job Board → Distribution to review the current channel state. The page shows Google Jobs notification status, feed availability, manual sharing options, and channels that still need an external setup step. It is a status and feed configuration surface. It does not submit jobs to boards or guarantee that Google or a job board will crawl, rank, approve, index, or display a listing. Use the Distribution page when you need to: Copy a board-specific feed URL and give it to the provider through the provider's intake process. Copy the ZipRecruiter feed URL for your organization and connect it in ZipRecruiter. Disable or re-enable a feed without exposing provider credentials. Confirm whether Google notification status or a local feed is available for the organization. See which channels still require manual sharing or provider follow-up. What a feed status means Feed available means Yardstick can serve an authorized, board-shaped XML snapshot for your organization's current public jobs. It does not mean a provider has received the URL, reviewed it, approved it, crawled it, indexed a job, or chosen to display a listing. An empty feed can still be a successful local response when no published jobs meet that board's required fields. A job with missing required fields is left out of that board's snapshot rather than sent with invented values. Update the job in Yardstick and check the next feed response. If the feed is disabled or unavailable, there is no local feed to submit until an admin restores the channel or the missing setup is resolved. Google Jobs When you publish a job posting, its public page automatically carries the structured markup Google reads to list a role in its job results. Yardstick also sends Google a best-effort notification when a published job URL changes or is removed, as long as Yardstick's Google Indexing integration is configured. You don't configure anything or turn anything on — publishing the posting is the whole product step. A few things worth understanding: This is eligibility, not a guaranteed listing. The notification helps Google discover that a public job URL changed, but Google still decides whether and when to crawl, index, display, or remove the listing. There's no button that makes a job show up immediately, and the timing is Google's to control. The listing is built from what's on the page. Google reads the same title, description, location, and salary that visitors see. Keeping those fields filled in gives Google a complete listing to show. Set a country before you publish. Every new publish or republish requires a country, including remote roles. For a remote role, choose its primary hiring market or the country where candidates must be eligible to work. Yardstick keeps incomplete drafts available while you gather that detail, then asks you to add it before the posting becomes public. Candidates see the country name on the careers page, public job page, and application. Google and feeds with a separate country field receive the matching two-letter country code; feeds that use one combined location field keep their channel-specific location format. Connect an open-aggregator feed Careerjet, Talent.com, and Jooble each expect a different XML shape. If the channel is available in your Distribution settings, Yardstick provides the matching feed URL. You or an authorized operator then submits that URL through the provider's intake process. The provider controls its review, crawl, indexing, ranking, and display decisions. Proof is environment-specific: local proof covers only local, preview proof covers only preview, and production proof must be recorded separately before sharing a production URL. Provider evidence remains open until the provider confirms its own step. Each feed is a full snapshot, not a list of only new jobs. When you publish or update a public job, the next snapshot reflects the current eligible fields. When you unpublish, archive, or otherwise remove a job from the public feed, the job is omitted from the next snapshot. The provider decides when it fetches that snapshot and when its own listing changes. Careerjet Before you start, make sure the job has a public Yardstick page with a title, job URL, location, company name, and complete description. The feed uses a element with nested , , and elements as safely available, rather than a single combined display value. Careerjet's XML guidance is flexible about feed format, but its feed must contain all current jobs and should be updated at least daily. The feed URL has this shape: https://jobs.yardstick.team/feeds/careerjet//.xml Copy the URL shown in Yardstick. Submit your website through Careerjet's recruiter intake and include the feed URL. Careerjet reviews the submission and confirms its own listing decision. A feed URL that loads successfully only proves that Yardstick can serve the local snapshot. Talent.com Before you start, make sure each job has a title, exact company name, city, state or region, country, original publication date, public job URL, and an HTML description with at least 50 visible characters. Talent.com requires these fields in its / feed. The current adapter omits the element because the period and type source fields are unavailable. It never sends partial salary data. The feed URL has this shape: https://jobs.yardstick.team/feeds/talent-com//.xml Give the URL to Talent.com through its XML feed intake. Talent.com can crawl an XML URL after it is provided. The crawl, any review or approval, and any later listing decision belong to Talent.com. If a job does not meet the required fields, Yardstick omits it from this snapshot. Jooble Before you start, make sure each job has a stable job ID, public job link, title, region or city, complete description, company name, and original publication date. Jooble's XML format uses a jobs root, a job id attribute, CDATA for job content, and DD.MM.YYYY for pubdate. The feed URL has this shape: https://jobs.yardstick.team/feeds/jooble//.xml Submit the URL through Jooble's ATS intake. Jooble controls its response, crawl schedule, freshness checks, indexing, and listing decisions. Yardstick includes the current public description and requirements when available, but does not claim that a valid XML response is a Jooble listing. Other job boards Yardstick does not submit your jobs directly to LinkedIn, Wellfound, Indeed, or similar boards. Instead, you share a tracked apply link and post it to those boards yourself. The link routes applicants to your Yardstick apply page and records where they came from, so you can see which channels are working in reporting. You'll find tracked apply links on the job and job-posting pages. Create a link with a source label ("LinkedIn," "Wellfound," a campaign name), copy it, and paste it wherever you're posting the role. Every applicant who uses that link keeps its source label, and that attribution shows up on the candidate and in your source reporting. What each channel supports today: LinkedIn and Wellfound — copy a tracked apply link and post it yourself. Yardstick does not submit the job for you. Indeed — no Indeed feed is exposed in the Distribution admin surface. You can still share a tracked apply link manually. ZipRecruiter — feed available. Yardstick can provide a ZipRecruiter XML feed URL, and you connect that URL inside your ZipRecruiter employer account. Connect a ZipRecruiter feed ZipRecruiter can pull a Yardstick feed for the jobs that have the fields ZipRecruiter needs. Yardstick provides the feed; you connect it in ZipRecruiter. Yardstick does not post jobs directly into your ZipRecruiter account, approve listings, or control when ZipRecruiter processes the feed. The feed URL uses this shape: https://jobs.yardstick.team/feeds/ziprecruiter//.xml Use the URL Yardstick gives you for your organization. Do not share it outside the ZipRecruiter account you want to connect; the token in the URL is what lets ZipRecruiter read the feed. To connect it: Open the feed URL and confirm it loads XML. In ZipRecruiter, add the feed URL to your employer account's XML feed import or feed setup flow. Keep your Yardstick postings filled in with a title, description, country, and a usable city/state location. Jobs missing fields ZipRecruiter requires are left out of the ZipRecruiter feed instead of sending incomplete data. Publish, update, and close jobs in Yardstick. ZipRecruiter reads the feed on its schedule and removes jobs that are no longer in the feed. Submission is not display These terms describe different checkpoints: | Checkpoint | What it means | | --- | --- | | Feed readiness | Yardstick can serve the current local XML snapshot for a channel. | | Submission | An admin or operator gives the feed URL to the provider. | | Review or approval | The provider checks the source, content, or account and decides whether to proceed. | | Crawl | The provider fetches the feed or public job page on its schedule. | | Indexing | The provider adds eligible content to its own search catalog. | | Ranking | The provider orders results according to its own systems and policies. | | Display | The provider chooses whether and where a job appears to job seekers. | Yardstick controls feed readiness and the content of its public job pages. It does not control provider submission, review, approval, crawl timing, indexing, ranking, or display. A provider response, a successful feed fetch, or a Google notification is not proof of a listing. Common questions Do I have to do anything to get my job onto Google? No. Once you publish the posting, its public page is eligible for Google's job results, and Yardstick sends a best-effort change notification when the integration is configured. When the listing actually appears is up to Google. Why isn't my job showing up on Google yet? Eligibility is immediate; indexing is not. Yardstick can notify Google that a public job URL changed, but Google crawls and lists public pages on its own schedule, so there can be a delay after you publish. Make sure the posting is published and its details, including its country, are filled in. Does Yardstick post my job to LinkedIn, Indeed, or ZipRecruiter automatically? No. Yardstick gives you tracked apply links for manual boards. For ZipRecruiter, Yardstick provides a feed URL that you connect in your ZipRecruiter account; Yardstick does not post there directly. What does a Careerjet, Talent.com, or Jooble feed prove? It proves that Yardstick can serve a board-shaped snapshot for the configured organization. You still need to submit the URL through the provider's intake, and the provider decides whether and when to crawl, index, rank, or display the jobs. How do I see which board a candidate came from? Share a tracked apply link with a source label for each board or campaign. The label follows anyone who applies through that link and appears in source reporting. Support Still have a question? Email support@yardstick.team. --- ## Jobs, applications, and candidates URL: https://app.yardstick.team/docs/product/jobs-applications-candidates Summary: Manage open jobs, track applications through the pipeline, and view candidate profiles. Yardstick's hiring loop runs on three linked records. Jobs are the roles you are filling. Applications are job-specific applicant records and the place you do high-volume review. Candidates are people you have advanced into serious consideration for a role. Yardstick keeps one profile for each real person, so their applications and history all stay in one place. This article walks through each of these and the screens where you'll find them. Jobs list Where this lives in the app Jobs list at /jobs — a table of every job your team can see, filtered by the department you have selected. The header shows whether you're on the Free or paid plan. If you've hit the Free-plan job limit, the New Job button is turned off. Job detail at /jobs/:jobId — the workspace for one job, split into tabs. Use Overview for the job's details and pipeline counts, Public posting to manage the public listing, Screening rules to set the review criteria and the knockout questions applicants answer (when application review is turned on for your workspace), and Access and Team to manage who works on the job and what they can do. From here you can open the job's applications or its review queue, when that's available to you. Applications for a Job at /jobs/:jobId/applications — every application attached to one job. Each row shows the applicant's name, the stage they're in, and when something last happened. All candidates — the view across every job of the people your team is seriously considering or has considered. You can filter by pipeline, department, and job (type any part of a job's title to find it), or search by name. Save a view to reapply a filter, search, and sort combination later. When application review is turned on, the header has a link that opens the Review Applications tab with the job you pick already selected. If your workspace has the Talent workspace, this list lives there on the Candidates tab — the same table, filters, and saved views — and visiting /candidates takes you straight to it. Otherwise, /candidates opens the list on its own page. Candidate profile at /people/:personId — one place that gathers every application a person has open, their resume, their contact details, and any follow-ups still pending. The Jobs board Every row in /jobs is a job, not a job posting. A job is the role you're filling ("Senior Designer, Brand"); a job posting is the public listing attached to it. The status chip on a row tells you where the job stands — draft, open, paused, closed, or archived. Postings are managed separately on the job detail page. A new organization with no named department shows no department; its automatically created workspace is not presented as one. The Free plan includes your first 3 jobs in total — not 3 at a time. Drafts and jobs brought in from elsewhere count too, and closing or archiving a job doesn't free up room. When you reach the limit, the New Job button is turned off and shows a warning. Job postings and interview-plan versions A Job is the internal role. Its public posting has its own four-state lifecycle: Draft, Published, Unpublished, and Archived. Publishing a posting opens its non-archived Job when needed. Closing, pausing, or archiving a Job takes down its live postings; reopening leaves them Unpublished until a recruiter publishes them again. A retained publication timestamp records that a posting was live before, not that it is live now. When an interview plan is updated, each changed round receives a new active version. Future candidates and not-started rounds use the newest active version for that round. A round already in progress or completed stays pinned to the version it was given, even if the plan changes; a later round can use the newest version after an earlier round is complete. Job staffing Job staffing is the dashboard record of who is accountable for one Job: the Hiring manager and the Recruiter. When you create a Job from the dashboard, Yardstick can start those fields from the selected department's defaults. Authorized users can later edit or clear the Job override from the Job detail page or the admin user drawer without changing the department defaults. Staffing is different from the other access controls around a Job: Department membership lets someone work across Jobs in a department. Department default is the starting hiring manager or recruiter for new Jobs in that department. Job staffing is the selected hiring manager or recruiter for one Job. Role assignment gives durable capability, such as hiring manager or recruiter scope. Access grant is a temporary or narrow exception for one person. Recruiter staffing can require explicit approval when the selected person needs recruiter capability added or extended. If the approval is canceled, Yardstick leaves the Job staffing, role assignment, and audit history unchanged. The public Jobs API, CLI, and MCP commands manage Job details such as title, department, location, description, and status. They do not set hiring manager, recruiter, department defaults, or Job staffing in this release; use the dashboard for those changes. The Applications pipeline Each Application binds a Person to a Job and moves through a set of statuses: Applied, Scheduling, Screening, Interviewing, Offer, Hired, plus the closed outcomes Offer Rejected, Disqualified, Withdrawn, and On Hold. The status chip on each row reflects where that job-specific application sits today. To move an application, open the application or the person's profile and change the status from the status control — the same dropdown that lists every status above. A few moves ask you to confirm before they take effect: Moving to Hired asks for an employment start date for the application; you cannot complete the move without one. Moving to Offer Rejected, Disqualified, or Withdrawn is treated as a closing outcome and shows a short confirmation so the change is deliberate. If the candidate has no email on file, some status changes that would trigger candidate communication prompt you to add one first (the Email Required dialog). On /candidates you can also select several rows and apply one status change to all of them at once from the bulk action toolbar, which is useful for clearing a batch of early-stage applications. Inside a job's detail page, the funnel summarizes how many applications sit at each stage, while the job's applications view shows the individual rows. An application is not hidden when its internal plan link is missing. It remains in candidate and comparison reporting with an explicit Not linked to a plan state. That state is different from a plan-load error, which is shown as an error with a retry path. If application review is turned on for your workspace, those applications also flow through a focused review queue. The main way in is the Review Applications tab in the Talent workspace (/talent/review-applications). Pick a job from the search box at the top — recruiters and hiring managers see the jobs they can review, each with its applicant count — and work that job's queue without opening the job first. If you have both roles, you start on the recruiter queue and can switch to the hiring-manager queue in one click. The older /jobs/:jobId/review and /jobs/:jobId/hm-review links still work; they send you into this tab with the job and the right role already selected. Open an applicant in the queue to see their resume, the review criteria, recruiter notes, and where the hiring-manager handoff stands, all in one place. Scheduling, scorecards, and decision briefs stay in the candidate workflow at /opportunities/:id, so the review queue keeps you focused on reviewing. Screening questions on the application form The Screening rules tab on a job is where you set the must-have questions every applicant answers. Each one is a knockout question: you write the question, choose how it is answered, and mark which answers rule someone out. Three kinds are available — yes/no, a multiple-choice list where you tick the options that fail, and a number with a threshold ("fails if less than 3 years"). You can also add a short Why note so the rest of the team knows what the question is for. Applicants answer these on the public application form, and their answers are saved with the question exactly as it was worded when they saw it. If you later reword a question or change which answers fail, older applications still show what that candidate was actually asked. A failed answer flags an application. It never rejects or hides one. Someone who answers outside your criteria still lands in your pipeline, in the same place they would have anyway. Nothing is auto-declined and nothing is filtered out of your lists — the decision stays yours. The only submissions turned away at the form are ones that are incomplete: a required question left blank, or a number that cannot be read. Those applicants are asked to fix the answer and submit again. In the review screen, the Application answers card shows each screening question, the answer as the candidate submitted it, and a Passed or Failed badge. A question the candidate was never asked — one you added after they applied — is marked Not asked rather than being treated as a fail. On the rare occasion the answers could not be saved when the application arrived, the application is still kept and the card says so plainly, so a missing answer is never mistaken for a pass. Screening answers are for your team inside Yardstick. They are deliberately not returned by the public API — see the API documentation for the reasoning. Candidates and Person records A candidate is a person advanced into serious consideration for a role. Yardstick still keeps one Person record per real human. If the same person applies to three different Jobs, you'll see three Applications but one Person — their resume, contact data, and historical scorecards live on the Person. /candidates is the cross-Job index for people in serious consideration; /people/:personId shows the unified profile. Each Application is screened against the resume it used, so the same Person can be evaluated on different resumes across roles. When you upload a newer resume, Yardstick uses it for the candidate's in-progress Applications. Applications that have already reached an outcome — Hired, Disqualified, Offer Rejected, or Withdrawn — keep the resume they were screened with. Use the job picker on /candidates when you want to narrow the page to one role — type any part of a job's title to filter the list. Save a view to reapply a filter, search, and sort combination later, and set one as your default so it loads automatically. The header's review-queue link opens the Review Applications tab with whichever job you pick already selected. Older candidates that aren't tied to a job still appear as normal rows and stay searchable by their plan or role name. Access and visibility Yardstick only shows Jobs, Applications, and Candidates that a user has permission to view based on their team and department access. Two people in the same organization can therefore see different rows on /jobs and /candidates: each list is filtered to the departments and teams that person belongs to. If a colleague can see a Job you can't, the difference is almost always department or team access rather than a missing record. The full Jobs board, the per-Job applications view, and the cross-Job /candidates index are part of the ATS surface. Workspaces on the lightweight plan are pointed at interview plans instead; if you don't see /jobs or /candidates at all, your workspace likely isn't on a plan that includes the ATS, and an admin would need to change that. On the Free ATS plan, your first 3 real jobs are included. Jobs that are in draft or were brought in from elsewhere still count toward that limit. On paid ATS plans, only open jobs count for billing; paused, closed, and archived jobs don't. Sample jobs never count. Common questions How do I move an application to the next stage? Open the application or the person's profile and change the status from the status control. The dropdown lists every status — Applied, Scheduling, Screening, Interviewing, Offer, Hired, and the closing outcomes. Some moves (for example Hired) ask for extra detail before they save. Why am I asked for a start date when I mark someone Hired? Hired is the point where Yardstick records when the person begins. The move can't complete until an employment start date is set for that application, so the date prompt appears as part of the change. Why does Yardstick ask for the candidate's email before I change a status? Some status changes can trigger candidate communication, and those need a deliverable address. If the candidate has no email on file, the Email Required dialog asks you to add one before the change goes through. What's the difference between a Job and a Job Posting? A Job is the internal hiring slot ("Senior Designer, Brand"). A Job Posting is the public-facing listing attached to it. The status chip on a /jobs row tracks the Job's lifecycle (draft, open, paused, closed, archived); postings are managed separately under the Job detail page. Can an API, CLI, or MCP caller set the hiring manager or recruiter for a Job? Not yet. Public Jobs commands can create and update the supported Job fields, but dashboard staffing is intentionally separate in this release. Set the hiring manager, recruiter, and department defaults from the dashboard. The same person applied to two roles — do I get two candidate records? No. Yardstick keeps one Person record per real human, so you'll see two Applications but one Person. Their resume, contact details, and history all live on the single profile at /people/:personId. Can I change several application statuses at once? Yes. On /candidates, select the rows you want and apply one status change to all of them from the bulk action toolbar. Troubleshooting I can't see a Job or candidate a teammate can see. Visibility follows team and department access. The record exists, but it's outside the departments or teams you belong to. Ask an admin to grant the access you need, or confirm which department the Job sits in. The "New Job" button warns me I've hit a limit. The Free plan includes only your first 3 jobs in total, and the warning appears once you reach that cap. Because the limit counts every job you've created — including drafts, imports, and ones you've since closed — closing or archiving a job won't free up room. Talk to an admin about moving to a paid plan to create more. I don't see the review-queue entry on /candidates. The header review-queue entry appears only when application review is turned on for your workspace and you're on the full ATS app. Workspaces on the lightweight plan don't get the entry, because the review queue isn't part of that experience. I can't move a candidate to Hired. Hired requires an employment start date for the application. If the move won't complete, set the start date in the prompt; without it the change is blocked. A status change won't go through because of a missing email. Add the candidate's email when the Email Required dialog appears. Status changes that can notify the candidate need a deliverable address on the Person record first. Still stuck after checking your access and plan? Email support@yardstick.team. --- ## Sample data sandbox URL: https://app.yardstick.team/docs/product/sample-data-sandbox Summary: Browse fictional, read-only sample data without affecting your real workspace. Sample data is one shared fictional organization in Yardstick. It gives workspace owners and admins a reliable, read-only way to explore example jobs, candidates, applications, tasks, and reports without changing real hiring data. Agent note (ui-only) Sample data is available only in the Yardstick app. Agents cannot create, refresh, reset, or remove sample content. Browse sample data If you are the current workspace owner or an admin: Open the Sample data / Real data control in the header, or go to Settings → Sample Data. Select Sample data. Use the normal Yardstick sidebar. Browse the fictional records in Jobs, Talent → Candidates, My Tasks, and Reporting. The main sidebar does not change in Sample data. Talent opens its existing Candidates tab for the sample, rather than adding a separate Candidates menu. My Tasks shows a shared fictional work queue. Those items demonstrate follow-up work; they are not assignments to you and cannot be completed or changed. The fictional records are read-only. Yardstick does not offer actions that create, edit, invite, send, schedule, import, bill, or connect external services. While Sample data is selected, Settings opens the Sample Data controls. Switch back to Real data at any time to use your normal workspace. Start with a hiring story The Sample dashboard includes a voluntary Start here option. It opens the strongest fictional hiring narrative without forcing a tour. The showcase has three openable stories: Active pipeline — follow a Job to its Interview Plan, candidate and application, interview evidence, scorecard, recommendation, and Reporting view for that role. Completed decision — inspect a finished hiring decision and the evidence that supports it. Process warning — see how a realistic hiring-process warning appears in the same connected workspace. Every primary name is a normal link with a descriptive back path. The journey uses five curated fictional Plans, supporting candidates and applications, and the same read-only Sample experience throughout. A link that is unavailable or out of date returns you to a safe Sample view; it never falls through to a real workspace record. If sample data is temporarily unavailable Yardstick keeps you in Real data while the shared sample is temporarily unavailable. There is no setup step or repair button for you, and your real workspace stays unchanged. If the view remains unavailable, contact Yardstick support. Hide or show the controls Owners and admins can hide the Sample data controls for themselves in Settings → Sample Data. Hiding controls switches you to Real data and removes the header control, banner, and onboarding prompt only for your account. It does not change the shared sample workspace or anyone else’s settings. To bring the controls back, return to Settings → Sample Data and select Show controls. This restores the choice; it does not automatically switch you to Sample data or change sample content. What is in the shared sample The shared sample includes five active roles, five curated Plans, 24 fictional candidates, 36 applications, eight fictional work-queue items, and reports with two intentional follow-up examples. It does not send email, change calendars, affect billing, or use your real candidates and hiring activity. Sample data is separate from your real workspace. In Sample data, you see only the fictional sample view. In Real data, you see and manage your normal workspace under your usual permissions. How sample content stays current Yardstick prepares and refreshes sample content outside the browser and never uses your account to create records or change memberships. A complete replacement is checked before it becomes current. If that refresh fails, the last successful version remains available while Yardstick retries in the background. You do not need to repair anything. --- ## Interview scheduling URL: https://app.yardstick.team/docs/product/scheduling Summary: Generate scheduling links, let candidates self-schedule, and reconcile interview events. Yardstick scheduling connects each interview round to a candidate-facing booking link, the assigned interviewer's calendar setup, and the final event details the hiring team needs to run the interview. This article covers generating a scheduling link, the candidate self-scheduling flow, and how booked events round-trip back into Yardstick. How scheduling works, start to finish Each interview round gets its own scheduling link. The link is short-lived and tied to that one round. When the candidate uses it, Yardstick hands the booking off to the interviewer's calendar and records the event once it's set. The round is created. When you move an application into an interview stage, Yardstick creates the interview round for it. You generate a link. From the round, you (or an agent) create the candidate-facing booking link. You can also drop {{interview_scheduling_link}} into an eligible candidate email, and Yardstick fills in the same link. The candidate opens the link. Yardstick checks the link, then sends the candidate to the interviewer's calendar to pick a time. The candidate books a time. The chosen time comes back from the calendar and is recorded on the interview round. Changes stay in sync. If the candidate later reschedules or cancels through the calendar, Yardstick updates the round to match. If a candidate closes the booking page without picking a time, re-opening the same link takes them back to the calendar to finish — for the first day after they open it. After they've booked, the link shows a short explanation instead of the calendar. Past that first day, it shows a page asking them to check for a confirmation email, with a button to continue to the calendar if they still need to book. A link that has expired or been turned off shows a short explanation too. Generating a link You generate links from the candidate's application. Each interview round has its own scheduling controls: Generate Scheduling Link creates the candidate-facing booking URL for that round. Once generated, a Copy control puts the link on your clipboard so you can send it to the candidate yourself. Schedule lets you set a date and time manually instead — useful when the time is already agreed and you only need it recorded. The Generate Scheduling Link button is only active once the round is ready to schedule. Two things have to be true: the round needs exactly one interviewer designated to do the scheduling, and that interviewer needs a connected calendar provider. When the button is disabled, hover it to see the specific reason (for example, no interviewer assigned, more than one without a single primary, or the assigned interviewer hasn't connected a calendar yet). A link stops working once the candidate books a time — once they book, it's done. Before that, they can re-open it and be sent back to the calendar for the first day after they first opened it. The link is also short-lived and can expire if it sits unused. The same operation from the CLI: npm run agent:cli -- interview-sessions scheduling-link generate \ --interview-session-id is_123 The response includes the booking link for the round. Generating a new link for the same round turns off the old one, so only the latest link works. Scheduling links in candidate emails You can use {{interview_scheduling_link}} in candidate emails that send a booking link, starting with the interview confirmation email. It means "schedule this candidate's specific interview round," not "book time with the sender." When the interviewer's calendar is set up and ready, Yardstick fills in the round's booking link in the email body. If an email uses {{interview_scheduling_link}} but the round isn't ready to schedule, Yardstick won't send a blank or broken link. Instead, it holds the email as a Pending Review draft that explains what's blocking it, so you can fix the problem and send the email yourself. Use {{sender_scheduling_link}} for Talent outreach only. That one uses the sender's own scheduling link and won't work in candidate interview emails. Candidate self-scheduling Candidates don't need a Yardstick account to open a scheduling link. Yardstick checks the link and either sends them to the booking page or shows an explanation if the link has expired, been turned off, or isn't valid. A candidate who opens the link and leaves without booking can come back to it. For the first day after they open it, the link sends them to the calendar again. After that, Yardstick can no longer tell whether they finished booking, so it shows a page telling them to check their email for a confirmation and offering to continue to the calendar — rather than dropping them on a calendar page that may no longer work. When the link works, the candidate goes straight to the interviewer's calendar to pick a time. The calendar handles the booking, and Yardstick records the time once it's confirmed. The scheduling page itself is deliberately bare: the candidate sees a brief loading moment, then the booking page or a short message explaining why it isn't available. It shows no company branding and no candidate details, and those messages stay generic on purpose. How Yardstick handles time zones Yardstick stores the scheduled start and end as exact moments in time. Staff views for the interview loop, interviewer packet, interview room, and interview kit show those moments in the staff viewer's local time, with the UTC offset included. If the saved scheduling time zone differs from that viewer's time zone, these views also show the original time and zone for context. When you schedule a round manually, Yardstick saves the time zone you selected with the agreed date and time. This keeps the original wall-clock intent clear while staff can read the schedule in their own local time on those views. For candidate self-scheduling, the calendar provider owns the candidate's time zone choices and booking confirmation. Yardstick keeps the provider-confirmed start and end. Yardstick saves the candidate or booker time zone only when the provider sends a standard IANA name, such as America/Los_Angeles, with that documented meaning. Otherwise, Yardstick leaves the time zone unknown instead of guessing. Older scheduled rounds can also have no saved zone. Provider support can differ by event type and account settings. Before using a new Cal.com or Calendly setup with candidates, confirm that the booking page shows the candidate's time zone, complete a test booking, and check that the confirmation and Yardstick round show the same moment. Also verify that Google or Microsoft calendar events keep the same start, end, and duration when participants view them in different time zones. A successful connection test alone does not prove this full booking flow. Calendar integrations Scheduling links are generated through connected provider credentials: Cal.com. Each scheduler connects their Cal.com account and matches their Cal.com event types to interview lengths. Candidates book through Cal.com, and the booked times come back into Yardstick automatically. Calendly. Each scheduler connects their Calendly account and matches their Calendly event types to interview lengths. Candidates book through Calendly, and the booked times come back into Yardstick automatically. Each interviewer connects their own scheduling provider from Admin → Integrations → Scheduling. After connecting, you can use Test connection there to confirm the credentials work before relying on them for a real candidate. For Cal.com, a successful test also retries booking-notification setup when setup is incomplete or a temporary provider problem interrupted it. Because the connection is per-interviewer, the person assigned to schedule a round must have connected their own provider — connecting yours doesn't cover a teammate's rounds. What the Cal.com status means The Cal.com card separates a working API key from working booking notifications: Secret generated means Yardstick saved the secure notification setup, but Cal.com registration has not finished. Yardstick retries eligible setup in the background, and you can choose Retry now. Registered on Cal.com means Cal.com accepted the booking-notification registration. It does not yet prove that a notification reached Yardstick. Deliveries verified means Yardstick received and verified at least one booking notification. This is the only status that proves delivery. Booking notifications failed means the most recent registration attempt did not succeed. Yardstick retries temporary provider problems in the background. If the saved API key is no longer accepted, choose Reconnect Cal.com instead. Test connection first checks the saved API key. When the key works, it can also recover missing or temporarily failed Cal.com notification registration and updates the card with the result. A successful credential test alone is not proof that a booking notification has been delivered. Notification setup and recovery stay in the Yardstick dashboard. The existing API and CLI capability is unchanged: it generates scheduling links and does not expose a separate Cal.com registration, retry, or reconnect action. The calendar used for a round is set when you generate the link. To switch to a different calendar, generate a new link. Google Calendar event sync and Microsoft calendar event sync are separate from candidate booking links. They keep interview events current after a session is scheduled; they do not create or manage Google Appointment Schedules or Microsoft Bookings pages. See Google and Microsoft integrations for the current support boundaries. If a round is blocked because an event type is missing, the assigned interviewer needs to choose a provider event type for that interview length from Admin → Integrations → Scheduling. The blocked state links to /admin/integrations/scheduling so the interviewer can fix the mapping. Common questions Why is the "Generate Scheduling Link" button greyed out? The round isn't ready to schedule yet. It needs one interviewer designated to schedule it, and that interviewer needs a connected calendar with an event type for the interview length. Hover the disabled button to see the exact blocker. How does the candidate actually book a time? Generate the link, copy it, and send it to the candidate. Opening it redirects them to the assigned interviewer's calendar provider, where they pick a slot. Yardstick records the booked time when the provider confirms it. Where do I connect my calendar? Open Admin → Integrations → Scheduling. Yardstick supports Cal.com and Calendly. Use Test connection after connecting to confirm the saved credentials work. For Cal.com, check the separate notification status before relying on automatic booking updates. Can I enter a time myself instead of sending a link? Yes. Use the Schedule action on the round to set a date and time manually — useful when the time is already agreed. The candidate needs to reschedule — do I generate a new link? Not usually. When a candidate reschedules or cancels through the calendar, the change syncs back onto the round on its own. Generate a new link only when you want to deliberately turn the old one off — generating a new link always cancels the previous one. Troubleshooting The Generate button is disabled and the tooltip says no interviewer is assigned. Assign an interviewer to the round first. Scheduling needs exactly one person designated to schedule it. The tooltip says the assignment is ambiguous. The round has more than one interviewer and no single primary, so Yardstick can't tell whose calendar to use. Mark one interviewer as the primary for that round and the button activates. The assigned interviewer connected a calendar but the link still won't generate. Confirm the connection is healthy with Test connection in Admin → Integrations → Scheduling. A connection that has expired or been disconnected blocks generation even though it once worked. The candidate's link shows an error instead of a booking page. Links are short-lived, and generating a new one turns off the old one. An expired or turned-off link shows a short, generic error instead of a booking page. Generate a fresh link and send that one. The candidate says the link no longer takes them to the calendar. That's expected once they've booked, or more than a day after they first opened it. If they've already booked, the link tells them it has already been used and asks them to contact the recruiting team. If it's only been more than a day, they get a page asking them to check for a confirmation email, with a button to continue to the calendar. If they never booked, generate a fresh link and send that one. The candidate booked, but the time isn't showing in Yardstick. Booked times come back from the calendar, so a confirmed booking should appear on the round shortly after. If it doesn't, open the interviewer's integration and check both parts of the status. Use Test connection to check the saved credentials and retry eligible Cal.com notification setup. If the card says Reconnect Cal.com, reconnect before trying again. If the credentials work and the card says Deliveries verified, but the time still hasn't synced, reach out for help. Setting up a calendar for the first time? Do a test run. Before you rely on a newly connected calendar for a real candidate, try the whole flow once yourself: generate the link, open the booking page, book a time, and confirm it shows up on the interview round. Related Interview plan builder — the plan must be published before sessions can be scheduled against it. Google and Microsoft integrations understand calendar-event sync, manual booking-page fallbacks, and data boundaries. Scorecards and decisions — once the booked event happens, the interviewer fills out the scorecard for the round. CLI commands — the interview-sessions scheduling-link generate wrapper and related commands. Need help? Email support@yardstick.team --- ## Scorecards and decisions URL: https://app.yardstick.team/docs/product/scorecards-decisions Summary: Submit interview scorecards, generate decision briefs, and record final hiring recommendations. After an interview is booked and run, three things happen: the interviewer fills out a scorecard, the hiring team reviews a combined decision brief, and a hiring manager records the final recommendation. This article walks through all three. Per-interview scorecard Scorecards (per interview) Each interviewer scores the candidate on the round they ran, at /opportunities/:opportunityId/interview/:interviewId/scorecard. The scorecard shows the items the round is set up to evaluate, and it remembers ratings you saved earlier so a partial draft is never lost. What you score depends on how the round was set up in the interview plan. A scorecard item is one of: Competency rating — score the competency this round is responsible for evaluating. Job skill rating — score the specific skills the round covers. Outcome — a structured result the plan defines for the round (for example, a recommendation outcome). Each item carries an optional note, so you can record the example or signal that justifies the score. If the round was set up to include a final recommendation, finishing the scorecard takes you straight to the recommendation step (see below). The round stays open while you review and submit that recommendation. You score on the round's defined scale, and your work saves on its own as you go — there is no separate save button. You can leave the scorecard and come back; your in-progress ratings and notes are still there. If the page opens to No Scorecard Items, the round has no scorecard configured yet. Open the interview plan, add scorecard items to that round, and reopen the scorecard. If you reach Scorecard not available, the interview itself has not been run or recorded yet — complete the interview first. Submitting a scorecard from the CLI: npm run agent:cli -- interview-sessions scorecard submit \ --interview-session-id is_123 \ --body-json '{"interviewer_user_id":"usr_abc","ratings":[{"item_id":"sk_1","item_type":"job_skill","rating":3}]}' The CLI command is a typed wrapper over the public scorecard API, with the same rating-item fields and validation rules. Decision briefs (per application) The decision brief pulls every interviewer's scores into one view so the hiring team can decide together instead of comparing notes by hand. It lives at /opportunities/:opportunityId/brief, and a brief is generated once the interviews are done and their scorecards submitted. Decision briefs are part of the email-and-automation tier — if your plan does not include it, the page invites you to upgrade rather than showing a brief. The brief opens with the headline: A panel recommendation — Strong Hire, Hire, Mixed, No Hire, or Strong No Hire — summarizing where the panel landed. A composite score and a count of how many interviewers recommend the candidate (for example, "3 of 4 interviewers recommend"). Below the headline, the brief breaks the decision down: Summary. A written narrative of how the candidate performed against the plan's competencies and skills. You can regenerate it; the latest version is the one shown. Strengths and concerns. The recurring positives and risks, each tagged with the interviewers who noted them. Outlier notes. Where one interviewer's read differs sharply from the rest, so a single strong or weak signal is not lost in the average. Scorecard comparison. Every interviewer's score per item, side by side, so disagreement stays visible rather than being averaged away. The summary is written by AI, and the brief says so. Treat it as a supplement to your own judgment, not a replacement — verify the key details before you make the call. Regenerating the brief from the CLI: npm run agent:cli -- applications brief regenerate \ --application-id app_123 (Regenerating recomputes the brief from the current scores — it doesn't just re-read the last one.) Final recommendation (per interviewer, per application) After the per-item ratings, each interviewer records one final hiring recommendation for the candidate — a single rating plus an optional note. It is recorded at /opportunities/:opportunityId/interview/:interviewId/recommendation. The rating is a five-point scale, with the labels you see on the page: | Rating | Label | What it means | | --- | --- | --- | | 0 | No Rating | Not enough information gathered | | 1 | Strong No Hire | Strong evidence against hiring | | 2 | No Hire | Evidence suggests not hiring | | 3 | Hire | Evidence supports hiring | | 4 | Strong Hire | Strong evidence for hiring | The page loads any recommendation you saved earlier, so you can pick up a draft and either change it or submit for the first time. Your rating and note save on their own as you go. Choose Submit recommendation to save the recommendation and finish the interview. After the save succeeds, the interview is marked done and locked, and your recommendation flows into the decision brief so the panel view stays current. If the round has no recommendation step, submitting the scorecard finishes and locks the interview instead. Recording a final recommendation from the CLI: npm run agent:cli -- applications final-recommendation record \ --application-id app_123 \ --interviewer-user-id usr_abc \ --rating 3 The rating value maps to the labels in the table above. Together: the round trip A complete loop for one candidate, end to end: Schedule the round via /docs/product/scheduling. Interview happens at the booked time. Scorecard is filled out by the interviewer. Final recommendation is submitted by the interviewer, which locks the round after the save succeeds. Decision brief is regenerated and reviewed by the hiring team. The application moves on — to Offer, Hold, or Reject. These moves need approval before they take effect (see CLI safe-use). Common questions Do I have to fill out the whole scorecard in one sitting? No. Your ratings and notes save as you go, so you can step away and return — your in-progress work is still there. A round with a recommendation is locked after you choose Submit recommendation and the save succeeds. A round without a recommendation is locked when you submit its scorecard. Why is the rating scale "Strong No Hire" to "Strong Hire" instead of a number? The recommendation uses a five-point hire/no-hire scale so the signal is about the decision, not an abstract score. You can still leave a note to explain your reasoning. "No Rating" is there for when you did not gather enough to make a call. Who can see my scores before the decision brief? Scores feed the per-application decision brief, where the panel compares them side by side. The brief shows each interviewer's score per item rather than blending them, so a dissenting view stays visible. Can I change a recommendation after I submit it? Yes, until the recommendation is submitted successfully. Reopen the recommendation page; it loads what you saved and lets you update it. Once you choose Submit recommendation and the save succeeds, the interview is locked. Does the AI make the hiring decision? No. The decision brief's summary is AI-generated and labeled as such. It gathers and summarizes what the panel found — the decision stays with the hiring team. Troubleshooting The scorecard page says "No Scorecard Items." The round has no scorecard configured. Open the interview plan, add scorecard items to that round, and reopen the scorecard. The page says "Scorecard not available." The interview has not been run or recorded yet. Complete the interview first, then open the scorecard. There's no decision brief for this candidate. A brief is generated after the interviews are done and their scorecards submitted. If interviews are still outstanding, the brief shows "No Brief Generated Yet" until they are finished. The brief page asks me to upgrade instead of showing a brief. Decision briefs are part of the email-and-automation tier. If your plan does not include it, the brief is unavailable. Need help? Email support@yardstick.team can confirm what your plan covers. My scores aren't showing up in the comparison table. The comparison only counts scored items, so any item left unrated is skipped. Reopen your scorecard and confirm each item has a rating, then regenerate the brief. Related Interview plan builder — the scorecard items come from the published plan's scorecard step. Scheduling — interview events feed the per-interview scorecard surface. CLI commands — typed wrappers for every action documented here. Need help? Email support@yardstick.team --- ## Two-step verification, passkeys, and trusted devices URL: https://app.yardstick.team/docs/product/security-two-step-verification Summary: Set up two-step verification and passkeys, remember trusted devices, recover access, and set your organization's security policy in Yardstick. Yardstick gives you several ways to keep your account secure, plus one setting your organization controls. You manage all of them from My Settings → Security unless noted otherwise. Two-step verification Two-step verification adds a second step to your sign-in: after your password, you enter a 6-digit code from an authenticator app like 1Password, Google Authenticator, or Bitwarden. Enroll an authenticator Open My Settings → Security. Under "Two-step verification," click Set up two-step verification. Scan the QR code with your authenticator app, or paste the secret manually. Enter the 6-digit code your app shows. Yardstick checks it and turns on two-step verification. Yardstick displays ten recovery codes. Save them somewhere safe — they are the only way back in if you lose your authenticator device. The dialog will not let you close until you tick "I have saved these codes." Sign in with two-step verification After you sign in with your password or single sign-on, Yardstick shows a verification screen. Enter the 6-digit code from your authenticator app to continue. Turn off two-step verification From My Settings → Security, click Remove and confirm. This clears your recovery codes and revokes every trusted device on your account right away. If your organization requires two-step verification, the Remove button warns you that you'll be locked out at your next sign-in until you set it up again. Regenerate recovery codes Click Regenerate recovery codes from the Security tab. You will see ten fresh codes; the previous batch stops working immediately. Save the new codes. Passkeys A passkey lets you sign in with your device instead of a password and a code. You unlock it with your fingerprint, face, or device PIN, and it's harder to steal than a password. Note: Passkeys are off by default. Ask your Yardstick administrator to turn them on for your organization. Register a passkey Once passkeys are turned on, the Security tab shows a Passkeys card. Click Add passkey, give it a name you'll recognize (like "MacBook Air"), and your browser asks for your fingerprint, face, or PIN. You must have two-step verification (TOTP) enrolled before you can add a passkey. Sign in with a passkey On the verification screen, click Use a passkey instead. Your browser asks for your fingerprint, face, or PIN, and then you continue to the app. If your organization uses the default mode, Passkey or TOTP, a passkey sign-in satisfies the two-step verification requirement and you are not asked for a code. If your organization uses the strict mode, TOTP always required, you are asked for a code even after the passkey. Remove a passkey From the Passkeys card, click Remove next to any passkey. Trusted devices After you pass a two-step verification check, you can tick Remember this device. The next time you sign in from the same browser within the trust window, you skip the verification code. Your organization sets how many days the trust lasts. The "Remember" option only appears when your organization allows it. Review and revoke trusted devices From the Security tab, the Trusted Devices card lists each device with its browser, when it was added, and when it was last used. Click Revoke on any device to end its trust right away — the next sign-in from that browser will ask for a verification code. Trust does not extend to sensitive actions Some actions always ask for a fresh verification code, even on a trusted device: Turning off two-step verification. Regenerating recovery codes. Changing your organization's two-step verification policy. Recovery codes If you lose your authenticator and have no trusted device left, use a recovery code: On the verification screen, click Use a recovery code instead. Paste one of the codes you saved when you set up two-step verification. Yardstick turns off your authenticator (and any passkeys), revokes all trusted devices, and signs you in. Re-enroll two-step verification from My Settings → Security. Each recovery code works only once. If you have no codes left and no other way in, contact Need help? Email support@yardstick.team — we can reset your two-step verification after confirming your identity. For organization owners and admins Set the two-step verification policy Open Admin → Organization Settings → Security. The policy controls: Enabled: turn the policy on or off. Target group: who the policy applies to (owners and admins only, or all members). Assurance mode: Passkey or TOTP (default): a passkey sign-in counts on its own. TOTP always required (strict): even passkey users enter a code. Grace period: how many days new members have to set up two-step verification before the policy blocks them. Remember device: whether members can choose to remember a browser. Trust duration: how many days a trusted device stays trusted. Changes are audited. See member compliance Admin → Members shows each member's two-step verification status: whether they're set up (with an authenticator or a passkey), how many recovery codes they have left, and their last activity. Use it to nudge people who haven't set up before the policy takes effect. Before enabling enforcement Before you turn the policy on for all members: Set up two-step verification on your own account first. The Security tab won't let you turn on the policy while you aren't set up. Use the compliance table to see who hasn't set it up, and email them. Set a sensible grace period (14 days is the default). During the grace period, members see a reminder but the app still works. Recover a locked-out user If a single-owner organization loses access — the only owner can't pass two-step verification and has no recovery codes — Yardstick support can reset two-step verification after verifying your identity. Email security@yardstick.team with the locked-out user's email and a brief description of what happened. What does not count as two-step verification A trusted device on its own is not two-step verification. The sensitive actions above always ask for a fresh code, so a trusted browser cannot be used to skip them. An API token is not two-step verification. Once you create a token while set up for two-step verification, that token keeps working for scripts and agents on its own. But creating a new token requires you to be set up for two-step verification at that moment. Browser support and constraints Two-step verification codes: work in any browser. Passkeys: need a recent browser that supports passkeys. The passkey options don't appear in browsers that can't use them. Trusted devices: need cookies. If your browser blocks cookies aggressively, the Remember this device option may not stick. Common questions Do I need an authenticator app, or can I use a passkey on its own? You set up two-step verification first — a passkey is added on top of it, not instead of it. Once both are set up and your organization uses the default Passkey or TOTP mode, a passkey sign-in satisfies the requirement on its own. I have a new phone. How do I move my authenticator? Sign in on your trusted device or with a recovery code, click Remove under My Settings → Security, and set up the authenticator on your new phone. You get a fresh set of ten recovery codes — save them. Why don't I see the "Remember this device" option? It only appears when your organization allows trusted devices. An owner or admin controls this under Admin → Organization Settings → Security. Will turning on two-step verification break my API tokens? No. Tokens you already created keep working for scripts and agents. Only creating a new token requires you to be set up for two-step verification at that moment. Troubleshooting I don't see the Passkeys card on the Security tab. Passkeys are off by default and turned on per organization. Ask your Yardstick administrator to turn on passkeys for your organization. The app keeps asking for a code even after I sign in with a passkey. Your organization uses the strict TOTP always required mode, which asks for a code even after a passkey. An owner or admin can change the mode under Admin → Organization Settings → Security. I'm trusted on this browser but still get asked to verify for some actions. A few sensitive actions always ask for a fresh code, even on a trusted device — turning off two-step verification, regenerating recovery codes, and changing your organization's policy. Enter the code to continue. I lost my authenticator and have no trusted device or recovery codes. Use a recovery code on the verification screen if you have one. If you have none and no other way in, contact Need help? Email support@yardstick.team — we can reset your two-step verification after confirming your identity. Related API tokens: see API token setup. --- ## Prospects, pools, activity & follow-ups URL: https://app.yardstick.team/docs/product/talent-crm-prospects Summary: Track prospects, group them into pools, log activity, and schedule follow-ups from the profile and My Tasks. Yardstick's talent workspace is where you keep track of prospects: people you may want to recruit or activate later. They might be referrals, alumni, silver medalists, declined offers, or people worth a warm conversation when the right role opens. This article covers adding and managing prospects, grouping them into pools, logging what happened in each conversation, and scheduling the next follow-up so nobody slips through. You'll find everything under Talent in the main navigation, split across the Prospects, Pools, and Sequences tabs. Add a prospect A prospect is a person you may want to recruit or activate later. To add one: Open the Prospects tab and click Add a prospect. Pick an existing person, or create a new one if they aren't in Yardstick yet. The person record holds the shared name, email, and phone. Optionally set a Source — where the prospect came from, like a referral, an event, or LinkedIn. Click Add prospect. The new prospect appears in the list. Each prospect has an owner, a status, and a timeline of everything you've logged. Who owns a prospect Every prospect has an owner: the person on the hook for the relationship, and the person who gets the reminder when a follow-up comes due. Whoever adds a prospect owns it. The Add a prospect panel has no owner to choose — the person who clicks Add prospect becomes the owner, and you hand it on afterwards if it belongs to someone else. To change the owner, open the prospect and use the Owner dropdown on its profile; it saves as soon as you pick. To move several at once, tick them in the list and use Assign owner in the bar that appears above the table. Both offer Me, Unassigned, and your active teammates. Reassigning moves the reminder. Hand over a prospect with a follow-up scheduled and its Follow up with … task moves to the new owner's My Tasks. Unassigned is a real choice. Leave a prospect unowned and it stays there for whoever on the team picks it up — filter the list by Owner: Unassigned to find them. Worth knowing: unassigned does not mean nobody is reminded. A follow-up on an unowned prospect goes to whoever last changed it, or failing that whoever first added it. It only goes to nobody when Yardstick cannot identify any of the three. An owner has to be active in your workspace. The dropdown lists active teammates only. If someone is deactivated after the list loads, picking them is still refused: nothing is saved and the prospect keeps the owner it had. The profile dropdown tells you the owner was not saved, and a bulk assign reports how many rows failed and leaves those rows selected so you can retry them with a different owner. The Prospects tab listing tracked prospects in the talent workspace Group prospects into pools A pool is a reusable group of prospects — for example silver medalists, declined offers, alumni, or people to revisit for a future role. Pools help you find the right people fast when a role opens. Open the Pools tab and click Create a talent pool. Give it a name and an optional description. From any prospect, use Add to pool to put them in one or more pools. A prospect can belong to several pools at once. Their profile shows every pool they're in under the Pools row. Log activity Every meaningful touch with a prospect belongs on their timeline, so you and your teammates always know where the relationship stands. Open a prospect's profile and click Log activity. Choose the Activity type — Note, Call, or Meeting. Add notes about what happened: outcomes, next steps, anything worth remembering. Click Save activity. The activity lands at the top of the prospect's timeline with the date and who logged it. Right after you save, Yardstick offers to Schedule the next touch? — see below. Outreach emails sent through a sequence are added to the timeline automatically, so you don't log those by hand. What updates "Last touch" Last touch is when someone last made contact with a prospect. You can sort the prospect list by it, and reporting uses it to count prospects nobody has contacted. Nobody has contacted a prospect until one of the actions below happens. Adding someone, importing them, or opening their profile is not by itself contact. In the prospect list, those people read Never contacted in the Last touch column rather than showing a date. You can also find them through the Stale (>90 days) view, which counts anyone never contacted as needing outreach, or by the list's next-step cue, which reads Add first touchpoint until there is a real contact. A nearby date is easy to mistake for it. A prospect's profile keeps its own Reviewed row, and every import stamps that date, so a freshly imported prospect can show a recent Reviewed date with nobody having contacted them. A contact date can be carried in on an import, but only through the Yardstick API, CLI, or MCP, whose rows take a last_contacted_at value; the spreadsheet import in the dashboard has no column for it. Several everyday actions count as contacting the person, and move the date: Logging a Call or a Meeting on the timeline. An outreach email that actually sends — whether you approved the draft yourself or auto-send sent it. Completing a follow-up in My Tasks. This one counts however you label it, including Note: you got back to the person, which is the whole point of the follow-up. Ticking off a sequence task step whose purpose is Reach out — see Outreach sequences. These don't: Logging a Note from Log activity. A note records what you learned or thought, not a touch — completing a follow-up is the exception above. Ticking off a sequence task step whose purpose is Internal — research, prep, an internal check. Anything that isn't a touch at all: adding someone to a pool, enrolling or unenrolling them from a sequence, or discarding a draft instead of sending it. Two rules apply to every update in the first list: Logging something in the past never moves the date back. Record a call from last month and Last touch stays on your most recent contact. You can still date an activity to when it actually happened — that's what Occurred at (optional) in Log activity is for — it just won't overwrite something newer. It can never be a date in the future. The Occurred at picker offers today and earlier only, and an import or an API write carrying a future date is refused rather than accepted. A future date would leave the prospect looking permanently fresh. Reporting is a step behind on all of this. Its staleness counts still fall back to the review date and to logged activity, so a prospect can read as non-stale in a report while nobody has actually made contact. One exception: a contact date sent straight through the Yardstick API or CLI is taken as given, so it can move Last touch earlier as well as later. It still can't be a date in the future. Schedule a follow-up A follow-up is a reminder to get back to a prospect on a specific day. You can set one two ways: Right after logging activity. When the Schedule the next touch? step appears, pick Today, In 3 days, or Next week. To pick a different day, use the Next follow-up row on the profile instead. From the profile. Use the Next follow-up row to set or change the date and add a note about what to do next. Follow-ups are scheduled by day, not by a specific time — you pick the day you want to get back to them. Once a follow-up is set, it shows up as a task in My Tasks so it's part of your daily list, not buried in a profile you might not reopen. A prospect profile showing the Next follow-up row and recent timeline activity Complete a follow-up from My Tasks When a follow-up comes due, it appears in My Tasks, titled Follow up with . Open My Tasks. Due follow-ups show in the Today tab. Find the prospect's follow-up and mark it done. Add a quick note about what you did — that note is logged to the prospect's timeline as a completed follow-up. Completing the follow-up clears the date and removes the task from your list. If there's a next step, log it and schedule another follow-up so the thread stays alive. Completing a follow-up also updates the prospect's Last touch date, whichever of Note, Call, or Meeting you pick under What happened? — see what updates Last touch, above. Agent note (api) Managing prospects, logging activity, and setting a follow-up date are available through the Yardstick API, CLI, and MCP, so an agent can keep prospects current without the dashboard. Marking a follow-up complete is a dashboard action. Pools and outreach sequences are operated through the dashboard only — see the sequences guide. API token setup: /docs/product/api-token-setup Outreach sequences & auto-send: /docs/product/talent-crm-sequences Common questions What's the difference between a prospect and a candidate? A prospect is someone you may want to recruit or activate later. An Application is the job-specific applicant record and the high-volume review surface. A candidate is someone advanced into serious consideration for a role. Prospects live under Talent; applications and candidates live with Jobs. Can two people own the same prospect? Each prospect has one owner, but the whole team sees the prospect and its timeline. Change the owner from the prospect's profile. Why did a follow-up task appear on my list for a prospect I didn't add? Because you own it. A prospect that arrives without a named owner belongs to whoever brought it in — you, if you ran the import yourself, or the teammate whose credentials an integration or the Yardstick API is set up with. A follow-up date on a prospect always creates the reminder for its owner. If it should belong to someone else, change the owner from the prospect's profile and the reminder moves with it. Imported prospects never arrive with a follow-up date already set, so an import on its own never fills up anybody's task list. An import row named an owner who is no longer active. What happens to it? Usually you catch it before anything is written: the preview marks that row Invalid, so you can correct the owner and preview again. Yardstick checks the owner again before creating a new person. The row only fails after a person is created in the narrow case where that owner is deactivated during the import — and then it is only that one row; the rest still lands. Start a new import for that row rather than retrying the finished one — once an import has run, it cannot be run again. If that narrow case saved a person with an email address, Yardstick recognizes that person and reuses them. If the row has only a name, the preview may offer an advisory match, so pick that match; if it isn't offered, add their email address to the row and Yardstick will match them for certain. Whoever runs the import owns any new prospect from a row that names no owner at all, and an import only changes the owner of a prospect you already have when the row actually names an owner. My follow-up disappeared after I completed it — is that expected? Yes. Completing a follow-up clears its date and removes the task. The completion is recorded on the prospect's timeline, and you can schedule a new follow-up whenever you need the next reminder. Related Outreach sequences & auto-send — enroll prospects in a multi-step email sequence and let later emails send automatically. Jobs, applications, and candidates — once a prospect applies to a role, they have an Application for that Job; when they move into serious consideration, they become a candidate for that role. Need help? Email support@yardstick.team --- ## Outreach sequences & auto-send URL: https://app.yardstick.team/docs/product/talent-crm-sequences Summary: Build a multi-step outreach sequence, enroll prospects, review email drafts, and turn auto-send on or off. An outreach sequence is a series of steps you set up once and run for many prospects — a first email, a wait, a follow-up email, maybe a reminder to call. This article covers building a sequence, enrolling prospects, what happens at each step, and how to let later emails send on their own with auto-send. You'll find sequences under Talent, on the Sequences tab. Build a sequence Open the Sequences tab and create a new sequence. Give it a name and an optional description — a short note on who it's for and the thesis behind it. The description stays internal. Add steps. Each step is one of two kinds: An Email step — a draft email Yardstick prepares for review. A Task step — a reminder for a person to do something, like make a call. On a Task step, choose its Task purpose: Reach out or Internal. See "Reach out or Internal" below — it decides whether ticking the task off counts as having contacted the prospect. For each step, set a Day delay: how many days after the previous step this one falls due. The first step is day 0. A sequence with two email steps in the builder Start from a template When you create a new sequence, you start in a gallery. Blank sequence is the first choice — pick it to build from scratch as above. After it come a few starter templates: ready-made outreach sequences for common situations, like reaching out to a passive prospect or re-engaging a past finalist. Each card shows the template's name, a one-line description, and how many steps it has. The New Sequence gallery showing Blank sequence and the starter templates Pick a template to preview its steps, then give it a name and an optional description before you create it. The name and description start filled in from the template — change them to whatever fits. Choosing a template copies it into a new sequence that's entirely yours. Once created, it's an ordinary sequence: edit the wording, reorder steps, add or remove steps, archive it, or turn on auto-send — exactly as you would with one you built from blank. The copy keeps no link back to the template, so later changes to the template never touch sequences you've already created. One rule applies whichever way you start: the name has to be unique among your active sequences. If a name is already in use, you'll be told to rename before the sequence is created. Enroll prospects Enrolling a prospect starts the sequence running for them. You can enroll one at a time or in a batch: From a profile. Open a prospect and use Enroll in sequence in the Sequences row, then pick the sequence. In bulk. Select several prospects in the list and choose Enroll in sequence from the action bar. Once enrolled, each step comes due based on its day delay, starting from when you enrolled them. What "due" means Steps come due by day, not at a clock time. A step with a 2-day delay falls due two days after the previous step — on that day, not at a specific hour. So a prospect won't get two emails minutes apart; each step waits for its day to arrive. Email steps create drafts to review When an email step comes due, Yardstick prepares a draft and marks it Pending Review — it does not send on its own (auto-send is the exception, covered below). To send it: Open the draft from My Tasks or your email drafts and click Review draft. Read it, Edit if you want to adjust the wording, then click Send. Once sent, the email is logged to the prospect's timeline, their Last touch date moves to now, and the sequence moves on to the next step. An auto-sent email does the same. Use variables in email steps Email steps can include variables that Yardstick fills in when it prepares a draft. The supported variables are: {{recipient_first_name}} {{recipient_full_name}} {{sender_first_name}} {{sender_full_name}} {{sender_scheduling_link}} {{company_name}} {{role_title}} {{source_label}} Current company and current title are not supported variables. If you type an unknown token, Yardstick leaves it exactly as written so you can catch it during review. {{sender_scheduling_link}} adds a link for the prospect to book time with the person sending the outreach. Yardstick fills it in from that sender's own scheduling link when it prepares the draft. This is not the interview scheduling link used in candidate interview emails — that one isn't available in Talent sequences. Each sender sets their own link under Profile → Personal scheduling URL. When you save a step that uses this variable, the builder checks whether you have a link set so you can catch a missing one early. If an email step uses {{sender_scheduling_link}} but the sender hasn't set a scheduling link, Yardstick pauses that step instead of sending a draft with a broken or missing link. Once the sender adds their link, the next run prepares the draft normally. When a supported value is missing, Yardstick uses a fallback so the draft still reads naturally: {{recipient_first_name}} and {{recipient_full_name}} become "there", {{company_name}} becomes "our team", {{role_title}} becomes "the role", {{source_label}} becomes "your profile", {{sender_full_name}} becomes "Recruiting Team", and {{sender_first_name}} becomes "Recruiting". Use Internal Note for review guidance that should sit beside a generated draft. It is shown beside generated drafts for human review, is not included in the email, and does not change auto-sent emails. Task steps create a task When a Task step comes due, Yardstick adds it to My Tasks for the assigned person — for example, "Call this prospect." Mark the task done when you've handled it, and the sequence advances to the next step. Reach out or Internal A task step in a talent sequence has a Task purpose, and it decides one thing: whether ticking the task off counts as having contacted the prospect. Reach out — the task is a touch with the person, like a call or a LinkedIn message. Marking it done updates that prospect's Last touch date, so they stop showing as having gone quiet. Internal — the task is your own work, like research or interview prep. Marking it done changes nothing about when you last contacted them. Pick whichever is true. Marking prep work as Reach out makes a prospect look freshly contacted when nobody has spoken to them. Two cases where there's nothing to pick: Email steps. The control is there but greyed out — sending an email always counts as reaching out. Sequences built inside an agency account. The control isn't shown at all. Those steps are work on the account itself rather than outreach to a person, so there's no prospect Last touch date for them to change. A task step starts as Reach out. If one is really internal work, open the sequence and change it. Discarding a draft stops the sequence If you Discard an email draft instead of sending it, that's a deliberate "stop" — discarding keeps the email in read-only history, prevents it from being sent, and ends the sequence for that prospect. Use Discard when you've decided not to keep reaching out. To pause one person without discarding, remove them from the sequence instead (see below). Auto-send: let later emails send on their own Auto-send lets a sequence send its later emails automatically, so you don't review every one. It's an admin choice and it's off until someone turns it on. A few rules keep it safe: The first email to each prospect is always approved by a person. Auto-send only applies to email steps after the first one. There's a daily limit. Each organization can auto-send a fixed number of emails per day. Past that, the rest wait for the next day. A bounce stops that prospect. If an auto-sent email bounces, Yardstick stops the sequence for that prospect so you don't keep mailing a dead address. Turn auto-send on Only an admin can change this. In a sequence's settings, turn on Auto-send follow-up emails. Yardstick asks you to confirm and reminds you it applies to everyone enrolled — current and future, not just newly enrolled prospects. A sequence needs at least two email steps for auto-send to do anything, since the first email is always reviewed by a person. Turn auto-send off There are two ways to stop automatic sending: Turn it off for the whole sequence. In the sequence's settings, switch Auto-send follow-up emails off. Later emails go back to waiting for your review, for everyone enrolled. Stop one prospect. Remove that prospect from the sequence (the Unenroll control on their profile's Sequences row). They stop receiving steps; everyone else continues. Agent note (ui-only) Outreach sequences, enrollment, and auto-send are operated through the Yardstick dashboard only — there is no API, CLI, or MCP for building sequences, enrolling prospects, approving drafts, or changing auto-send. The prospect activity timeline and follow-up scheduling in the prospects guide are the agent-operable surface. Prospects, pools, activity & follow-ups: /docs/product/talent-crm-prospects Common questions Will a prospect get several emails at once? No. Steps come due by day, so each email waits for its day to arrive — they don't stack up and fire together. I turned on auto-send but nothing sends automatically. Why? The first email to each prospect is always approved by a person, so a sequence with only one email step has nothing to auto-send. Add a second email step, and later emails will send on their own. A prospect's sequence stopped on its own. What happened? Two things stop a sequence for one prospect: an auto-sent email that bounced, or a draft someone discarded. Both are deliberate stops so you don't keep emailing the wrong person. Re-enroll them if you want to start again. How do I pause one person without ending it for everyone? Remove just that prospect from the sequence with Unenroll on their profile. The sequence keeps running for everyone else. Related Prospects, pools, activity & follow-ups — add prospects, log activity, and schedule follow-ups before or alongside a sequence. Need help? Email support@yardstick.team --- ## Team, admin, and departments URL: https://app.yardstick.team/docs/product/team-admin Summary: Manage org members, departments, roles, and organization settings. Settings starts with your personal profile at /settings, where every signed-in user can manage their own account. Team and organization administration lives in the admin pages under /admin. Owners and admins use those pages to manage the people who can sign into Yardstick, the departments they belong to, and the organization-wide settings that govern access. If you are setting up Yardstick for the first time, start with Set up your workspace. That guide explains the difference between creating your own workspace and joining one from an invitation. If you are not an owner or admin, the admin-only pages stay hidden. If you open an admin-only URL directly, Yardstick shows Access denied before the admin sidebar loads. Personal settings and API credential settings still open for signed-in users from their Settings routes and from older admin links. Admin portal Where this lives My Settings (/settings) — your personal profile and security. This is the global Settings landing page for every signed-in user. /profile and /admin/profile still open the same personal settings surface for existing links. API & agents (/settings/api-tokens) — create and manage your own API tokens and agent credentials. Owners and admins can also review organization-wide credential inventory. Older /admin/api-tokens links open the same page. Admin dashboard (/admin) — the overview: tiles for users, departments, pending invites, and active grants, a recent-activity feed, and quick actions for organization administration. Members (/admin/users) — every person in your org with their role and last sign-in. From here you invite people, change durable roles, manage department membership, set Job staffing, create access grants, and deactivate accounts, one at a time or in bulk. Departments (/admin/teams) — create departments, add or remove members, choose a department lead, and set the default hiring manager and recruiter for Jobs in that department. The page is a list of your departments on the left and the selected department's access settings on the right. Roles & permissions (/admin/roles) — a read-only table of the system roles and what each one can do across Jobs, candidates, scorecards, departments, and the rest. See Roles and what each can do. Invitations (/admin/invitations) — every pending invite, when it was sent, and who sent it. Resend, resend and copy a fresh link, or revoke from this table. Job access (/admin/job-access) — each Job with its hiring team and any access grants, so you can audit who can see a given hiring loop. Organization settings (/admin/organization) — your organization name, billing contact, and other org-wide values. Branding lives next door under Branding. This is separate from personal Settings at /settings. Integrations (/admin/integrations) — the provider connection hub for Google Workspace, Microsoft 365, email sending, and scheduling. Owners and admins use it to connect providers, reconnect accounts, review setup blockers, and open the detail page for each integration. See Google and Microsoft integrations for provider access, data boundaries, and deferred provider features. Departments Departments are how Yardstick decides who sees what. A Job belongs to a department, and a person sees a Job when they belong to its department — or when someone gives them a specific access grant for it. Set departments up to match how your hiring is actually organized, and most access takes care of itself. Department names and member rosters are organization-visible so people can find and administer the right department. Seeing that directory does not grant access to the department's Jobs, candidates, applications, interview records, or reports. A department name can reveal hiring intent, so avoid sensitive detail in department names. On the Departments page you can: Create a department. Use the New department row, give it a name, and save. Add or remove members. Pick people for the department; they immediately gain access to that department's Jobs. Choose a department lead. Promote one member to lead. The lead is responsible for department oversight. A department has at most one lead, so promoting a new lead steps the previous one back to member. Set department defaults. Pick the default hiring manager and recruiter that new Jobs in the department should start with. These are staffing defaults, not membership or lead status. You manage departments from the admin pages, and you can also automate department setup and membership through the API, CLI, and MCP surfaces (this needs department permissions on your credential — see CLI commands). Department defaults are dashboard-only today; the public Department commands manage department records, membership, lead assignment, and invitations, but they do not set default hiring managers or recruiters. Roles, department membership, staffing, and grants Yardstick uses five access terms in the dashboard. They overlap in the screens you use, but they do different jobs: Role assignment is durable capability. It says what someone can do across the organization, a department, or a Job, such as recruiter, department lead, hiring manager, or interviewer. Department membership says which departments someone belongs to. It gives department-scoped visibility and is separate from being the department lead. Department default says who new Jobs in a department should use as the starting hiring manager or recruiter. Changing a default does not rewrite existing Job staffing. Job staffing says who owns a specific Job as hiring manager or recruiter. A Job can use the department defaults when it is created, or an authorized admin/recruiter can set a Job override later. Access grant is a reasoned, revocable exception for one person and one resource, often with an expiry. It does not make the person a department member, recruiter, or hiring manager. Use department membership for people who should work across a department's hiring, Job staffing for the accountable hiring manager and recruiter on one Job, and access grants for narrow exceptions. Invite your team Start an invite from Invite people on the dashboard, or from the Members page. You can invite one person by email or upload a list to invite many at once. Each invite carries a starting role and scope; an admin can edit both until the person accepts. If someone already has access, Yardstick tells you they are already a member instead of sending another invite. If a matching invite is still pending, the invite drawer stays open with actions to resend, extend, or cancel the invite when your role allows it. Pending invites stay on the Invitations page until they are accepted, expire, or are revoked. Resend sends a fresh link, Resend and copy fresh link refreshes the invite before copying the URL for you to share directly, and Revoke cancels the invite and disables its link right away. Invites also expire on their own after a while, after which the person needs a new one. Roles and what each can do A person's role sets what they can do. Today there are two layers: Org membership decides admin reach. Every person is an Owner, Admin, or Member: Owner — full access, including billing and ownership. Only an owner can make someone else an owner, and an org always keeps at least one owner, so you cannot remove the last one. Admin — can manage members, departments, invitations, and organization settings, but cannot change an owner's role or assign the owner role. Member — works in Yardstick (Jobs, candidates, interviews) but does not see the admin pages and cannot change anyone's role. You cannot change your own role — that prevents you from locking yourself out. System roles describe what someone can do across each part of the product. The Roles & permissions page shows them in a read-only table: | Role | Reach | | --- | --- | | Admin | Manage everything across the org. | | Recruiter | Run hiring day to day — Jobs, applications, candidates, interviews, and scorecards. | | Department lead | Manage their own departments and the hiring within them. | | Hiring manager | Drive hiring on their own Jobs — applications, candidates, scorecards, and briefs. | | Interviewer | See their assigned Jobs and submit their own scorecards. | Each cell in the table reads Manage, Write, Read, or a dash: Manage means create, edit, delete, and grant access to others; Write means create and edit; Read means view only; a dash means no access. Hover any cell for the detail. For now this table is read-only — it shows the roles as they ship. Custom roles and editing a role's permissions one action at a time are planned for a later release, not available yet. Share one Job with an access grant Sometimes someone needs to see a single Job without joining its whole department — a panel interviewer brought in for one loop, say. An access grant does exactly that: it gives one person access to one Job, and you can set it to expire on its own so access does not linger. Review and manage grants on the Job access page, where each Job lists its hiring team and any grants attached to it. Access grants are also automatable through the API, CLI, and MCP surfaces with the right grant permissions on your credential. Common questions What's the difference between adding someone to a department and giving them an access grant? A department member sees every Job in that department, now and in the future. An access grant gives one person access to one Job. Use a department for someone who works across its hiring; use a grant for a one-off, especially with an expiry. Does making someone the department lead make them the default hiring manager? No. Department lead, default hiring manager, and default recruiter are separate settings. Set the department defaults explicitly if new Jobs should start with a specific hiring manager or recruiter. Who can change someone's role? Owners and admins. An admin can manage members but cannot change an owner's role or make someone an owner — only an owner can do that. No one can change their own role, and an org always keeps at least one owner. Can I create my own roles or fine-tune what a role can do? Not yet. The Roles & permissions page is read-only today and shows the roles as they ship. Custom roles and per-action editing are planned for a later release. Someone accepted their invite but can't see a Job. Why? Access follows departments. Check that they are a member of the Job's department, or give them an access grant for that specific Job. How do I remove someone's access? Take them out of the department to remove access to its Jobs, revoke any access grants they hold on the Job access page, or deactivate the account from the Members page to remove their access entirely. Troubleshooting The admin pages don't appear for me. The admin section is for owners and admins. Your personal Settings and API credentials can still open from Settings, but admin-only pages show Access denied if you open them directly. If you need admin access, ask an owner or admin in your org to update your role on the Members page. I can't change a teammate from owner to admin. You are likely the only owner — Yardstick won't let you remove the last one. Promote another person to owner first, then change the role. I can't assign the owner role. Only owners can assign the owner role. If you're an admin, an owner needs to make the change. An invite link isn't working. Invites expire, and revoking one disables its link immediately. On the Invitations page, Resend to issue a fresh link, or re-invite the person if the original was revoked. I resent an invite but the person didn't get an email. Yardstick still creates or refreshes the invite when email delivery isn't set up for your org. Use Resend and copy fresh link on the Invitations page and send the link to the person directly. Need help? Email support@yardstick.team can help if email delivery should be working but isn't. Related Set up your workspace — create your first workspace or join an existing one from an invitation. Jobs, applications, and candidates — what your team works on once they're in. CLI commands — automate departments, invitations, and access grants. Need help? Email support@yardstick.team --- ## Set up your workspace URL: https://app.yardstick.team/docs/product/workspace-setup Summary: Create your first Yardstick workspace or join one through an invitation. Your workspace is where your team keeps Jobs, candidates, interview plans, and settings. You need to create or join one before you can use Yardstick's signed-in product pages. Create your first workspace If your account does not belong to a workspace, Yardstick asks you to name one when you sign in. The same setup screen appears if you refresh, return later, or open a direct link to a signed-in product page. Enter the name your team uses for its organization. Select Create workspace. Wait while Yardstick finishes setup. You will continue to the page you originally opened when your workspace is ready. The setup screen has no skip option because Jobs and other product data need a workspace. You can select Sign out if you are not ready to continue. If Yardstick cannot create the workspace, correct the workspace name if prompted, then select Create workspace again. Your first successful creation is kept, so retrying does not create a second workspace. If Yardstick says it couldn't load your workspace, select Try again. This checks your workspace access again; it does not submit the workspace name. Join a workspace from an invitation An invitation joins you to someone else's existing workspace. Open the invite link and accept it instead of creating a new workspace. Once the invitation is accepted, Yardstick opens the invited workspace. If you opened Yardstick without the invite link and see the workspace naming screen, return to the invitation email and use its link. Ask the sender for a fresh invitation if the link expired or was revoked. Setup reminders Yardstick may email you if your verified account still has no workspace. The first reminder is eligible after 30 minutes and is normally processed by the next hourly check, within about 90 minutes of verification. If setup is still incomplete, a second reminder can follow three days after the first one was sent. Creating a workspace or accepting an invitation stops these reminders before the next email is sent. If you create the workspace, you may then receive the usual emails that help workspace creators get started. Invited teammates do not receive those creator-specific emails. The Unsubscribe link in a setup reminder stops both workspace-setup reminders and future emails that help you get started with Yardstick. It does not change emails sent to candidates. Troubleshooting The setup screen keeps appearing after I created a workspace. Sign out and back in once. If the setup screen still appears, contact support. I accepted an invitation but still see setup. Confirm that you used the latest invite link. An expired or revoked invitation does not add you to the workspace. Ask the sender to resend it if needed. I do not want to create a workspace. Select Sign out. Yardstick cannot open signed-in product pages until your account belongs to a workspace. Need help? Email support@yardstick.team