Getting Started

Everything you need to authenticate, make your first API call, and start building with the SpireStock REST API.

Prerequisites

• An active SpireStock workspace with admin or developer access.
• An API key, created from the dashboard under Developer → API Keys. Creating one requires workspace administrator access.
• A tool for making HTTP requests — cURL, Postman, or any HTTP client library.

Base URL

All API endpoints are served from a single base URL. Every path referenced in this documentation is relative to:

https://api.spirestock.com/api/v1

For example, the full URL for listing orders would be https://api.spirestock.com/api/v1/orders.

Authentication

SpireStock accepts two credentials. Which one you want depends on whether a browser is involved.

Authenticating with an API key

Create a key in the dashboard under Developer → API Keys, or with the API itself while signed in as an administrator:

curl -X POST https://api.spirestock.com/api/v1/developer/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse sync",
    "scopes": "read,orders",
    "expires_in_days": 90
  }'

{
  "response_code": 201,
  "message": "API key created. Save this key — it won't be shown again.",
  "data": {
    "id": 3,
    "key": "df_9f3a1c7e2b8d4a6f0c5e1b7a3d9f2e4c6a8b0d2f4e6a8c0b2d4f6a8c0e2b4d6f",
    "name": "Warehouse sync",
    "key_prefix": "df_9f3a1c",
    "scopes": "read,orders",
    "expires_at": "2026-11-16T00:00:00.000Z"
  }
}

Send it on every request as a header:

X-API-Key: df_9f3a1c7e2b8d...

Scopes

A key’s scopes string mixes two kinds of token: actions (read, write) and optional resources (orders, users, products, …). read permits GET and HEAD; write permits every method and implies read. Name no resource and the key reaches every endpoint it is allowed to; name one or more and it is confined to those.

Authenticating with a session token

If you are building something a person signs into, exchange their credentials for a JWT. The request must carry a turnstile_token from the Turnstile widget on your page:

curl -X POST https://api.spirestock.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "User-Agent: AcmeIntegration/1.0" \
  -d '{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD",
    "turnstile_token": "TOKEN_FROM_THE_TURNSTILE_WIDGET"
  }'

{
  "response_code": 200,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "first_name": "Jane",
    "last_name": "Developer",
    "official_email": "[email protected]",
    "role_name": "Admin",
    "user_type": 0,
    "organization_id": 5,
    "organization_name": "Acme Dairy"
  },
  "workspace": {
    "workspace_id": "ws_x9y8z7",
    "slug": "acme-dairy",
    "display_name": "Acme Dairy",
    "plan": "professional",
    "status": 1
  }
}

Include the token in the Authorization header using the Bearer scheme:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Set a User-Agent

The API rejects requests whose User-Agent is missing, shorter than 10 characters, or matches a known scraping tool. Several HTTP clients trip this by default:

curl https://api.spirestock.com/api/v1/orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "User-Agent: AcmeIntegration/1.0"

const res = await fetch("https://api.spirestock.com/api/v1/orders", {
  headers: {
    "X-API-Key": process.env.SPIRESTOCK_API_KEY,
    "User-Agent": "AcmeIntegration/1.0",
  },
});

import requests

session = requests.Session()
session.headers.update({
    "X-API-Key": os.environ["SPIRESTOCK_API_KEY"],
    "User-Agent": "AcmeIntegration/1.0",
})

Your First Request

With a key in hand, fetch a list of orders from your workspace. Keep the key in an environment variable — never in source control.

curl https://api.spirestock.com/api/v1/orders \
  -H "X-API-Key: $SPIRESTOCK_API_KEY"

const res = await fetch("https://api.spirestock.com/api/v1/orders", {
  headers: {
    "X-API-Key": process.env.SPIRESTOCK_API_KEY,
  },
});

const { data, pagination } = await res.json();
console.log(data);  // Array of order objects
console.log(pagination.total);

import os
import requests

res = requests.get(
    "https://api.spirestock.com/api/v1/orders",
    headers={"X-API-Key": os.environ["SPIRESTOCK_API_KEY"]},
)

result = res.json()
print(result["data"])  # List of order objects
print(result["pagination"]["total"])

Every request is scoped to the organization the key belongs to. There is no tenant parameter to pass and no way to reach another workspace’s data.

What You Can Build

A single API key reaches most of the workspace — orders, outlets, products, routes, reports and more. A read key pulls data out; a write key pushes data back in. Below are the common integrations, and the endpoint groups each one uses.

For the full, always-current list of every endpoint and its schema, see the API Reference. A key can reach every group except the ones that manage credentials, billing or the platform itself — see Scopes above.

Building with AI instead of code

If the goal is to ask questions of the workspace rather than build a pipeline, connect an AI assistant over MCP instead of writing against the REST API directly. It wraps a read key and lets Claude, Cursor or any MCP-compatible client answer questions in plain language:

• “How many orders were delivered last week, by outlet?”
• “Which distributors haven’t ordered this month?”
• “Summarise today’s sales for the north region.”

The MCP connection is read-only — it can look at orders, accounts, products and reports, but never place an order, change a record or alter billing. See Connect AI Tools for setup.

Rate Limits

To ensure fair usage across all tenants, the API enforces rate limits on a per-IP or per-token basis. When a limit is exceeded the API responds with 429 Too Many Requests.

Error Handling

The API uses standard HTTP status codes. Errors include a JSON body with a response_code matching the HTTP status and a human-readable message field.

{
  "response_code": 400,
  "message": "Validation failed"
}

Next Steps

Now that you can authenticate and make requests, explore further:

• API Reference — Full endpoint documentation with request/response schemas.
• Webhooks — Receive real-time event notifications for orders, users, and payments.
• SDKs — Official client libraries for Node.js, Python, and cURL examples.
• Connect AI Tools — Let Claude, Cursor, or any MCP client read your workspace in plain language. Published on npm today.