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
  - participants = people open to work, collaborate, or connect with mentors (API name: performers)
  - 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

TELEGRAM / TDLIB (OPTIONAL, LOCAL ONLY)
----------------------------------------
For Telegram channel search via local Workix MCP, users may use the Workix app credentials:
  https://workix.co/tgapi
  TG_APP_API_ID=2244247
  TG_APP_API_HASH=faa65a0a8de7edaf8d2393056c9c0c1c
They may also create their own app at https://my.telegram.org/apps; this is optional.
These are application identifiers, not Telegram account credentials. Phone numbers, login codes,
2FA passwords, and Telegram sessions must stay local and must never be sent to Workix or an agent chat.

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=<keywords>&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

Participants (API name: performers; legacy URLs keep performer):
  GET https://workix.co/api/v1/performers
  GET https://workix.co/api/v1/performers/{idOrSlug}
  Query: q, tags, collab, limit, lang (en|de|ru|zh|ja|ko|…)
  collab=networking|startups|opensource|equity (comma-separated → must match all) — keep only participants open ("yes") to those; also works on /search?scope=performers
  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).
  Participant CV PDF download (attachment application/pdf; body/headline follow lang; legacy URL keeps performer):
    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"?,
    "hidden"?: bool,  // true = hide card from feed/search/public page; false = public (default)
    "collab"?: { "networking"?, "startups"?, "opensource"?, "equity"?  // "yes"|"unknown"|"no"
                 "note"? } }
  POST /api/v1/profile/bump  → resurface card to top of participants list (list sorted by last update; any PATCH also bumps). Server limit: once every 3 days; earlier calls return HTTP 429 with Retry-After, retryAfterSec, and nextBumpAt.

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")
  Participant JSON (legacy URL): https://workix.co/performer/{id}.json
    e.g. https://workix.co/performer/6a676fd8513d0525120ef96e.json
  Participant vanity JSON: https://workix.co/{performerSlug}.json  (type:"performer"; legacy API type)
  Participant CV PDF: https://workix.co/performer/{id}/pdf?lang=en  (legacy URL)
    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 participant card via MCP workix_update_profile + vanity slug. It helps people find collaborators and mentors by skills and interests:
  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.