Public REST API

Build on GiesenCloud

A RESTful API that gives you programmatic access to profiles, roasts, inventory, and planning data. Integrate your roastery with any system.

Get Your API Key View Documentation

Requires the Developer Access add-on on the Commercial or Industrial plan.

Simple, predictable, RESTful

Standard HTTP methods, JSON responses, and consistent pagination. If you have used a REST API before, you already know how this works.

Cursor pagination

List endpoints return a cursor to fetch the next page.

Problem Details errors

Errors follow RFC 9457 as application/problem+json.

Idempotent writes

Every write requires an Idempotency-Key header, so a retry is safe.

Rate limits

120 requests per minute for reads and 30 for writes, per user.

Request GET

curl -X GET https://giesen.cloud/api/public/v1/profiles \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response 200 OK

{
  "data": [
    {
      "id": "9a3f1c2e-7b84-...",
      "name": "Ethiopia Yirgacheffe",
      "roaster_id": 42,
      "is_favorite": true,
      "is_fahrenheit": false,
      "weight_change": -14.5,
      "use_rpm": true
    }
  ],
  "links": { "prev": null, "next": "..." },
  "meta": { "per_page": 25, "next_cursor": "eyJpZCI6..." }
}

Get started in three steps

Get your API key
Create an account and generate a personal access token from your API settings page.
Make your first request
Use the token as a Bearer header to authenticate and fetch your roast profiles.
Explore endpoints
Browse the full API reference to discover every resource available to your integration.

Authentication

Secure by default

The GiesenCloud API uses Laravel Sanctum bearer tokens to authenticate requests. Generate a token from your account settings, then include it in the Authorization header of every request.

Tokens carry the public-api ability and only reach your own team's data.

Scoped, rate-limited, and revocable at any time

# Include in every request
Authorization: Bearer YOUR_API_TOKEN

# Tokens are:
# - Scoped to your team's data
# - Rate-limited per user

AI Tools (MCP)

Talk to your roastery data

Connect any MCP-compatible AI client to your GiesenCloud data over OAuth.

Works with MCP-compatible AI clients
OAuth-Scoped Connections
Team-Scoped & Secure
Read & write tools

Learn more

# MCP Server Endpoint
https://giesen.cloud/mcp

# In your AI client, add a new MCP server with the endpoint URL above.

Endpoint overview

The API is organized around the core resources of your roastery.

Resources	Description
Profiles	List and retrieve your roast profiles.
Roasts	List and retrieve your roast logs.
Roasters	List and retrieve the roasters on your team.
Inventory	Green coffee lots, suppliers and purchase orders.
Planning	Read roast planning, create batches in bulk and mark them complete.
Quality	Samples, sample decisions and cupping sessions.
Coffees	Coffees, blends, blend batches and locations.
Reports	Production, quality and inventory reports.
ERP	Customers, products, variants, price lists, sales and production orders, and shipments. Industrial plan.

View Documentation

The API documentation is available to signed-in teams with API access.

What will you build?

A few ideas for extending your roastery workflow with the API.

E-commerce sync

Read inventory and roast data from the API to keep your online store in step with your roastery floor.

Custom dashboards

Pull roast data into your own BI tools or internal dashboards. Visualize production trends, capacity usage, and quality metrics your way.

Third-party integrations

Connect GiesenCloud to ERPs, accounting software, or logistics platforms. Automate data flow across your entire supply chain.

Start building today

Add Developer Access to your plan, generate an API token, and make your first request.

Get Your API Key Talk to Us