API reference

The Partner API is a stable HTTP API. Route shapes, payloads, and error codes are frozen: we add to them, we do not break them.

Base URL

https://api.wpcursor.com/api/partner/v1

All requests and responses are JSON.

Authentication

Send your key on every request:

X-Partner-Key: wpk_...

A key is issued by WPOS with a fixed set of scopes. It is shown to you once and stored only as a hash. Treat it like a password: keep it server-side, rotate it if it leaks (contact WPOS to revoke and reissue), and never ship it to a browser. For in-browser experiences, mint a narrow embed session instead.

Scopes

Scope	Grants
`read`	Read accounts, sites, and job status.
`provision`	Create accounts, change plans, grant credits, set account status.
`handoff`	Set white-label branding on a site.
`jobs`	Submit, poll, and cancel build jobs.
`embed`	Mint embedded-assistant sessions.

A call that needs a scope your key lacks returns 403 forbidden_scope.

Rate limits

Requests are limited per partner, at sixty per minute. Over the limit returns 429 rate_limited; back off and retry. Build jobs have their own capacity limits; see Build jobs.

Endpoints

Method	Path	Scope	Purpose
`GET`	`/ping`	`read`	Confirm the key and see its scopes.
`POST`	`/accounts`	`provision`	Provision an account (idempotent on `externalRef`).
`GET`	`/accounts/:id`	`read`	Read an account.
`POST`	`/accounts/:id/plan`	`provision`	Change the plan.
`POST`	`/accounts/:id/credits`	`provision`	Grant credits.
`POST`	`/accounts/:id/status`	`provision`	Suspend or reactivate.
`GET`	`/accounts/:id/sites`	`read`	List connected sites.
`POST`	`/sites/:siteId/handoff`	`handoff`	Set white-label branding.
`POST`	`/sites/:siteId/jobs`	`jobs`	Submit a build job.
`GET`	`/jobs/:jobId`	`jobs`	Poll a job.
`POST`	`/jobs/:jobId/cancel`	`jobs`	Cancel a job.
`POST`	`/sites/:siteId/embed-session`	`embed`	Mint an embed session.

Errors

Every non-2xx response uses one envelope:

{ "error": { "code": "validation_error", "message": "email is required" } }

Code	Status	Meaning
`unauthorized`	401	Missing, unknown, revoked, or expired key.
`forbidden_scope`	403	The key lacks the scope this call needs.
`partner_suspended`	403	Your partner account is not active.
`limit_reached`	403	Account cap hit, or insufficient credits for a job.
`not_found`	404	No such resource, or it is not yours. Used for cross-tenant access so ids never leak.
`validation_error`	400	A field is missing or malformed.
`plan_invalid`	400	Unknown `planId`.
`email_conflict`	409	The email already belongs to an account that is not yours.
`rate_limited`	429	Over the request or job-capacity limit. Retry after backing off.
`internal_error`	500	Something went wrong on our side. Retry; if it persists, contact us.

Ownership failures answer 404 not_found, never 403. A request for an account, site, or job that is not yours is indistinguishable from one that does not exist, by design, so the API never reveals another partner’s ids.

Webhooks

Events are delivered and signed as described in Webhooks.

Support

Something missing or behaving unexpectedly? Email partners@wpos.ai.

Overview

Get started

Guides

Reference

API reference

Base URL

Authentication

Scopes

Rate limits

Endpoints

Errors

Webhooks

Support

​Base URL

​Authentication

​Scopes

​Rate limits

​Endpoints

​Errors

​Webhooks

​Support

Base URL

Authentication

Scopes

Rate limits

Endpoints

Errors

Webhooks

Support