POST Build Request

Request a brand-new Wire action for a site that isn't in the catalog yet

POSThttps://api.openwire.sh/v1/wire/build-request

Request a brand-new action for a website that doesn't have one yet. Wire's builder generates a scraper from your goal, auto-tests it against the live site, and publishes it to the catalog on success. The call is asynchronous — it returns immediately with status: "pending". Credits are charged on submission and refunded automatically if the build fails.

Track progress by listing your build requests (GET /v1/wire/build-requests) or from the Wire dashboard. Once a request reaches success, run its action with POST /v1/wire/task.

Request Body

{
  "website_url": "https://example.com",
  "goal": "Extract product name, price, and availability from a product page"
}

Parameter	Type	Description
`website_url` required	string	The site to build an action for. The domain is extracted automatically (leading `www.` stripped)
`goal` required	string	Natural-language description of what the action should do or extract. Be specific — the builder synthesizes the scraper from this
`catalog_id`	string (UUID)	Attach the action to an existing catalog instead of creating one. Find IDs in GET /v1/wire/catalog
`visibility`	string	`"private"` (default) or `"public"`. Private actions are only visible to your account
`force`	boolean	Defaults to `false`. If similar actions already exist for the domain the request returns `409 ACTION_EXISTS`; set `true` to build anyway

Response

201 Created

{
  "status": "ok",
  "build_request": {
    "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "website_url": "https://example.com",
    "domain": "example.com",
    "goal": "Extract product name, price, and availability from a product page",
    "visibility": "private",
    "status": "pending",
    "credits_charged": 25,
    "created_at": "2026-05-28T12:00:00Z",
    "updated_at": "2026-05-28T12:00:00Z"
  }
}

Field	Type	Description
`id`	string (UUID)	The build request ID — use it to track the build
`status`	string	Starts at `pending`, then ends at `success` (action is live) or `failed` (credits refunded)
`credits_charged`	integer	Credits held for this build. Refunded if it fails
`action_id`	string	Present once published — pass it to POST /v1/wire/task
`error`, `error_type`	string	Populated when `status` is `failed`

Error Responses

Code	HTTP	When
`INVALID_INPUT`	400	`website_url` or `goal` missing, `website_url` malformed, or `visibility` isn't `private`/`public`
`BLOCKED_WEBSITE`	400	The site isn't supported for scraping
`INSUFFICIENT_CREDITS`	402	Your balance can't cover the build cost. Response includes `balance` and `required`
`ACTION_EXISTS`	409	Similar actions already exist for this domain. Response includes `existing_actions`; set `force: true` to proceed
`BUILD_LIMIT_REACHED`	429	Too many pending build requests (max 3). Wait for one to finish
`INTERNAL_ERROR`	500	Failed to create the build request. Any charged credits are refunded

Action exists — 409 Conflict

{
  "status": "error",
  "error": {
    "code": "ACTION_EXISTS",
    "message": "Similar actions already exist for this website. Set force=true to proceed anyway.",
    "existing_actions": [
      {
        "action_id": "example_com_product_detail",
        "name": "Product Detail",
        "description": "Extract product name, price, and availability"
      }
    ]
  }
}

Code Examples

curl -X POST https://api.openwire.sh/v1/wire/build-request \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "website_url": "https://example.com",
    "goal": "Extract product name, price, and availability from a product page"
  }'

import requests

response = requests.post(
    'https://api.openwire.sh/v1/wire/build-request',
    headers={'X-API-Key': 'your_api_key'},
    json={
        'website_url': 'https://example.com',
        'goal': 'Extract product name, price, and availability from a product page'
    }
)

data = response.json()
print(f"Build request: {data['build_request']['id']} ({data['build_request']['status']})")

const response = await fetch('https://api.openwire.sh/v1/wire/build-request', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    website_url: 'https://example.com',
    goal: 'Extract product name, price, and availability from a product page'
  })
});

const { build_request } = await response.json();
console.log('Build request:', build_request.id, build_request.status);

Rate limit

20 requests per minute per user. Each build request costs credits (currently 25), refunded automatically if the build fails.