Build jobs

A build job is one headless run of the WPOS agent against one site. You send a plain-language instruction plus optional structured context, WPOS runs the agent with no human in the loop, and you get back a structured result: a summary, the changes it made, and any warnings. Every call needs the jobs scope.

Submit a job

POST /sites/:siteId/jobs.

curl -X POST https://api.wpcursor.com/api/partner/v1/sites/site_.../jobs \
  -H "X-Partner-Key: $WPOS_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Create an About page from the brief in context, publish it, and link it in the main menu.",
    "context": { "brief": "Family-run bakery since 1998, three locations, known for sourdough." },
    "externalRef": "job_about_001",
    "model": "sonnet",
    "timeoutMinutes": 15
  }'

Field	Required	Notes
`instructions`	yes	Plain-language task, up to 10,000 characters.
`context`	no	Structured data passed to the agent verbatim as JSON, up to 20,000 characters serialized. Briefs, approved copy, audit findings.
`externalRef`	no	Your own id. Makes the submission idempotent.
`model`	no	`sonnet` (default) or `opus`.
`timeoutMinutes`	no	5 to 30, default 15. A run that exceeds it ends with status `timeout`.

A new job returns 202; a repeat of the same externalRef returns 200 with the existing job.

{ "success": true, "job": { "id": "job_...", "status": "queued", "pollUrl": "/api/partner/v1/jobs/job_..." } }

Jobs run with no human in the loop. The agent never pauses to ask a question, so put everything it needs in instructions and context. Structured context in the context field beats stuffing data into the instruction prose.

Preconditions

A job is accepted only when the site belongs to you and is active, the account is active, and the account has credits. Insufficient credits returns 403 limit_reached. There are caps on concurrency: a small number of partner jobs run at once globally, and one running job per site. At capacity you get 429 rate_limited; retry shortly.

Poll for the result

GET /jobs/:jobId. Poll until status is terminal: succeeded, failed, timeout, or cancelled.

{
  "success": true,
  "job": {
    "id": "job_...",
    "siteId": "site_...",
    "externalRef": "job_about_001",
    "status": "succeeded",
    "model": "sonnet",
    "result": {
      "summary": "Created and published an About page and added it to the main menu.",
      "changes": [
        { "type": "page_created", "pageId": 42, "url": "https://customer.com/about", "title": "About" }
      ],
      "warnings": []
    },
    "creditsConsumed": 6,
    "createdAt": "2026-08-08T...",
    "startedAt": "2026-08-08T...",
    "finishedAt": "2026-08-08T..."
  }
}

The result shape

On success, result is the agent’s structured report:

summary: one line describing what it did.
changes: an array of { type, pageId?, url?, title? }. type is one of page_created, page_updated, widget, or other.
warnings: anything the agent flagged but did not treat as failure.

If the agent finished but its final report could not be parsed, result is { "raw": "..." } with the raw text, and status is still succeeded.

Rather than polling, register a webhook and handle the job.completed event, which fires on every terminal status and carries the same result. Use polling for interactive flows, webhooks for everything else.

Cancel a job

POST /jobs/:jobId/cancel is best-effort: a queued job becomes cancelled, a running job is stopped and becomes cancelled, and a job already finished returns 200 with its current status unchanged.

curl -X POST https://api.wpcursor.com/api/partner/v1/jobs/job_.../cancel \
  -H "X-Partner-Key: $WPOS_PARTNER_KEY"

Credits and cost

After a job finishes, WPOS converts its cost to credits and consumes them from the account, recording both creditsConsumed and the underlying cost_usd on the job. Any run that actually started consumes at least one credit. Watch spend per account in the dashboard.

Embed the assistant

The same agent, driven by your customers in your UI.

Webhooks

Get told when a job finishes.

Overview

Get started

Guides

Reference

Submit a job

Preconditions

Poll for the result

The result shape

Cancel a job

Credits and cost

Next

Embed the assistant

Webhooks

​Submit a job

​Preconditions

​Poll for the result

​The result shape

​Cancel a job

​Credits and cost

​Next

Embed the assistant

Webhooks

Submit a job

Preconditions

Poll for the result

The result shape

Cancel a job

Credits and cost

Next