> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wpos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Provision a customer account, connect a site, and run your first build job with the Partner API.

This takes you from an API key to a finished build job. It assumes WPOS has
enabled your account as a partner and issued you a key. If not, see
[Getting access](/partners/overview#getting-access).

<Note>
  The base URL for the Partner API is `https://api.wpcursor.com/api/partner/v1`.
  Authenticate every request with the `X-Partner-Key` header.
</Note>

<Steps>
  <Step title="Check your key">
    Confirm the key works and see the scopes it carries.

    ```bash theme={null}
    curl https://api.wpcursor.com/api/partner/v1/ping \
      -H "X-Partner-Key: $WPOS_PARTNER_KEY"
    ```

    ```json theme={null}
    {
      "success": true,
      "partner": { "id": "ptr_...", "name": "Acme Agency", "slug": "acme" },
      "scopes": ["provision", "read", "handoff", "jobs", "embed"]
    }
    ```
  </Step>

  <Step title="Provision a customer account">
    Create an account for a customer, keyed by your own reference. This call is
    idempotent on `externalRef`: send it again and you get the same account back
    with `existing: true`, never a duplicate.

    ```bash theme={null}
    curl -X POST https://api.wpcursor.com/api/partner/v1/accounts \
      -H "X-Partner-Key: $WPOS_PARTNER_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "email": "owner@customer.com", "externalRef": "ws_123", "company": "Customer Co" }'
    ```

    ```json theme={null}
    {
      "success": true,
      "existing": false,
      "account": { "id": "acc_...", "email": "owner@customer.com", "licenseKey": "WPC-...", "plan": "starter", "createdAt": "2026-08-08T..." }
    }
    ```

    Keep the `licenseKey`: your customer uses it to activate the WPOS plugin on
    their site.
  </Step>

  <Step title="Connect a site">
    Your customer installs the WPOS plugin on their WordPress site and activates
    it with the license key from the previous step. See
    [Install the plugin](/get-started/install). Once the plugin registers, the
    site appears on the account and you get a
    [`site.registered` webhook](/partners/webhooks#events).

    Read the account's sites to get the `siteId` you will run jobs against:

    ```bash theme={null}
    curl https://api.wpcursor.com/api/partner/v1/accounts/acc_.../sites \
      -H "X-Partner-Key: $WPOS_PARTNER_KEY"
    ```
  </Step>

  <Step title="Grant some credits">
    Build jobs consume credits. Grant the account a balance to work from.

    ```bash theme={null}
    curl -X POST https://api.wpcursor.com/api/partner/v1/accounts/acc_.../credits \
      -H "X-Partner-Key: $WPOS_PARTNER_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "amount": 500, "reason": "Onboarding grant" }'
    ```
  </Step>

  <Step title="Run a build job">
    Submit a plain-language instruction for the agent to run on the site. The call
    returns immediately with a job you poll.

    ```bash theme={null}
    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": "Add a testimonials section to the homepage with three quotes.", "externalRef": "job_001" }'
    ```

    ```json theme={null}
    { "success": true, "job": { "id": "job_...", "status": "queued", "pollUrl": "/api/partner/v1/jobs/job_..." } }
    ```
  </Step>

  <Step title="Poll for the result">
    Poll the job until it reaches a terminal status. A finished job carries a
    structured summary of what changed.

    ```bash theme={null}
    curl https://api.wpcursor.com/api/partner/v1/jobs/job_... \
      -H "X-Partner-Key: $WPOS_PARTNER_KEY"
    ```

    ```json theme={null}
    {
      "success": true,
      "job": {
        "id": "job_...",
        "status": "succeeded",
        "result": {
          "summary": "Added a testimonials section with three quotes to the homepage.",
          "changes": [{ "type": "page_updated", "pageId": 12, "url": "https://customer.com/", "title": "Home" }],
          "warnings": []
        },
        "creditsConsumed": 4
      }
    }
    ```

    Instead of polling, you can register a webhook and receive a
    [`job.completed` event](/partners/webhooks#events) the moment it finishes.
  </Step>
</Steps>

<Tip>
  Prefer webhooks to tight polling loops. Poll at a human pace (every few seconds)
  for interactive flows, and lean on the `job.completed` webhook for everything
  else.
</Tip>

## Next

<CardGroup cols={2}>
  <Card title="Accounts" icon="users" href="/partners/accounts">
    Plans, credits, status, and sites in depth.
  </Card>

  <Card title="Build jobs" icon="robot" href="/partners/build-jobs">
    Instructions, context, results, and caps.
  </Card>

  <Card title="Embed the assistant" icon="window" href="/partners/embed">
    Put the agent inside your own product.
  </Card>

  <Card title="API reference" icon="code" href="/partners/api-reference">
    Every endpoint, error, and limit.
  </Card>
</CardGroup>