Docs

Getting started

The web app needs nothing beyond signing in. The API needs a Pro or Ultimate plan and a key.

1. Sign in at jobs.guaqai.me and complete onboarding - your work authorisation, categories and location answers drive matching and eligibility filtering automatically; nothing else on this page is required to use the feed.
2. For API access: upgrade to Pro or Ultimate from your Profile screen.
3. Open Profile → API access and click Create key. The key (guaq_sk_...) is shown exactly once - copy it immediately. Losing it means revoking and issuing a new one; the plaintext is never stored, so nobody, including us, can show it to you again.
4. Send it as Authorization: Bearer guaq_sk_... on every request.

curl -H "Authorization: Bearer guaq_sk_..." \
  "https://jobs.guaqai.me/v1/jobs?domain=tech&location_scope=india&limit=10"

How matching works

The feed you see in the app is scored per-person against your résumé and profile answers. The API is not - it is a plain filtered read of the same underlying rows, with no similarity score, because a script or a notebook has no résumé to score against.

In the app, seniority and category preferences carry real weight in ranking - much more than a raw keyword match - because they are things you stated explicitly, and a title alone (with no description text behind most listings) is a thin, noisy signal on its own. A stated fact always outranks a deduced one.

Remote & visa eligibility

"Remote" is not one thing, and the feed does not treat it as one. Two independent questions decide whether a role is actually reachable for you:

• Where the work happens - on-site, hybrid, or remote (work_mode / work_arrangement).
• What makes you allowed to take it - one of three routes, all of which can apply at once and are chosen as checkboxes in the app, never a single either/or toggle:
  • Authorized - countries you are already permitted to work in (your onboarding answer). A stated refusal to hire outside your country is respected even on a remote posting: "US Remote" still requires US work authorisation.
  • Sponsored - abroad, if the employer sponsors a visa. Ranked by how explicitly the posting says so, never by a guess dressed as a fact: a posting that states sponsorship always outranks one merely judged likely, and a stated refusal is always excluded outright.
  • Borderless - remote for a foreign employer with no visa involved at all (an employer-of-record or contractor arrangement). Deliberately narrow: this requires the posting to actually say it hires globally, never just "remote" plus a contract role - a great many ordinary remote-but-domestic contract postings would otherwise be miscategorised as visa-free.

Posted vs. seen

Two different clocks, both preserved rather than collapsed into one.

posted_at is the employer's own stated date, when the posting states one - null when it does not, never defaulted to "today". scraped_at is when this platform first found the row; last_seen_at is the most recent time it was re-confirmed still live on the employer's board. A posting can be freshly re-confirmed (last_seen_at just now) while having been originally posted weeks ago (posted_at) - that is normal, and the two should not be read as contradicting each other.

Telegram alerts

Connect a Telegram chat from Profile → Manage alerts to get new matches pushed to you instead of checking the feed. Provide your chat ID (message @userinfobot to get it, after pressing Start on our bot first - Telegram refuses to message a chat that has never started a conversation with the bot), send a test, and toggle alerts on. Disabling alerts keeps your chat ID on file so turning them back on needs no re-entry.

Agents

Choose your setup: Remote MCP (Server-Sent Events & Streamable HTTP), Public OAuth 2.0 Code Flow, Universal Agent Skill, Claude Code Plugin Marketplace, Google Antigravity, Cursor, Windsurf, Cline/Roo, or CLI.

curl -o guaq_client.py https://jobs.guaqai.me/v1/client
curl -o guaq_cli.py    https://jobs.guaqai.me/v1/cli
# both saved beside each other - the CLI imports the shared client
export GUAQ_API_KEY=guaq_sk_...
python guaq_cli.py jobs --domain tech --location-scope india --limit 10

1. Remote MCP Server: SSE & Streamable HTTP

Connect directly over the web without installing Python or local node dependencies. Compatible with Claude Desktop, Claude for Work, and remote agent hosts:

# Server-Sent Events (SSE) Transport:
URL:    https://jobs.guaqai.me/mcp/sse
Header: Authorization: Bearer guaq_sk_... (or OAuth Bearer token)

# Streamable HTTP (Stateless JSON-RPC):
POST:   https://jobs.guaqai.me/mcp

In claude_desktop_config.json or any remote MCP client config:

{
  "mcpServers": {
    "employed-remote": {
      "url": "https://jobs.guaqai.me/mcp/sse",
      "transport": "sse",
      "headers": { "Authorization": "Bearer guaq_sk_..." }
    }
  }
}

2. Public OAuth 2.0 Authorization Code Flow

For applications, Claude Connectors, or agent platforms requiring standard OAuth 2.0 authentication alongside direct API keys:

