First steps to use the smenso API Reference.
Base URL
All API requests use your workspace-specific URL:
https://{workspace}.smenso.cloud/skyisland/api/Replace {workspace} with your subdomain (e.g., acme).
Authentication
Every request requires a personal API token in the Authorization header:
Authorization: Basic {your-api-token}Generate your token in the Admin Center under API Token.
For detailed setup instructions, see the Authentication Guide.
How this reference is organized
The sidebar groups all endpoints into three API models. Each model serves a different purpose:
| Section | Format | Read | Write | Use when… |
|---|---|---|---|---|
| Integration JSON | JSON | ✅ | ✅ | Building new integrations (recommended) |
| Integration XML | XML | ✅ | ✅ | Maintaining existing batch/enterprise workflows |
| Reporting | CSV / JSON / Excel | ✅ | ❌ | Exporting data for dashboards, BI tools, or analytics |
Starting a new integration? Use the Integration JSON endpoints. All new features are developed exclusively for the JSON API.
Within each section, endpoints are grouped by entity: Absences, Attachments, Comments, Flavors, Folders, Projects, Settings, Status Reports, Tasks, Time Records, and more.
→ For a detailed comparison of the three models, see the API Types Guide.
Making your first request
Verify your token works by calling the Timezones endpoint:
curl -X GET \
"https://{workspace}.smenso.cloud/skyisland/api/integration/timezones/json" \
-H "Authorization: Basic {your-api-token}"If you receive a JSON array of timezone identifiers, your setup is correct.
→ For a full step-by-step walkthrough (including write operations), see the Quick Start Guide.
Key concepts to know
Before exploring the endpoints, familiarize yourself with these concepts:
| Concept | What it means | Guide |
|---|---|---|
| Async tickets | Some write endpoints return a ticketId instead of an immediate result. Poll the status endpoint to track progress. | Integration Tickets |
| Date format | Dates use dd.MM.yyyy format (e.g., 15.09.2024). Do not send UTC offsets. | Dates & Time zones |
| Flavors | Custom fields attachable to projects, tasks, status reports, users, and time records. Identified by GUID or name. | Flavors |
| GUIDs | All entities are identified by GUIDs (e.g., e7737f60-d5a8-4b61-8cda-2ad51ccff4dd). | Core Concepts |
| Permissions | API access mirrors UI permissions. Write operations require an Admin role. | Permissions & Privacy |
| Rate limits | Requests are rate-limited. Handle 429 responses with backoff. | Rate Limits |
Common starting points
Depending on your use case, start with one of these endpoint groups:
| I want to… | Go to |
|---|---|
| Create or update tasks | Tasks (JSON) |
| Import absences | Absences (JSON) |
| Provision projects from templates | Projects → Create from template (JSON) |
| Export project data for Power BI | Projects (Reporting) |
| Log time records | Time Records (JSON) |
| Manage member settings & working times | Settings (JSON) |
| Check the status of an async operation | Get status ticket (JSON) |
Integration XML: Legacy note
The Integration XML section and the Integration v1 subsection contain older endpoints. They remain fully functional but are not being extended with new features. If you see an equivalent endpoint in both JSON and XML, prefer the JSON version.
The Integration v1 endpoints use a generic path pattern (/api/integration/{integrationName}) and are superseded by the entity-specific endpoints. They are maintained for backward compatibility only.
Need more context?
The Guides section provides in-depth explanations, best practices, and examples for each entity and concept. Use the Guides to understand how and why, and the API Reference to see the exact request/response details.
| Topic | Guide |
|---|---|
| Data model & foundational concepts | Core Concepts |
| Token setup & security | Authentication |
| JSON vs. XML vs. Reporting | API Types |
| Async polling & error handling | Integration Tickets |
| Date formats & timezones | Dates & Time zones |
| Request throttling | Rate Limits |