Create default smart workflow (no benchmark)

POST

/api/v1/workflows/create-default-smart

Code sample: cURL

curl -X POST 'https://api.justcrawl.io/api/v1/workflows/create-default-smart' \
  -H 'Authorization: Bearer $JUSTCRAWL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"strategy":"success"}'

• Production

Create a smart workflow from the org’s connected providers without requiring benchmark data. Used by the smart-workflow flow when a user has no URL history to benchmark (fresh org, or after deleting all workflows including the default), and by the guided MCP scrape to stand up a per-domain workflow on first use.

Provider order is a static alphabetical fallback by providerId — without benchmark data we have no signal to rank by. Per-strategy ranking only kicks in once the optimization cycle runs against real benchmark data.

route selects which workflow this call owns, and changes three behaviours:

• * (the default) — the org-wide default workflow. Chain is capped at 3 providers, and an org with no active provider accounts gets a 400.
• domain:<host> — a workflow routed to one domain, resolved ahead of the * default for URLs on that host. The chain includes every supported vendor (a vendor the org cannot authenticate simply fails over at runtime), and an org with no active provider accounts is not an error — a platform-managed org scrapes on platform credentials and legitimately has none. The host segment is normalized server-side (lowercased, www. stripped) so it matches the URL’s generated domain: tag.

Idempotent per route: if a workflow already exists on this route for the org, it is updated in place; otherwise a new one is created and published.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

strategy

required

string

Allowed values: success cost reliability quality

route

* for the org-wide default (the behaviour when omitted), or domain:<host> for a domain-routed workflow. The host segment is normalized server-side, so domain:www.example.com and domain:example.com address the same workflow.

string

default: *

Example

domain:example.com

pipeline

object

includeStorage

boolean

includeExtractor

boolean

extractorPageType

string

Responses

201

The created or updated default smart workflow. Body is wrapped under workflow rather than returned directly so callers can disambiguate create-vs-update via workflow.isUpdate.

Media typeapplication/json

object

workflow

object

workflowId

string format: uuid

name

string

route

The canonical route this workflow was created on — ‘*’, or the normalized ‘domain:’.

string

providerOrder

Array<string>

costPerThousand

Always null on this endpoint — cost estimation needs benchmark data.

number

nullable

isUpdate

True when an existing default workflow was overwritten; false when a fresh one was created.

boolean

Example^generated

{
  "workflow": {
    "workflowId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "name": "example",
    "route": "example",
    "providerOrder": [
      "example"
    ],
    "costPerThousand": 1,
    "isUpdate": true
  }
}

400

Invalid strategy (must be one of success, cost, reliability, quality), a malformed route (must be * or domain:<host>), or no active providers configured for the org on the * route.

401

Missing or invalid authentication token

Media typeapplication/json

object

error

string

Example

{
  "error": "Missing or invalid authentication token"
}

403

Insufficient permissions for this operation

Media typeapplication/json

object

error

string

Example

{
  "error": "No organization. Complete onboarding first."
}

500

Unexpected server error. Logs and PostHog $exception capture

Media typeapplication/json

object

error

string

Example

{
  "error": "Something went wrong"
}