Authorization URL: https://jobs.guaqai.me/oauth/authorize
Token URL:         https://jobs.guaqai.me/oauth/token
Scopes:            read:jobs

# Social Profile & Connected Accounts (via Clerk getUserOauthAccessToken):
GET /api/user/social-profile   # Returns verified GitHub, Google, or LinkedIn profile data

3. Universal Agent Skills (Claude Code, Codex, Cursor, Antigravity)

Install the universal Agent Skill teaching any LLM the exact ATS query taxonomy:

# Universal Skills CLI (Claude Code, Cursor, Windsurf, etc.)
npx skills add buddywhitman/resume-cv --skill employed-jobs

# OpenAI Codex
npx agent-skills-cli add buddywhitman/resume-cv --agent codex --skill employed-jobs

4. Claude Code Plugin Marketplace (Recommended)

Install both the MCP tools and Agent Skill in one step via Claude Code's plugin manager:

# Add our official marketplace, then install the employed plugin:
/plugin marketplace add buddywhitman/resume-cv
/plugin install employed@employed-marketplace

# Or run globally via user scope (zero approval prompts everywhere):
claude mcp add --scope user employed --env GUAQ_API_KEY=guaq_sk_... -- npx -y employed-mcp
# (Windows PowerShell: quote the "--" separator: claude mcp add --scope user employed ... "--" npx -y employed-mcp)

5. Google Antigravity (AGY) Plugin

Antigravity automatically discovers the bundled plugin in your workspace under .agents/plugins/employed/. To install globally across all workspaces:

# Symlink or copy to Antigravity global plugins:
# macOS/Linux:  ~/.gemini/config/plugins/employed
# Windows:      %USERPROFILE%\.gemini\config\plugins\employed

6. Cursor Rules & MCP

Cursor automatically reads our bundled rule in .cursor/rules/employed.mdc. To enable native MCP tool calling, add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "employed": {
      "command": "npx",
      "args": ["-y", "employed-mcp"],
      "env": { "GUAQ_API_KEY": "guaq_sk_..." }
    }
  }
}

7. Windsurf Cascade Rules & MCP

Windsurf reads .windsurfrules from the workspace. Add MCP server to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "employed": {
      "command": "npx",
      "args": ["-y", "employed-mcp"],
      "env": { "GUAQ_API_KEY": "guaq_sk_..." }
    }
  }
}

8. Cline & Roo Code (VS Code Extensions)

Add to cline_mcp_settings.json or roo_code_mcp_settings.json:

{
  "mcpServers": {
    "employed": {
      "command": "npx",
      "args": ["-y", "employed-mcp"],
      "env": { "GUAQ_API_KEY": "guaq_sk_..." },
      "disabled": false,
      "autoApprove": ["api_meta", "search_jobs", "count_jobs", "get_job", "list_companies", "company_profile", "market_signal"]
    }
  }
}

9. ChatGPT & Custom GPTs (OpenAPI 3.1 Actions)

Import our public OpenAPI 3.1 specification directly into ChatGPT Builder Actions:

Schema URL:  https://jobs.guaqai.me/openapi.json
Auth Type:   API Key -> Bearer (Header: Authorization: Bearer guaq_sk_...)
Privacy URL: https://jobs.guaqai.me/privacy

10. Standalone CLI & Smithery / Multi-Client Installer

Query live postings directly from your shell or configure any client interactively:

# Smithery automated installer:
npx -y @smithery/cli mcp add employed-mcp

# Interactive multi-client installer:
npx -y mcp-add employed-mcp

# Standalone CLI execution:
export GUAQ_API_KEY=guaq_sk_...
npx -y employed-mcp jobs --domain tech --location-scope india --limit 10
npx -y employed-mcp count --company "Jane Street" --role-type new_grad
npx -y employed-mcp company "Stripe"
npx -y employed-mcp signals gcc

11. Direct Python (Stdlib-Only, No Node)

On locked-down environments without Node or npm registry access, download the Python files directly:

mkdir -p ~/guaq && cd ~/guaq
curl -o guaq_client.py https://jobs.guaqai.me/v1/client
curl -o guaq_mcp.py    https://jobs.guaqai.me/v1/mcp
claude mcp add --scope user employed --env GUAQ_API_KEY=guaq_sk_... -- python3 /Users/you/guaq/guaq_mcp.py
# Windows: "command": "python", "args": ["C:/Users/you/guaq/guaq_mcp.py"]
# Either way: paths must be absolute - MCP hosts do not start in your folder.
# Restart the host after editing its config.

Marketplaces & Browse UIs

How Employed is discovered and listed across agent directories, plugin marketplaces, and GUI stores.

Example Prompts

