Wayfern
Start building Sign in

Operations quickstart: learn, create and call

Turn a public page into a JSON API: learn it from two examples, save the operation, and call it from the dashboard, the REST API or the five MCP tools.

Updated

An operation is a saved read of a public page. You give Wayfern a page URL with a placeholder where the input goes, plus two example values. Wayfern finds the request the page makes for its data and saves it as a versioned template. After that, one call with new arguments returns the data as JSON. This guide shows the three steps from the dashboard, the REST API and MCP.

Before you start

  • You need a project. Every member of the project can learn, create and call its operations. The project owner is billed.
  • For REST, use an API token with the web scope. For MCP, use a token with the mcp scope.
  • Find the project id in the URL of the project page in the dashboard: /projects/PROJECT_ID.
  • The page must be readable by a signed-out visitor. Wayfern refuses login walls, write requests, private addresses and pages whose robots.txt does not allow WayfernBot. It removes cookie and authorization values from the learned request.

In the dashboard

Open Operations and select New operation. The wizard has five steps: Page, Learning, Candidates, Fields, and Test and save. In the last step, Wayfern saves the operation and calls it with a new value so you see the result.

With the REST API

1. Learn the page

Put each parameter in the trigger URL as {name}, and give two different examples for each. A parameter name starts with a letter or an underscore and has up to 32 characters.

curl -X POST https://api.wayfern.com/api/v1/projects/$PROJECT_ID/operations/learn \
  --max-time 180 \
  -H "Authorization: Bearer $WAYFERN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger": { "url": "https://shop.example/search?q={query}" },
    "params": [{ "name": "query", "type": "string", "examples": ["desk lamp", "office chair"] }],
    "options": { "proxy": "auto" }
  }'

Learning loads the page 3 times: with example 1, with example 2, and with example 1 again as a new visitor. It takes tens of seconds and stops after 60 seconds in total. The answer is 201 with a learnId and up to 5 ranked candidates. Each candidate shows its request, where the examples sit, the proposed fields with sample values and the lowest tier it can use.

Learning costs 3 credits when it returns candidates and nothing when it does not. The draft is kept for 30 minutes. Read it again for free with GET .../operations/learn/LEARN_ID.

2. Create the operation

Send the learnId with "auto": true to take the best candidate as it is. Or send candidateId, a slug, a name and the fields you want to keep.

curl -X POST https://api.wayfern.com/api/v1/projects/$PROJECT_ID/operations \
  --max-time 180 \
  -H "Authorization: Bearer $WAYFERN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "learnId": "lrn_4kQ9w2Zc", "auto": true }'

Before it saves, the server replays example 2 and example 1. It refuses a bot wall, a login page or output that does not match the fields. The answer is 201 with the operation and its id. Creating is free.

3. Call it

curl -X POST https://api.wayfern.com/api/v1/operations/op_7Hx2mP/call \
  --max-time 180 \
  -H "Authorization: Bearer $WAYFERN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "args": { "query": "standing desk" }, "options": { "maxTier": 2 } }'
{
  "success": true,
  "data": {
    "result": [
      { "title": "Oak standing desk", "price": 389 },
      { "title": "Standing desk frame", "price": 219.5 }
    ],
    "tier": 1,
    "cached": false,
    "version": 1,
    "ms": 640,
    "truncated": false
  },
  "credits": 1
}

options can set maxTier, proxy, country and cacheTtlSeconds. A call costs 1 credit when it answers with data or with an empty result, cache hits included. A failed call is free. Its error body has a reason, such as blocked, rate or drift, and a next hint. REST output above 1 MB is cut, and truncated is true.

With MCP

The Wayfern MCP server has five operation tools. Arguments use snake case.

ToolCostWhat it does
list_operationsFreeThe operations of your projects, or of one project_id
describe_operationFreeParameters with examples, output fields and the output schema
learn_operation3 credits when it finds candidatesproject_id, trigger_url and params with two examples each
create_operationFreeproject_id, learn_id, and candidate_id or auto: true
call_operation1 credit per call that answersoperation_id, args, and optional max_tier, proxy, country, cache_ttl_seconds
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_operation",
    "arguments": { "operation_id": "op_7Hx2mP", "args": { "query": "standing desk" } }
  }
}

Lists come back as columns and rows, up to 20,000 characters. To add Wayfern to an agent, see Connect an agent.

Limits

An operation has up to 10 parameters and a trigger URL of up to 2,048 characters. A project has up to 200 operations. Per minute, learn allows 10 requests, create 20 and call 600. Calls to one site are spaced to 2 a second per project. See Operations for every endpoint, and Operation versions and health for what happens when the site changes.

Related guides