Developers

Connect your systems to SparesHaven.

The SparesHaven V1 API provides secure, read-only access to inventory, vendors, incoming orders, and stock movement history. Use scoped API keys to give external applications access only to the workspace data they need.

API overview

Understand the SparesHaven API.

SparesHaven's V1 API gives external systems controlled access to workspace data. The current API is read-only: it can retrieve data but does not create, edit, receive, issue, or delete operational records.

Every successful request is scoped to the organisation that owns the API key. A key cannot use these endpoints to request records from another SparesHaven workspace.

GET/api/v1/inventory

inventory:read

Read inventory and part data.

GET/api/v1/vendors

vendors:read

Read vendor and supplier data.

GET/api/v1/orders

orders:read

Read incoming order data.

GET/api/v1/history

history:read

Read stock movement history.

V1 API access is deliberately read-only.

Operational changes continue to happen through SparesHaven's authenticated application workflows. API credentials expose only the supported read permissions.

Credentials

Create an API key.

API keys are managed from Settings → API access by a workspace Owner or Admin. Give each key a descriptive name and select the read-only permissions required by the system that will use it.

When the key is created, SparesHaven displays the complete secret once. Copy it immediately and store it securely.

Name

Identify the integration

Use a recognisable name such as the application, reporting tool, or service that will use the key.

Scope

Select permissions

Select only the datasets the integration needs. At least one permission is required.

Secret

Save the key immediately

The complete API key cannot be viewed again after the creation window is closed.

Treat an API key like a password.

Do not place API keys in public source code or share them with people who do not need access. If a key is lost or exposed, revoke it and create a replacement.

Authentication

Authenticate every request.

Send the API key in the HTTP Authorization header using the Bearer authentication scheme. SparesHaven API keys use thesp_live_prefix.

Authorization: Bearer sp_live_your_api_key

Missing credentials

A request without an Authorization header is rejected with HTTP 401.

Invalid or revoked key

Invalid credentials and revoked API keys are rejected with HTTP 401.

Missing permission

A valid key without the permission required by an endpoint is rejected with HTTP 403.

Authentication also determines the workspace.

The organisation is taken from the authenticated API key. The client does not provide an organisation ID to these read endpoints.

Permissions

Give integrations only the access they need.

Each endpoint requires its corresponding API permission. A single key can hold one or several permissions.

inventory:read

Read inventory and part data.

vendors:read

Read vendor and supplier data.

orders:read

Read incoming order data.

history:read

Read stock movement history.

Use the smallest useful permission set.

If an integration only needs inventory, for example, it does not need vendor, order, or history permissions.

Inventory endpoint

Read inventory.

Use the inventory endpoint to retrieve non-archived part records from the authenticated workspace. Results are ordered by part number.

GET /api/v1/inventory
Authorization: Bearer sp_live_your_api_key

page

Optional. Positive integer. Defaults to 1.

limit

Optional. Number of records per page. Defaults to 50 and must be between 1 and 100.

search

Optional. Up to 100 characters. Searches part number, description, manufacturer part number, and manufacturer description.

status

Optional. Accepts active or obsolete.

Returned records include the part ID, part number, description, manufacturer part number and description, current stock, minimum and maximum stock, bin location, lifecycle status, unit price, and created and updated timestamps.

Archived parts are not returned.

The Inventory API excludes records whose lifecycle status is archived, even when no status filter is supplied.

Vendors endpoint

Read vendors.

Use the vendors endpoint to retrieve non-archived suppliers from the authenticated workspace. Results are ordered alphabetically by vendor name.

GET /api/v1/vendors
Authorization: Bearer sp_live_your_api_key

page

Optional. Positive integer. Defaults to 1.

limit

Optional. Defaults to 50 and must be between 1 and 100.

search

Optional. Up to 100 characters. Searches vendor name, contact name, and email.

status

Optional. Accepts active or inactive.

Vendor records can include contact name, email, phone, address, city, country, website, notes, PO ordering information, status, and created and updated timestamps.

Archived vendors are excluded from the API.

The Vendors endpoint returns active and inactive records but does not expose archived vendors.

Orders endpoint

Read incoming orders.

Use the orders endpoint to retrieve incoming part orders. Results are returned with the newest-created orders first.

GET /api/v1/orders
Authorization: Bearer sp_live_your_api_key

page

Optional. Positive integer. Defaults to 1.

limit

Optional. Defaults to 50 and must be between 1 and 100.

search

Optional. Up to 100 characters. Searches order number, external order reference, and order note.

status

Optional. Accepts open, partially_received, received, or cancelled.

Each result includes the order identifiers, part and vendor IDs, external reference, ordered, received and cancelled quantities, order dates, status, note, timestamps, related part information, vendor name, and a calculated quantity_remaining.

quantity_remaining =
  quantity_ordered
  - quantity_received
  - quantity_cancelled

Order search has a specific scope.

The API search parameter searches order number, external order reference, and note. It does not search the related part or vendor name.

History endpoint

Read stock movement history.

Use the History endpoint to retrieve stock movement records from the authenticated workspace. Results are returned newest first.

GET /api/v1/history
Authorization: Bearer sp_live_your_api_key

page

Optional. Positive integer. Defaults to 1.

limit

Optional. Defaults to 50 and must be between 1 and 100.

search

Optional. Up to 100 characters. Searches the movement note.

type

Optional. Accepts add or issue.

Movement records include the movement ID, part ID, movement type, quantity, note, creator ID, creation timestamp, and related part number and description.

History API filtering is narrower than the SparesHaven History screen.

The V1 API's type filter currently accepts only add and issue. Adjustment is not currently an accepted API type filter. API history search also searches the movement note rather than part number or description.

Responses

Understand pagination, validation, and errors.

Successful list requests use a consistent response structure. Records are returned in data, with pagination information in meta.

{
  "data": [
    // records for this page
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "count": 50,
    "total": 124,
    "total_pages": 3,
    "has_more": true
  }
}

400

Bad request

Invalid or unsupported query parameters.

401

Unauthorised

Missing, malformed, invalid, or revoked credentials.

403

Forbidden

The key does not have the permission required by the endpoint.

429

Rate limited

The API key has exceeded its current request allowance.

The configured request allowance is 120.

Each API key is checked against a configured limit of 120 requests within SparesHaven's rate-limit window. When the allowance is exceeded, the API returns HTTP 429. Integrations should handle HTTP 429 responses without assuming a particular rate-limit time period.

Unknown query parameters are rejected rather than silently ignored. Search values are limited to 100 characters and certain special characters are not supported.

API list responses are returned with private, no-store cache instructions.

Security

Manage API access safely.

API keys remain visible in Settings by their name and masked prefix, together with their permissions, creation date, and last-used information. The complete secret is not displayed again after creation.

Review

Know which systems have access

Give keys descriptive names and periodically review active credentials and their assigned permissions.

Revoke

Stop authentication immediately

Revoking a key prevents it from authenticating future API requests. Revocation cannot be undone.

Delete

Remove revoked credentials

Once a key has been revoked, its record can be permanently deleted from the revoked-key area.

Replace a key instead of trying to recover it.

If an API key is lost, revoke the existing credential and create a new one. SparesHaven does not reveal the complete secret again.

Continue learning

Return to workspace configuration.

Review appearance, notification preferences, workspace currency, and the API-key management controls available in SparesHaven Settings.

Settings documentation