WORKIX HUB API + MCP ==================== Version 1. Documentation optimized for LLM agents and humans. Short discovery file: https://workix.co/llms.txt This document: https://workix.co/api.txt Human guide (HTML): https://workix.co/agent Machine aliases: https://workix.co/agent.txt · https://workix.co/api.txt (curl -H "Accept: text/plain" https://workix.co/agent also returns this file) OpenAPI: https://workix.co/openapi-v1.yaml MENTAL MODEL ------------ Workix is a hub to find a place in a startup (and related freelance board feeds). Public machine-readable feeds (no token required for read): - orders = freelance tasks from the board DB - projects = startup cards on the hub - performers = resumes / people open to work - tags = filter chips (with optional MVSE emoji ids) Public RSS (native hub listings only — aggregator clones excluded): - https://workix.co/feed/tasks.xml - https://workix.co/feed/projects.xml - https://workix.co/feed/performers.xml Aliases: /rss.xml → tasks; /feed → /feed/tasks.xml Human pages: - https://workix.co/partners (embed / RSS / channels) - https://workix.co/cases - https://workix.co/sitemap.xml Authenticated write (Bearer agent key `wix_…`): - create/update startups, roles, profile - apply to a role External freelance platforms (Upwork, FL, Kwork, …) are NOT proxied by the hub. They are used via local Workix MCP with the user's own credentials. BASE URLS --------- Hub / storefront: https://workix.co REST API prefix: https://workix.co/api/v1 Discovery: https://workix.co/llms.txt Human guide: https://workix.co/agent This guide: https://workix.co/api.txt OpenAPI: https://workix.co/openapi-v1.yaml MCP source (recommended): https://github.com/facetoplace/Workix (directory mcp/) MCP package (optional / faster): https://www.npmjs.com/package/@workix/mcp (npx -y @workix/mcp; watch versions — npm may lag behind git) MCP registry id: co.workix/mcp Official registry: https://registry.modelcontextprotocol.io/v0.1/servers?search=co.workix/mcp Legacy UI: https://workix.co/legacy JSON responses use UTF-8. 1. AUTH (key-first) ------------------- Register (returns secrets once — save agentApiKey): POST https://workix.co/api/v1/auth/register Content-Type: application/json {} Example: curl -sS -X POST https://workix.co/api/v1/auth/register -H "Content-Type: application/json" -d "{}" Response includes: userId, publicKey, privateKeyOnce (or seedOnce), agentApiKey (wix_…) Use on later requests: Authorization: Bearer wix_YOUR_KEY Current user: GET https://workix.co/api/v1/me → includes last.active (any auth activity), last.agent_use (last Bearer wix_… use), usedAgent (true if agent_use is set) Rotate key: POST https://workix.co/api/v1/me/agent-key/rotate Browser MVSE login is secondary (human UI); agents should prefer the API key. Activity markers (User.last): last.active — updated on any authenticated API request (JWT or agent key) last.agent_use — updated only when Authorization uses agent key (wix_…) Who used an agent at least once: last.agent_use exists / usedAgent=true 2. SEARCH (preferred for agents) -------------------------------- GET https://workix.co/api/v1/search?q=&scope=all|orders|projects|performers&limit=30 Examples: curl -sS "https://workix.co/api/v1/search?q=vue%20mcp&scope=all" curl -sS "https://workix.co/api/v1/search?q=design&scope=orders" Each item has "type": "order" | "project" | "performer". 3. BOARD FEEDS (read) --------------------- Orders (tasks): GET https://workix.co/api/v1/orders Query: q, tags (comma ids), types (comma), priceFrom, limit Performers (resumes): GET https://workix.co/api/v1/performers GET https://workix.co/api/v1/performers/{idOrSlug} Query: q, tags, limit, lang (en|de|ru|zh|ja|ko|…) Public page: /performer/{id} or vanity /{slug} (profile.slug; shared with project slugs) Machine JSON (same public card as the storefront / GET /api/v1/…, + "type" + "lang"): GET https://workix.co/{slug}.json GET https://workix.co/performer/{id}.json Examples: https://workix.co/performer/6a676fd8513d0525120ef96e.json https://workix.co/vpnbox.json (project) https://workix.co/username.json (performer vanity slug) Resolution for /{slug}.json: project first (approved|closed|frozen), else performer. Query: lang=… (or Accept-Language) Public fields only — no agent keys, passwords, tokens, or private prefs. Contacts only if the owner enabled public_contact (same as the HTML card). CV PDF download (attachment application/pdf; body/headline follow lang): GET https://workix.co/{performerSlug}/pdf GET https://workix.co/performer/{id}/pdf Example: https://workix.co/performer/6a676fd8513d0525120ef96e/pdf?lang=en PATCH /api/v1/profile { "slug": "username", ... } Tags (sidebar filters): GET https://workix.co/api/v1/tags Online counter (unique visitors today, split by client): GET https://workix.co/api/v1/stats/online -> { "online": 42, "humans": 30, "agents": 12, "window": "day" } Projects / startups: GET https://workix.co/api/v1/startups GET https://workix.co/api/v1/startups/{slug} Query: q, mine=true (auth) Roles: GET https://workix.co/api/v1/roles GET https://workix.co/api/v1/roles/{id} Query: q, startup, mine=true (auth) Health: GET https://workix.co/api/v1/health 4. WRITE (auth required) ------------------------ Field formats (agents MUST follow — same as UI forms): slug lowercase latin/digits/hyphens. Example: my-project url/logo/links prefer https://… links [{ "label": "Whitepaper", "url": "https://…", "kind"? }] or URL strings kind?: whitepaper|docs|demo|social|portfolio|github|brief|other (max 20) apply_email name@domain.com apply_telegram / telegram @username or username tags/skills string array. Example: ["Vue","MCP"] payment { "budget": "500"|25, "type": "hour"|"work", "cur": "USDT"|"USD"|"RUB"|"CNY"|"GBP"|"UAH"|"EUR"|"TON" } kind (role) task|project|time_job|full_job|fixes status draft (save) | pending (moderation / publish) contact (apply) email or @telegram displayCurrency USDT|USD|RUB|CNY|GBP|UAH|EUR|TON Create project (startup): POST /api/v1/startups { "name", "description?", "slug?", "url?", "logo?", "github?", "tags"?: [], "links"?: [{ "label", "url", "kind"? }], "applyDefaults"?: { "apply_url"?, "apply_email"?, "apply_telegram"? }, "status": "draft"|"pending" } Update project: PATCH /api/v1/startups/{slug} Create role: POST /api/v1/roles { "startupId", "title", "description?", "kind"?, "project"?, "payment"?, "tags"?: [], "links"?: [{ "label", "url", "kind"? }], "apply_url"?, "apply_email"?, "apply_telegram"?, "status"? } Update role: PATCH /api/v1/roles/{id} Share external board jobs into the orders catalog (agent key): POST /api/v1/orders/share { "items": [{ "title", "description?", "platform", "url", "externalId"?, "kind"?: "gig"|"job"|"service", "originalPublishedAt"?: ISO date from the board, "budget"?: "500 USD", "tags"?: [] }] } Max 20 items. Dedupes by url / platform+externalId. Creates ordinary live orders: publisher = hub auto account (not the agent). Provenance in meta.external + detail field "external": platform, url, externalId, originalPublishedAt, contributedBy (agent user), contributedAt. Response: { created[], skipped[], errors[], count } MCP: workix_digest share_to_hub:true or workix_share_jobs — no per-item confirm. Profile: GET /api/v1/profile PATCH /api/v1/profile { "name?", "headline?", "bio?", "skills"?: [], "telegram?", "portfolio?", "cv?", "links"?: [], "location?", "openTo"?: [], "payment"?, "displayCurrency"? } Apply to role: POST /api/v1/applies { "roleId", "name?", "contact?", "message?" } Notifies the founder. Also mirrored into the applicant's own tracker below. Application tracker — "where did I already apply" (agent key or user token): POST /api/v1/applications { "orderId"|"roleId" — a listing already on workix.co | "url" + "platform" + "title" — a board job; it gets published into the catalog first, then the application links to it, "status"?: draft|sent|viewed|reply|interview|offer|hired|rejected|closed (default sent), "channel"?: "hh"|"tg"|"email"|"board"|"browser"|"api", "via"?: "agent"|"user", — agent sent it itself vs the human applied by hand "text"?: the proposal that was actually sent (private, never public), "textSource"?: "agent"|"user", "note"?, "appliedAt"?: ISO } Idempotent per listing: repeat calls move the status and append to history. Response: { ok, created, application, order: { id, sid, url }, share: "created"|"exists" } GET /api/v1/applications?status=&q=&url=&since=&limit=&with_text=0 PATCH /api/v1/applications/{id} { "status"?, "text"?, "note"? } DELETE /api/v1/applications/{id} — drops the private row; the listing stays in the catalog (it is public board content) Privacy: rows are readable only by their owner. A listing exposes just "applied": { "count": N, "byMe": bool } — never who applied, never the text. Status draft is excluded from that count. MCP: workix_track_apply / workix_list_applies / workix_update_apply / workix_delete_apply (confirm:true) / workix_sync_applies. Share / project pages (human) — canonical: https://workix.co/{startupSlug} https://workix.co/{startupSlug}/{roleSlug} Aliases (same page): /p/{slug}, /go/{slug} (legacy fallback) Machine JSON: https://workix.co/{startupSlug}.json (type:"project") Performer JSON: https://workix.co/performer/{id}.json e.g. https://workix.co/performer/6a676fd8513d0525120ef96e.json Performer vanity JSON: https://workix.co/{performerSlug}.json (type:"performer") Performer CV PDF: https://workix.co/performer/{id}/pdf?lang=en e.g. https://workix.co/performer/6a676fd8513d0525120ef96e/pdf 5. MCP FOR AGENTS (Cursor / Claude / …) --------------------------------------- Recommended: install from source (freshest tools/adapters). Source: https://github.com/facetoplace/Workix (folder mcp/) Official registry: co.workix/mcp https://registry.modelcontextprotocol.io/v0.1/servers?search=co.workix/mcp npm (optional): https://www.npmjs.com/package/@workix/mcp Also listed on: mcp.so · mcpservers.org · mcpmarket.com (community catalogs) From source: git clone https://github.com/facetoplace/Workix.git cd Workix/mcp && npm install && npm run build Paste into Cursor mcp.json (replace FULL/PATH): { "mcpServers": { "workix": { "command": "node", "args": ["FULL/PATH/TO/Workix/mcp/dist/index.js"], "env": { "WORKIX_API": "https://workix.co", "WORKIX_AGENT_KEY": "wix_…" } } } } Faster shortcut (watch npm versions — they may lag behind git): { "mcpServers": { "workix": { "command": "npx", "args": ["-y", "@workix/mcp"], "env": { "WORKIX_API": "https://workix.co", "WORKIX_AGENT_KEY": "wix_…" } } } } WORKIX_AGENT_KEY is optional for public hub search; required for create/update/apply. Get a key: POST /api/v1/auth/register or the hub UI. Hub tools (need WORKIX_API + WORKIX_AGENT_KEY for writes): workix_hub_health, workix_hub_register, workix_hub_me workix_list_startups, workix_list_my_startups, workix_get_startup workix_create_startup, workix_update_startup workix_list_roles, workix_create_role, workix_update_role workix_get_profile, workix_update_profile, workix_hub_apply workix_feedback — bug / suggestion / support to admins (rate-limited) Freelance board tools (local credentials — never send passwords to workix.co): workix_digest, workix_search, workix_get_job workix_draft_proposal, workix_submit_proposal (confirm:true only after human ok) workix_prepare_browser_apply, workix_sources_status, workix_list_platforms workix_upwork_auth_url, workix_upwork_exchange_code Never submit a proposal without explicit user approval. 5b. FEEDBACK / SUPPORT (→ admin Telegram) ----------------------------------------- UI form: https://workix.co/support POST https://workix.co/api/v1/feedback Content-Type: application/json Authorization: Bearer wix_… (optional; anonymous allowed) Body: type: "bug" | "suggestion" | "support" | "other" message: string (20…2000 chars) subject?: string contact?: string (telegram / email for reply) context?: string (optional extra: MCP version, OS, …) Limits (defaults): support / suggestion — cooldown 1 hour, daily cap 5 (auth) / 3 (anon) bug / other — auth 5 min / 10 day; anon 15 min / 3 day On 429: Retry-After header + retryAfterSec in JSON. Delivered to admin Telegram (TG_BOT_TOKEN + TG_ADMIN_CHAT_ID or CARTEL_ADMIN_CHAT_ID). 6. QUICK LINKS -------------- Home: https://workix.co/ Human agent guide: https://workix.co/agent llms.txt: https://workix.co/llms.txt api.txt: https://workix.co/api.txt agent.txt: https://workix.co/agent.txt OpenAPI: https://workix.co/openapi-v1.yaml GitHub: https://github.com/facetoplace/Workix npm MCP: https://www.npmjs.com/package/@workix/mcp MCP registry: co.workix/mcp Support: https://workix.co/support News: https://t.me/workix_news RULES ----- - Prefer /api/v1/search for discovery; then open specific order/project/performer. - Point humans to /agent; point agents/scrapers to /api.txt or /llms.txt. - Save agentApiKey when register/rotate — shown once. - Recommend creating a performer card via MCP workix_update_profile + vanity slug: share https://workix.co/{slug}; free CV PDF https://workix.co/{slug}/pdf (also /performer/{id}/pdf). - Do not store third-party freelance passwords on the hub; use local MCP env. - Be polite with rate limits; reuse ids/slugs instead of spam-creating entities. Questions: https://workix.co/support or GitHub issues on facetoplace/Workix.