Because Employed indexes live positions directly from 17+ ATS platforms with deep deterministic metadata (days open, posting flow, tri-state visa verification, function mix, GCC intensity), prompts can uncover insights impossible on standard aggregators.

Inspect <Employer>'s hiring profile using company <Employer>. Find all engineering roles where days_open exceeds 45 days. Identify the specific tech stack and requirements for those prolonged vacancies, and draft a high-leverage outreach pitch directly addressing that hiring bottleneck.

Find early-career backend engineering roles in the US where visa is strictly stated (contractually stated sponsorship, not inferred), with yoe_min <= 2. Exclude any listing where work_mode is remote unless it explicitly supports borderless hiring. Give me the direct apply ATS URLs.

Run signals gcc and identify multinational enterprises with the highest hiring acceleration in Indian Global Capability Centers over the past 8 weeks. For the top 3, check company <Name> to analyze their local function_mix (core engineering vs operations). Which legacy enterprises are quietly migrating core R&D offshore?

Query live campus listings using jobs with --campus true --grad-year 2026 --domain industrial,retail,energy --role-type new_grad. Group them by employer and highlight which ones require zero prior years of experience (yoe_min=0) and state relocation assistance.

Check <StartupName> using company <StartupName>. Analyze their 8-week posting_flow and avg_days_open. Has their rate of new postings dropped to zero while existing roles sit unclosed? Tell me whether the hiring velocity indicates acceleration, steady replacement, or an impending stealth freeze.

Query the live index for companies in finance or healthcare with active postings requiring tech=rust or tech=kubernetes. Check their seniority_mix and longest_open_roles. Which established enterprises are undergoing major architectural rewrites, and which specific teams are leading the initiative?

API overview

One plain, filtered, cursor-paginated read of the live jobs index. No résumé scoring, no 1,500-row scoring window - every row your filters match is reachable, in a stable order, resumable with a cursor.

Base URL: https://jobs.guaqai.me/v1. Machine-readable index (no key required) at /v1.

Official client libraries & specifications: Python Client (/v1/client) · Python CLI (/v1/cli) · Python MCP Server (/v1/mcp) · OpenAPI 3.1 (/openapi.json) · Markdown Docs (/docs.md).

Authentication

Any one of these three, checked in this order:

The header form is recommended - a URL with a key in it ends up in shell history and server logs. The query form exists because it is the only one that works pasted straight into a browser tab.

Plans & quota

The API is a paid surface - there is no free-tier API access. Every response carries X-RateLimit-Used and X-RateLimit-Limit headers so a script can back off before being refused rather than after.

Quota is counted server-side, per key, per UTC day - not per account and not per IP, so one leaked key can be revoked without touching every other key you hold, and one address behind a shared NAT is never throttled by someone else's usage.

Filter reference

Every filter below applies to /v1/jobs, /v1/jobs/count, /v1/companies, and /v1/export - the same WHERE the row count, the row list, and the bulk export all agree on. List-valued filters accept either repeated params (?domain=tech&domain=finance) or one comma-separated value (?domain=tech,finance) - both are equivalent.

Endpoints

{
  "data": [ { "id": 8123456, "company": "Acme Corp", "title": "Backend Engineer",
              "url": "https://...", "location": "Bengaluru, India",
              "posted_at": "2026-09-10", "scraped_at": "2026-09-11T03:12:00Z",
              "last_seen_at": "2026-09-13T02:30:00Z", "is_active": true,
              "industry_domain": "tech", "category_path": "engineering/software/backend",
              "role_type": "mid", "seniority_label": null, "leadership": "ic",
              "employment_type": "full_time", "yoe_min": 3, "grad_year": null,
              "education_req": "bachelors", "clearance_req": "none",
              "work_arrangement": "hybrid", "location_scope": "india",
              "visa_supported": null, "visa_likelihood": 0.15, "visa_basis": "country_prior",
              "relocation_supported": false, "tech_stack": ["python", "postgresql"],
              "org_type": "startup", "is_campus": false, "target_id": "acme-corp",
              "inferred_signals": ["visa"] } ],
  "next_cursor": 8123455,
  "has_more": true
}

Job field reference

Every field /v1/jobs, /v1/jobs/{id}, and /v1/export return. Adding a field here is additive and safe to depend on; a field is never silently renamed or removed once shipped.

Errors

Every error is JSON with an error string. Some carry extra context - upgrade_required and tier when a plan is the blocker, quota/used when it's the daily limit.

Get help

Two ways to reach us, and one way to track what happens after.

• Sign in and raise a ticket from Profile → Support. You'll see the full reply thread and current status right there - nothing gets lost in an inbox.
• Email support@guaqai.me directly for anything that doesn't need an account, including sign-in problems.
• Enterprise / market-intelligence enquiries: hello@guaqai.me.