API Quickstart

The Sporeline API gives you programmatic access to your farm data. You can read blocks, batches, recipes, deliveries, and more — or push data from external systems. This guide covers creating a key, storing it, and making a first call.

Prerequisites

• You must have the Manager or Owner role to create and manage API keys.
• API access is on every plan.

Step 1: Create an API Key

1. Navigate to Settings > API Keys.
2. Click Create Key.
3. Enter a Key Name — choose something descriptive like “Production Integration” or “Analytics Export”.
4. Optionally set an Expiration Date. Leave it empty for a key that never expires.
5. Click Create Key.

Save the key immediately. The full key value is shown only once after creation. After you dismiss the confirmation, only a truncated prefix is visible in the table. If you lose the key, you must revoke it and create a new one.

The key value looks like this:

mt_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

It starts with mt_live_, followed by 32 characters.

Step 2: Store the Key Securely

Never hard-code API keys in source code or commit them to version control. Store the key in an environment variable:

export SPORELINE_API_KEY="mt_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Or use your secret manager of choice (AWS Secrets Manager, GitHub Actions Secrets, 1Password, etc.).

Step 3: Make Your First Request

All API requests require the key in the Authorization header using the ApiKey scheme:

Authorization: ApiKey mt_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Fetch your list of recipes:

curl -H "Authorization: ApiKey $SPORELINE_API_KEY" \
  https://9uvbgolte1.execute-api.us-east-1.amazonaws.com/prod/recipes

A successful response returns HTTP 200 with a JSON body:

{
  "data": [
    {
      "recipe_id": "01JTXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "name": "Oyster HW 80/20",
      "species": "Pleurotus ostreatus",
      ...
    }
  ]
}

Authentication Details

The API supports two authentication methods:

For programmatic access, always use an API key. JWT tokens are short-lived and tied to a user session.

Tenant Scoping

All API responses are automatically scoped to your tenant. You cannot access another tenant’s data. The tenant is derived from the API key — no additional tenant ID parameter is needed.

Role Context

API key requests run with the Manager role. Changing settings, setting up integrations and managing API keys need a person signed in to Sporeline, so a key gets 403 for those. See Authentication.

Common Endpoints

Most list endpoints accept limit and next_token query parameters for pagination.

Pagination

List endpoints return up to a configurable number of records per page. When more records exist, a next_token is included in the response. Pass it as a query parameter to fetch the next page:

curl -H "Authorization: ApiKey $SPORELINE_API_KEY" \
  "https://9uvbgolte1.execute-api.us-east-1.amazonaws.com/prod/blocks?limit=50&next_token=<token>"

When a response has no next_token, you have reached the last page.

A next_token belongs to the list that issued it, with the same filters. Sent to a different list, it is refused with a 400 error such as Invalid next_token; start that list again without a token.

Error Responses

The API returns standard HTTP status codes.

Error responses include a JSON body with an error object:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Recipe not found",
    "retry": false,
    "request_id": "2f1c7d6e-4b0a-4f8e-9d1a-3c5b7e9f0a12"
  }
}

See Error Codes for every status and code.

Retries from a portal

A customer portal or ordering system that sends orders to Sporeline will sometimes lose an answer: a timeout, a dropped connection, a 5xx. The order may or may not have been made. To retry safely, send an Idempotency-Key header on every POST /deliveries:

1. Make a new key (a UUID) for each order your system sends, and store it with that order.
2. Send it as Idempotency-Key: <uuid> on the POST /deliveries.
3. If no answer comes back, send the same request again with the same key. Sporeline makes the order once; the retry gets the first answer back, with the header Idempotent-Replay: true.
4. Make a new key only for a new order. The same key with a different body is refused with 422 (IDEMPOTENCY_KEY_REUSED).

A retry that arrives while the first request is still running gets 409 with "retry": true; wait a moment and retry with the same key. Keys last 7 days. Without a key, every retry of a create makes another order. The full rule and the other routes that honour keys are in the API reference.

Managing API Keys

From Settings > API Keys you can:

• View all keys with their name, prefix, status, expiration, and last-used date
• Create new keys at any time
• Revoke a key — requests using that key stop working within five minutes

Revoked keys cannot be re-activated. If you need to replace a key, revoke the old one and create a new one.

Rate Limits

• Per address: 300 requests in any 5 minutes from one IP address. Going over returns HTTP 403 until the rate drops.
• API throttle: 25 requests/second with bursts up to 50, shared by every caller. Going over returns HTTP 429.
• Busy endpoint: a burst that reaches a part of Sporeline that is already working at capacity returns HTTP 503 with a Retry-After header and "retry": true. Wait that many seconds and send a read again; for a write, see Rate Limits first, because the same answer can come back for a write that was saved.
• There is no monthly request quota on any plan.

Implement exponential backoff in your integration to handle both gracefully. See Rate Limits.

Related Pages

• API Keys — Manage keys from the settings panel
• Team Setup — User roles and access control
• Integrations — Push events to your systems with webhooks