API Guide

The SESAM REST API provides a simple and efficient way to interact with the SESAM platform and automate various tasks such as data ingestion, transformation, and management.

This online help guide is designed to provide you with a comprehensive understanding of the SESAM API, including its capabilities, features, and best practices for integration. You will find detailed documentation on the various endpoints, parameters, and response formats, as well as examples and sample code snippets to help you get started quickly.

Whether you are a seasoned developer or just getting started with APIs, this guide will help you make the most out of the SESAM platform and accelerate your data integration projects. So, let's get started!

Authentication and REST API access

The SESAM web interface and external clients use the same REST endpoints, but with different credentials:

Client	Credential	Needs the rest_api_access plan feature	CSRF token
Browser (guests and registered users)	Session cookie	No	Required on POST, PUT, PATCH and DELETE: send the X-CSRFToken header
REST client	Authorization: Token <token> (see Accounts)	Yes	Not needed
OAuth client / MCP server	OAuth access token or MCP token	Yes	Not needed

REST API access is a plan capability, not a property of the account type. Token, OAuth and MCP credentials of a user whose current plan does not include rest_api_access are rejected with 403 Forbidden on every endpoint, even if the token itself was issued earlier. The browser session is deliberately not gated, so the web interface keeps working on every plan. Guests have no API credentials. All currently registered plans (Starter, Basic, Premium) include REST API access; the check matters for future plans and for accounts whose Stripe product is unknown (these are locked out completely).

Errors and limits

Every endpoint answers failures with one of the following status codes. Clients should decide on the status code and treat the body as a human-readable explanation.

Status	Meaning	Typical body
400 Bad Request	The request data is invalid.	Field errors: {"duration": ["Ensure this value is greater than or equal to 1."]}; some endpoints answer {"detail": "..."} or an empty body (malformed task id).
401 Unauthorized	Credentials are missing or invalid, or the feature needs a user account and the caller is a guest (projects, REST API access, public sharing).	{"detail": "Authentication credentials were not provided."} or {"detail": "The feature projects requires a user account."}
402 Payment Required	A plan limit is reached: the rolling 24-hour scenario-creation or simulation quota is exhausted, or a requested scenario duration or area exceeds the plan limit.	{"detail": "Limit of 5 scenario creations per 24 hours exceeded."}; simulations and Builder limit violations answer a list of messages, e.g. ["Limit of 20 simulation runs exceeded.", "Consider upgrading ..."]
403 Forbidden	The plan does not include the requested capability (for example templates or uploads in Starter), the credential type is not allowed by the plan (REST API access), or the CSRF token of a browser request is missing or wrong.	{"detail": "The feature scenario_templates is not included in your plan."} or {"detail": "CSRF Failed: ..."}
404 Not Found	The object does not exist or does not belong to the current user or guest session. This includes projects of other users and task status URLs of tasks that were not started by the caller; SESAM never reveals whether a foreign object exists.	{"detail": "Not found."} or {"detail": "Project does not exist or does not belong to you."}
503 Service Unavailable	A scenario creation (Builder, template copy or ZIP upload) could not be queued. The request is not counted against your quota; retry later.	{"detail": "Scenario creation could not be queued."}

Details of the contract:

• Quotas are rolling windows. "Per 24 hours" always means the 24 hours before the current request, not a calendar day. The runs_per_day field of GET accounts/me/ follows the same rule. Scenario creations (Builder, template copies and ZIP uploads) share one quota, simulation runs have their own. Reservations are atomic, so parallel requests cannot exceed the limit. A creation or run that fails is refunded.
• Scenario creation and simulations are asynchronous. The Builder (builder/create-scenario), template copies (builder/templates/{id}/instantiate), ZIP uploads (builder/upload-scenario) and simulation starts (simulator/simulate-scenario) all answer 202 Accepted with result_id and status_url once the task is queued; the result exists when the status URL reports SUCCESS.
• Duplicating a scenario does not consume quota. It only requires the scenario_duplication feature.
• Projects. A project_id of null, 0 or -1 selects the Workspace and needs no feature. Any other id needs the projects feature (401 for a guest, 403 if the plan has none) and a project owned by the caller (404 otherwise).
• Guests are served by the Starter plan. They get 403 for every capability Starter lacks (for example projects, templates and uploads). 401 is only used when the plan includes a capability that additionally needs an account; the Starter plan has none.
• Status endpoints (Builder, Simulator, Workspace exports, Editor) answer 404 for task ids that were not started by the calling user or guest session.
• Text fields such as names and comments are stored exactly as sent and are returned unchanged. Escaping happens when they are displayed, so API clients receive no HTML entities.