REST API
The primary production path. Use API keys, direct requests, and webhooks for authenticated control-plane operations and execution flow.
Default production integration path
Agent integration
Build against the merchant path Pivota exposes on top of existing merchant stacks.
Pivota is the builder surface for the merchant gateway that sits on top of existing storefront, checkout, and payment systems.
Some merchants start with discovery, feeds, or link-out. When a merchant is ready for deeper flows, builders use the REST path, SDK, or MCP to work with checkout, orders, events, and webhooks.
Why this matters
Merchant onboarding and rollout choice come first. This page describes the builder surface that sits on top of that merchant path, whether the merchant is starting with lighter discovery flows or deeper merchant-native checkout.
Start in 4 steps
Make the first call path obvious before login.
1
Create a developer account and get a production or test API key.
2
Send a first authenticated request against the branded API domain.
3
Create the first order or checkout flow and confirm response shape.
4
Configure webhook delivery and validate execution updates before promoting traffic.
Test and production keys are supported. Validate the first authenticated request and webhook loop before promoting traffic.
Public quickstart
Start with the branded REST path
Use the public API base and the X-API-Key header to validate access before building deeper order or checkout flows.
curl https://api.pivota.cc/agent/v1/merchants \
-H "X-API-Key: YOUR_API_KEY"Choose your integration mode
REST is the default. SDK and MCP sit on top.
SDK
A convenience wrapper over the same production REST API. Published package name: pivota-agent.
Use when your runtime benefits from a client library
MCP
A local orchestration and discovery surface for search and routing workflows. Published package name: pivota-mcp-server.
Not a hosted replacement for the production REST API
What can be called today
Start with the request families already proven in production.
Not every merchant uses every request family on day one. Search, recommendation, and lighter handoff paths may come before deeper checkout and order flows.
Merchant-native checkout does not mean every agent surface completes checkout fully inside chat. Depending on merchant readiness and the surface, execution may continue through link-out or another merchant-controlled handoff while staying in merchant-controlled systems.
Search and recommendation
Query merchant data, resolve products and offers, and support downstream shopping workflows without crawling fragmented sites.
Cart and checkout intents
Validate item paths and create merchant-native checkout flows that carry execution forward.
Orders and order status
Create, inspect, and manage order flows while keeping merchant systems in control.
Order events and execution signals
Observe order lifecycle events and operational state instead of guessing from front-end surfaces alone.
Webhooks and delivery health
Configure destination URLs, subscribe to events, verify signatures, and inspect or retry delivery history.
Merchant-native payment flow
Route execution into payment-aware flows with write-back and sync rather than isolated checkout fragments.
Example request and response
Show builders the execution shape, not just the category story.
Public docs should make the request contract visible before login so a builder can understand the next action, the merchant-native path, and the event model without guessing.
Request example
curl -X POST "https://api.pivota.cc/agent/v1/checkouts/intent" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"merchant_id": "merch_...",
"items": [
{
"product_id": "prod_...",
"variant_id": "var_...",
"quantity": 1
}
],
"currency": "USD"
}'Response example
{
"status": "ready_for_checkout",
"merchant_native_path": {
"checkout_url": "https://checkout.pivota.cc/...",
"rollout_stage": "merchant_native_checkout"
},
"next_action": "redirect_to_checkout",
"events": ["order.created", "order.payment_attempted"]
}Execution boundaries
Make the handoff and execution model explicit.
Pivota resolves structured commerce requests instead of forcing agents to crawl merchant pages.
Merchant-native checkout begins when the executable checkout path is created or returned.
Payment orchestration and downstream status sync stay connected to merchant systems.
Write-back and post-purchase signals continue through APIs and webhooks after execution begins.
What stays public vs what is in the console
Public docs for activation. Console for operational control.
Builders should be able to understand the contract, auth, and execution model without login. Account-specific controls and telemetry stay in the developer console.
Visible without login
First call quickstart and branded API base
Request families and example request shapes
Auth model, webhook model, and execution boundaries
Protocol positioning and merchant-onboarding dependency
Inside the developer console
Create and revoke API keys
Inspect usage, delivery history, and retries
Manage webhook destinations and signing secrets
Review order activity and account-specific operational state
Trust and proof
Public contract, not just conceptual positioning.
The developer portal already validated the public API domain, published SDK packages, MCP runtime, and managed webhook receiver pattern in production.
OpenAPI is live on https://api.pivota.cc/openapi.json
The branded API base is https://api.pivota.cc
The published SDK package is pivota-agent
The published MCP package is pivota-mcp-server
Managed webhook receivers follow https://api.pivota.cc/agents/{agent_id}/webhooks/managed-inbox
Ready to evaluate the callable surface directly?
Start with API access and the first call, then move into request types, auth, webhooks, and protocol positioning as the integration deepens.