Core Concepts

The smenso data model

Before working with the API, it helps to understand how the key entities relate to each other:

Workspace
 ├── Users
 │    └── Flavors (custom fields)
 ├── Projects
 │    ├── Tasks
 │    │    ├── Flavors (custom fields)
 │    │    ├── Attachments
 │    │    └── Time Records
 │    │         └── Flavors (custom fields)
 │    ├── Status Reports
 │    │    └── Flavors (custom fields)
 │    └── Flavors (custom fields)
 ├── Absences (linked to users)
 └── Templates (project/task/status report creation blueprints)

Key entities

Workspace - The top-level container for all data. Your API token is scoped to one workspace. Each API request targets a specific workspace via the Base URL (https://{workspace}.smenso.cloud/skyisland/api/).

Users - The people in your workspace. Users are referenced by their GUID across many entities (e.g., as assignees on tasks, owners of absences, or creators of time records). Users can carry Flavors for additional metadata. Member settings (including working times) can be read and updated via the Settings endpoints .

Projects - The primary organizational unit in smenso. Projects contain tasks, status reports, and project-level Flavors. Every task belongs to exactly one project.

Tasks - The core work item. Tasks are assigned to projects and can carry custom fields (Flavors), time records, and attachments. Tasks support properties like title, description, priority, start/due dates, status, duration, and more.

Flavors - Workspace-specific custom fields that can be attached to projects, tasks, status reports, users, and time records. Flavors are identified by their GUID or name and allow you to store any additional metadata your workflow requires. See Flavors .

Absences - Represent time off (vacation, sick leave, etc.) for workspace members. Absences are linked to users and are subject to overlap validation rules.

Time Records - Track time spent on tasks. Time records are linked to both a task and a user, and can carry Flavors for additional metadata.

Status Reports - Periodic reports on project progress. Status reports can be created from templates and follow a draft → published lifecycle with restrictions on modifications after publication. They support Flavors for custom reporting fields.

Templates - Blueprints for creating projects (tasks and status reports) with predefined structure, fields, and rules. Templates allow automated, consistent project provisioning via the API. Templates themselves do not carry Flavors - they inherit and pass on the Flavor configuration to the entities created from them. See Templates .

Attachments - Files attached to tasks, projects, and status reports. See Attachments .

Identifiers (GUIDs)

All major entities in smenso are identified by GUIDs (Globally Unique Identifiers), for example:

e7737f60-d5a8-4b61-8cda-2ad51ccff4dd

When referencing entities in API requests (e.g., a project ID, task ID, or user ID), always use the full GUID including hyphens.

📘

You can copy a project's GUID from the smenso UI via the project's context menu or by extracting it from a shared API link.

Authentication

All API requests require a personal API token passed in the Authorization header:

Authorization: Basic {your-api-token}

Tokens are user-scoped: they inherit the permissions and data visibility of the user who created them.

→ Full details: Authentication

Base URL

All API requests use the following base URL pattern:

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

Replace {workspace} with your workspace subdomain.

API models and payload formats

smenso offers three API models with different payload formats:

Each model has its own set of endpoints. The JSON API is recommended for all new integrations.

→ Full comparison: API Types

Request and response structure

Request headers

Every request requires at minimum:

Success responses

Successful requests return HTTP 200 with the requested data or confirmation. The response body format matches the API model used (JSON or XML).

Error responses

Errors return structured messages. Example (JSON API):

{
  "errors": [
    "An error message"
  ]
}

Asynchronous responses

Some write operations return HTTP 200 with a ticketId for async processing:

{
  "id": "df268a25-d957-47ec-ae25-a749c0df861b",
  "endpoint": "Endpoint name",
  "success": 1,
  "status": "Success",
  "statusId": 10,
  "received": "11.02.2026 13:19:22",
  "started": "11.02.2026 13:19:24",
  "processed": "11.02.2026 13:19:29"
}

{
  "id": "f1123add-27ef-4e92-9fda-576d20eddcc8",
  "endpoint": "Endpoint name",
  "success": 0,
  "status": "Failed",
  "statusId": 30,
  "received": "2026-03-16T09:56:24.3935672+00:00",
  "started": "0001-01-01T00:00:00+00:00",
  "processed": "2026-03-16T09:56:24.4456212+00:00",
  "messages": [""],
  "Endpoint": {
    "created": 0,
    "modified": 0,
    "attributesModified": 0,
    "deleted": 0
  }
}

→ See Integration Tickets for polling and result handling.

HTTP status codes

Validation rules

The API enforces the same business rules as the smenso UI. This ensures data consistency regardless of whether changes are made through the interface or the API. Key validation areas include:

• Required fields - Entities like projects and tasks have mandatory fields (e.g., Title). Requests missing required fields are rejected with specific error messages.
• Absence overlap detection - Two absences for the same user cannot overlap in time.
• Status report publication rules - Published status reports cannot be modified; only drafts are editable.
• Time recording locks - Time records may be locked for past periods depending on workspace configuration.
• Flavor constraints - Flavor values must match their configured type and allowed value range.
• Unique constraints - Some fields (e.g., project titles within a workspace) may need to be unique depending on your workspace configuration.

When a validation rule is violated, the API returns a structured error response listing all violations.

Timezone handling

Date values are handled consistently across all endpoints:

• The API automatically determines the correct UTC offset based on the workspace timezone and the date itself (including DST transitions).
• Do not send UTC offsets in date values - the API calculates them for you.
• You can override the timezone per request using supported timezone identifiers.

→ Full details: Dates & Time zones