SpendGuard™ API Documentation

Operated by: Constant Control Limited

Effective Date: 26 March 2026

Reviewed: 26 March 2026 | Next Review Due: April 2027

The SpendGuard API enables programmatic access to your organisation's contract spend data. API access is authenticated via service account API keys and enforces the same role-based access controls as the SpendGuard web application.

1. Authentication

All API requests require a valid API key passed as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer sg_live_your_api_key_here" \
  https://www.spendguard.co.nz/api/v1/csos

Obtaining an API Key

Navigate to Platform Admin → API Keys in SpendGuard
Click + New Service Account
Configure the name, role, scope, and expiry
Copy the API key immediately — it is shown once and cannot be retrieved again

API Key Format

API keys follow the format sg_live_ followed by 64 hexadecimal characters. Example:

sg_live_a1b2c3d4e5f6...

2. Security Controls

Control	Details
Encryption	All requests must use HTTPS (TLS 1.2+)
Key Expiry	Keys expire after a configurable period (7, 14, 30, 60, or 90 days). Maximum 90 days.
IP Allowlisting	Optional — restrict API access to specific IP addresses or CIDR ranges
Rate Limiting	Default 100 requests per minute per key. Configurable per service account.
Scope	`read` (GET only), `read_write` (all methods), or `admin` (all methods + admin endpoints)
RBAC	Each service account is assigned a role. The same row-level security policies that apply to human users apply to API requests.
Audit Trail	Every API action is logged with the service account name, IP address, endpoint, and timestamp

3. Base URL

https://www.spendguard.co.nz/api/v1

3.1 OpenAPI Specification

The full machine-readable API specification is available at:

Download OpenAPI Spec (JSON)

3.2 MCP (Model Context Protocol)

AI agents that support MCP can discover SpendGuard tools automatically:

GET /api/v1/mcp

Headers:
  Authorization: Bearer sg_live_your_key

Returns a manifest of available tools including get_csos, get_projects,
get_programmes, and get_vendors.

4. Endpoints

Health Check

GET /api/v1

Response:
{
  "name": "SpendGuard API",
  "version": "v1",
  "status": "healthy"
}

No authentication required. Use this to verify connectivity.

List CSOs

GET /api/v1/csos

Headers:
  Authorization: Bearer sg_live_your_key

Response:
{
  "data": [
    {
      "id": "uuid",
      "reference_number": "CSO-2026-0001",
      "title": "Cloud Migration Phase 1",
      "status": "active",
      "total_budget": 480000,
      "budget_spent": 99000,
      "start_date": "2026-01-01",
      "end_date": "2026-06-30",
      "created_at": "2026-03-05T03:24:05Z",
      "project_id": "uuid"
    }
  ],
  "meta": {
    "count": 1,
    "service_account": "Procurement Bot",
    "scope": "read"
  }
}

Returns all CSOs visible to the service account's role and organisation. Scope: read or higher.

5. Error Responses

Status	Meaning	Example
`401`	Invalid, expired, or missing API key	`{"error": "Invalid API key"}`
`403`	Insufficient scope or role for this endpoint	`{"error": "Insufficient scope"}`
`429`	Rate limit exceeded	`{"error": "Rate limit exceeded"}`
`500`	Internal server error	`{"error": "Failed to fetch CSOs"}`

6. Rate Limits

API requests are rate-limited per service account using a sliding window of 1 minute. The default limit is 100 requests per minute. When the limit is exceeded, the API returns 429 Too Many Requests.

Enterprise organisations may request higher rate limits. Contact team@constantcontrol.co.nz.

7. Data Scoping

The API enforces the same data isolation as the web application:

Organisation isolation — Service accounts can only access data within their assigned organisation
Role-based access — A service account with the project_manager role sees only projects it manages and CSOs within those projects
Row-level security — Enforced at the database level, not application level

8. Upcoming Endpoints

The following endpoints are planned for future releases:

Endpoint	Method	Description	Phase
`/api/v1/projects`	GET	List projects	Phase 2
`/api/v1/programmes`	GET	List programmes	Phase 2
`/api/v1/vendors`	GET	List vendors	Phase 2
`/api/v1/transactions`	GET, POST	List and record transactions	Phase 2
`/api/v1/weekly-entries`	GET, POST	List and submit weekly cost entries	Phase 2
`/api/v1/webhooks`	POST	Subscribe to outbound events	Phase 3

9. Support

For API support, integration guidance, or to request additional endpoints:

Email: team@constantcontrol.co.nz
Security issues: security@constantcontrol.co.nz

Constant Control Limited — Licensed for business in New Zealand. Servicing a global market for our clients.