Using the Stocksmith API

Pull your Stocksmith data into your own tools with our read-only API


Tired of exporting CSVs by hand every time you need your inventory numbers somewhere else? The Stocksmith API lets you pull your materials, products, recipes, and more straight into your own spreadsheets, dashboards, or scripts.

The Stocksmith API (v1) is a read-only REST API: you can list and look up your account data, but you can't create, update, or delete records through it yet. Every response comes back as JSON, and every request is authenticated with a personal API key.

The API is currently in closed beta, so it isn't switched on for every account yet. If you don't see API Keys under Settings, it hasn't been enabled for your account yet, so check back soon.

In this article:

Getting an API key

Go to Settings > API Keys to create and manage your keys. A few things to know before you start:

  • Only the primary account user can manage API keys. If you're not the primary user on the account, you won't see this option.
  • You can have up to five active keys at a time. Give each one a name so you remember what it's for, for example "Inventory dashboard".
  • The full key is shown once, at the moment you create it. Copy it somewhere safe straightaway: Stocksmith only stores a masked version afterwards, and there's no way to reveal the full key again.
  • Every key starts with live_. Revoke a key any time from the same page if you no longer need it.

Authenticating your requests

Send your key as a Bearer token in the Authorization header of every request:

Authorization: Bearer live_yourkeyhere

A request with no key, an invalid key, or a revoked key gets a 401 Unauthorized response. All responses, successful or not, come back as JSON.

Available endpoints

Every endpoint supports listing a page of records, or looking up a single one by adding its ID to the path. The API uses the same names you see in Stocksmith itself:

Endpoint Returns
GET /api/v1/ping A connectivity check that confirms your key works.
GET /api/v1/account Basic account details: name, currency, time zone, and subscription plan.
GET /api/v1/materials Your materials: raw materials and supplies.
GET /api/v1/products Your finished products, including variations and stock levels.
GET /api/v1/components Your components: sub-assemblies used to build other products.
GET /api/v1/manufactures Your manufacture production runs.
GET /api/v1/recipes Your recipes, including the full ingredient list and calculated costs.
GET /api/v1/expenses Your purchases, with line items and supplier details.

Cost and price fields (like unit_cost or the recipe cost breakdown) only appear in the response if the user attached to your API key has permission to view financials in Stocksmith. If that user doesn't have cost visibility, those fields are simply left out of the response. The /expenses endpoint goes a step further and returns a 403 Forbidden for a key without purchase access.

Paging through results

List endpoints return 25 records per page by default. Add per_page to change that, up to a maximum of 100:

GET /api/v1/materials?page=2&per_page=50

Every list response includes a meta block so you know where you are:

"meta": {
  "current_page": 2,
  "total_pages": 8,
  "total_count": 187,
  "per_page": 50
}

Filtering results

Add these as query parameters to narrow down a list. Available filters differ by endpoint:

Endpoint Filters
Materials, Products, Components state (active, archived, or all; defaults to active), name, sku, category_name
Manufactures product_id, status, from / to (start date range)
Recipes product_id, variation_id, updated_since
Purchases from / to (purchase date range), updated_since, category_id, supplier_id, received_status

For example:

GET /api/v1/materials?state=archived&category_name=Waxes

Dates use the YYYY-MM-DD format, and timestamps use full ISO 8601 (for example 2026-06-20T00:00:00Z). On recipes and purchases, an invalid filter value returns a 400 Bad Request with a message telling you what's wrong.

Rate limits

Each key can make up to 1,000 requests per minute. Requests without a valid key are limited to 20 per minute per IP address. If you go over the limit, you'll get a 429 Too Many Requests response with a Retry-After header telling you how many seconds to wait.

Handling errors

Errors come back as a JSON object with a single error field:

{ "error": "Invalid or revoked API key" }
Status Meaning
401 Unauthorized The Authorization header is missing, or the key is invalid or revoked.
403 Forbidden The API isn't enabled for this account, or the key's user doesn't have permission for this resource.
404 Not Found No record exists with that ID, or it exists under a different endpoint. A component's ID, for example, won't be found under /materials.
429 Too Many Requests You've hit the rate limit. Wait for the period given in the Retry-After header.

