Introduction to the smenso API

The smenso API allows external systems to interact with your smenso workspace programmatically. You can create, read, update, and delete entities such as projects, tasks, absences, time records, and status reports - enabling workflow automation, data synchronization, and reporting integrations. This page gives you a high-level understanding of the API before diving into the details. If you want to jump straight into code, see the Quick Start Guide.

❗️ Availability: The Integration API is available only in workspaces with the Enterprise Add-on "smenso Integration API" enabled.

Base URL

All API requests are made against your workspace-specific base URL:

https://{workspace}.smenso.cloud/skyisland/api/

Replace {workspace} with your actual workspace subdomain.

Prerequisites

Before making your first API call, ensure the following:

Your workspace has the Enterprise Add-on "smenso Integration API" enabled
You have generated a personal API token in the Admin Center (see Authentication)
For write operations (create/update/delete), your account requires an Admin role
For read-only operations via the Reporting API, any role is sufficient

A first look: Making an API request

Here is a minimal example that retrieves your workspace's timezone configuration:

curl --request GET \
     --url https://{workspace}.smenso.cloud/skyisland/api/integration/timezones/json \
     --header 'Authorization: Basic {your-api-token}' \
     --header 'accept: application/json'

A successful response returns a JSON array of supported timezone identifiers.

📘
For a complete step-by-step walkthrough, see the Quick Start Guide.

API access models

smenso provides three API models that you can use individually or combine:

API model	Format	Read	Write	Best for
JSON API	JSON	✅	✅	Modern integrations, CRUD, automation (recommended for new projects)
XML API	XML	✅	✅	Legacy/enterprise batch workflows
Reporting API	JSON/CSV	✅	❌	Dashboards, analytics, exports

📘
Not sure which model fits your use case? See API Types for a detailed comparison.

Who can use the API?

All smenso user types - Admins, Members, Restricted Members, Read-only Members, Guests, and their restricted/read-only variants - can generate a personal API token.

Key permission rules:

Reporting API (read-only exports): Available to all roles. Returned data respects the user's existing UI permissions.
Integration API (create/update/delete): Requires an Admin role for write operations.

📘
API permissions mirror the user's permissions in the smenso UI. If a user cannot see a project in the UI, the API will not return it either. See Permissions & Privacy for details.

Common use cases

Use case	Description	Relevant guide
Workflow automation	Create tasks automatically when events occur in external systems (e.g., CRM, ticketing)	Tasks
Data synchronization	Sync projects, tasks, or absences between smenso and HR, ERP, or other systems	Projects, Absences
Project provisioning	Create new projects based on templates triggered by external events	Templates
Bulk import	Import large batches of tasks, absences, or time records	Integration Tickets
Reporting & analytics	Export project/task data for dashboards or BI tools like Power BI	API Types
Custom field management	Enrich entities with workspace-specific metadata using Flavors	Flavors

General response behavior

All API endpoints follow consistent patterns:

Successful requests return an HTTP 200 status with the requested data or a confirmation.
Asynchronous operations return an HTTP 202 with a ticketId for polling (see Integration Tickets).
Validation errors return structured error messages matching the validation rules of the smenso UI.
Authentication failures return HTTP 401.