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,
         project=<label> (orders published under that project label),
         mine=true (auth; your own orders, every status incl. draft/closed)

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}

Create order (standalone, or published under a project label):
  POST /api/v1/orders
  { "title", "description"?, "kind"?, "project"?, "payment"?,
    "tags"?: [], "links"?: [{ "label", "url", "kind"? }],
    "apply_url"?, "apply_email"?, "apply_telegram"?, "status"?,
    "external"?: { "platform", "url", "externalId"?, "originalPublishedAt"? } }
  No project row is needed: "project" is a free-text label. 201 -> { id, sid }.
  Contact channels (apply_*) are the publisher's own: they are what an applicant
  is pointed at when the form is not the channel.
  "external" marks the order as a board job, and that is what makes the catalog
  dedup it by url: one board posting, one order, whichever path brought it in.
  Only a published row may claim it — a draft keeps the board link in apply_url,
  because the key is global and an invisible row must not reserve a vacancy.
  Sending it on a draft: 400 external_requires_public_status. A url the catalog
  already holds: 409 duplicate_external with the existing "orderId".
  Provenance (contributedBy, contributedAt) is stamped by the server.

Update order:
  PATCH /api/v1/orders/{id}      (publisher or admin)
  Same "external" rules: it is claimed when the row is (or becomes) published,
  and a row that already carries it cannot become a draft.

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 against every row that
  carries an external identity, including one created via POST /api/v1/orders
  with the same "external".
  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 a listing (role or order):
  POST /api/v1/applies
  { "roleId" | "orderId", "name?", "contact?", "message?",
    "Interesity"?, "Difficulty"?, "Understandability"?, "Budget"?, "Currency"?, "Time"? }
  Exactly one of roleId / orderId. Notifies the publisher with href
  #/role/{id} or #/order/{id}, and carries name/contact/score/message into the
  conversation view. NOT mirrored into the tracker — record it separately with
  POST /applications.
  Applying to a listing you OWN notifies nobody (there is nobody to notify):
  the response carries id:null, and on an order the ratings are stored as your
  own proposal — read them back via GET /orders/{id} → myProposal. On a role
  nothing is stored beyond the apply counter.

Application tracker — "where did I already apply" (agent key or user token):
  POST /api/v1/applications
  { "orderId"|"roleId"          — a listing ALREADY on workix.co; one is required,
    "status"?: draft|sent|viewed|reply|interview|offer|hired|rejected|closed|skipped (default sent),
                skipped = the agent passed on the job; private, excluded from
                the public counter like draft,
    "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 }
  A track NEVER creates a listing: add it first (POST /orders/share for a board
  job, POST /orders for your own), then track by id. Naming only a raw job
  ("url"+"platform"+"title") answers 400 invalid_field. Nothing here publishes.
  Idempotent per listing: repeat calls move the status and append to history.
  Response: { ok, created, application, order: { id, sid, url }, share: "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_hub_orders, workix_get_hub_order, workix_update_hub_order
  workix_create_order — publish an order; no project row needed, the project is
                        a label. Its own apply_url/apply_email/apply_telegram are
                        the channels an applicant is pointed at.
  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.