Trying it out

Check that your key works:

curl https://app.stocksmith.io/api/v1/ping \
  -H "Authorization: Bearer live_yourkeyhere"
{ "ping": "pong", "account_id": 12345 }

List your materials:

curl https://app.stocksmith.io/api/v1/materials \
  -H "Authorization: Bearer live_yourkeyhere"
{
  "materials": [
    {
      "id": 501,
      "name": "Soy wax",
      "sku": "WAX-SOY-01",
      "unit_measure": "kg",
      "category": "Waxes",
      "stock_on_hand": "42.5",
      "available_stock": "40.0",
      "reorder_level": "10.0",
      "state": "active",
      "unit_cost": { "amount": "8.2", "currency_code": "USD" },
      "created_at": "2026-01-14T09:03:00Z",
      "updated_at": "2026-06-01T11:22:00Z"
    }
  ],
  "meta": { "current_page": 1, "total_pages": 1, "total_count": 1, "per_page": 25 }
}

Money values always come back as an object with amount as a string (not a plain number) plus a currency_code. This avoids rounding errors when your code parses the value.

Connecting an AI assistant

If you use an AI assistant like Claude or ChatGPT, you can connect it straight to your Stocksmith account through our MCP server at mcp.stocksmith.io. Once it's connected, you can ask your assistant questions about your materials, products, recipes, and more, without leaving the conversation.

The MCP server sits behind the same closed beta gate as the rest of the API. If you don't see API Keys under Settings, the MCP server isn't switched on for your account yet either.

  • It's read-only, the same as the REST API above. Your assistant can check a connection, look up your account details, and list or view materials, products, components, recipes, manufactures, and purchases: 14 tools in total.
  • Only the primary account user can connect an assistant. If you're not the primary user, the connection is refused.
  • In your assistant's settings, add a new connector pointing at mcp.stocksmith.io. Your assistant registers itself with Stocksmith automatically and takes you through a sign-in and approval screen. No API key is needed for this step.
  • Once you approve it, the connection shows up under Settings > Connected Apps, where you can see when it connected, when it was last used, and revoke it at any time.

Building your own integration rather than using an assistant's built-in connector? Authenticate with a regular API key the same way you would for the REST API described above.

Troubleshooting

I'm getting a 401 Unauthorized

  1. Check the header reads exactly Authorization: Bearer live_.... A missing "Bearer" prefix or extra whitespace will fail.
  2. Confirm the key hasn't been revoked under Settings > API Keys.
  3. Generate a new key if you're not sure the one you have is still valid. The full value can't be viewed again once created.

I'm getting a 403 Forbidden

  1. Confirm the API is enabled for your account. See the note near the top of this article.
  2. For /expenses specifically, confirm the user the key belongs to has permission to view purchases and costs.

I don't see cost fields in my response

This is expected if the user attached to your API key doesn't have permission to view financials in Stocksmith. Create a key under a user who has cost visibility if you need that data.


I can't connect my AI assistant

  1. Confirm you're signed in as the primary account user. Secondary users can't connect an assistant.
  2. Confirm the MCP server is enabled for your account. See the callout near the top of this article.
  3. Disconnect and reconnect from your assistant's settings, then approve the request again.

FAQ

Can I create, update, or delete records through the API?

Not yet. This version of the API is read-only: you can list and look up records, but writing data back into Stocksmith isn't supported.

Which user's permissions apply to my API key?

Whichever user created the key. If that user is view-only, or doesn't have cost visibility, the API reflects the same restrictions they'd see inside Stocksmith itself.

Is there a limit on how many keys I can have?

Yes, up to five active keys per user. Revoke one you're not using if you need to create another.

Can I disconnect an AI assistant I've connected?

Yes. Go to Settings > Connected Apps and revoke it from there. This immediately cuts off its access to your account.

Need Help?

Already have an API key and just want the quick answer to "do you have an API"? See Do you have an API available? Still stuck, or want to request something this version doesn't support yet? Please get in touch, and we'll be happy to help.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.