API Documentation

Headers

Request body

allowed_domains and allowed_roles are AND-combined when both are present (user must satisfy both). A rejected user always sees the same generic 401 Invalid credentials — they cannot tell whether the password was wrong or whether they are simply out of scope.

Examples of filter use

• Only employees — "allowed_domains": ["dobahna.cz"]
• Only platform super-admins — "allowed_roles": ["superadmin"]
• Only internal super-admins (both must hold) — "allowed_domains": ["dobahna.cz"], "allowed_roles": ["superadmin"]
• Admins and super-admins from two domains — "allowed_domains": ["dobahna.cz","semtix.cz"], "allowed_roles": ["admin","superadmin"]

The filters are sent by your backend (alongside the API key) — the end user never sees them and cannot tamper with them. Hard-code them in the integrating application's config, not in the login form.

Example — curl

curl -X POST https://your-cmlsemtix-host/api/v1/auth/verify \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
        "email":"jana@dobahna.cz",
        "password":"hunter2",
        "allowed_domains":["dobahna.cz"],
        "allowed_roles":["superadmin","admin"]
      }'

Example — PHP

$ch = curl_init('https://your-cmlsemtix-host/api/v1/auth/verify');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('CMLSEMTIX_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'email'           => $email,
        'password'        => $password,
        // Lock this integration to in-house staff only:
        'allowed_domains' => ['dobahna.cz'],
        'allowed_roles'   => ['superadmin', 'admin'],
    ]),
]);
$body = curl_exec($ch);
$code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code === 200) {
    $data = json_decode($body, true);
    $remoteUserId = $data['user_id'];        // log them in locally
} else {
    // 401 — invalid credentials; show generic error
}

Example — Node.js

const res = await fetch('https://your-cmlsemtix-host/api/v1/auth/verify', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CMLSEMTIX_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email,
    password,
    // Restrict to staff super-admins of dobahna.cz:
    allowed_domains: ['dobahna.cz'],
    allowed_roles:   ['superadmin'],
  }),
});

if (res.ok) {
  const { user_id, email, name, role } = await res.json();
  // start local session keyed on user_id
} else {
  // 401 — reject login
}

Success response (200)

{
  "user_id": 42,
  "email":   "jana@example.com",
  "name":    "Jana Nováková",
  "role":    "user"
}

Failure response (401)

Returned identically when:

• e-mail is unknown,
• password is wrong,
• account is deactivated (is_active = 0) or has login disabled (can_login = 0),
• e-mail's domain is not in allowed_domains,
• user's role is not in allowed_roles.

The caller cannot distinguish between these cases — by design, to prevent account enumeration and to keep your filter rules opaque to attackers. The real reason is recorded in the CML.SEMTIX auth_logs for audit.

{ "error": "Invalid credentials" }

Returns a list of all projects the user has access to.

Query Parameters

Returns detailed information about a specific project.

Path Parameters

Finds a project by any of its variables (not just the id) and returns its complete configuration in a single call: core fields, billing model, all plain variables, timed variables (grouped periods), members, and every todolist with its todos.

Pass the variable as a query parameter named after the variable key, e.g. ?google_ads_id=392-963-5599. Any project variable key works (google_analytics_id, gtm_id, custom keys, …). Matching is exact on both key and value.

Query Parameters

Example Request

curl -X GET "/api/v1/projects/lookup?google_ads_id=392-963-5599" \
  -H "Authorization: Bearer sk_live_your_api_key"

Example Response

{
  "data": {
    "matched_by": { "var_key": "google_ads_id", "var_value": "392-963-5599" },
    "multiple_matches": null,
    "project": { "id": 53, "name": "...", "billing_type": "tm_project", ... },
    "billing": {
      "billing_type": "tm_project",
      "budget_type": "total_hours",
      "budget_hours": 40,
      "budget_amount": null,
      "hourly_rate": 1200,
      "disallow_over_budget": false,
      "settings": { ... }
    },
    "variables": [
      { "var_key": "google_ads_id", "var_value": "392-963-5599", "template_label": "Google Ads ID", ... }
    ],
    "timed_variables": [
      { "template_id": 2, "label": "Google Ads rozpočet", "currency": "CZK",
        "periods": [ { "value": 65000, "valid_from": "2026-03-01", "valid_to": "2026-02-28", ... } ] }
    ],
    "members": [ { "id": 12, "name": "...", "email": "...", "role": "user" } ],
    "todo_lists": [ { "id": 5, "name": "...", "todos": [ { "id": 91, "title": "..." } ] } ],
    "counts": { "variables": 3, "timed_variables": 3, "members": 4, "todo_lists": 2, "todos": 17 }
  }
}

Errors

Note: If more than one project shares the same variable value, the lowest-id project is returned and multiple_matches holds the total count so callers can disambiguate.

Creates a new project.

Request Body

Updates an existing project.

Deletes a project and all its contents. This action is irreversible!

Returns all task lists in the given project.

Creates a new task list in the project.

Request Body

Returns all tasks in the given list.

Returns detailed information about a specific task.

Creates a new task in the list.

Request Body

Updates an existing task. You can update only the fields you want to change.

Deletes a task. Requires scope delete.

Returns all comments for a specific task, ordered by creation date (newest first).

Path Parameters

Response

Returns an array of comment objects, each containing:

• id - Comment ID
• content - Comment text (may contain HTML)
• created_at - Creation timestamp
• user - Author information (id, name, avatar)
• attachments - Array of attached files

Adds a new comment to a task. Notifies subscribed users.

Path Parameters

Request Body

Updates an existing comment. Only the comment author can edit their comments.

Path Parameters

Request Body

Deletes a comment. Only the comment author or project admin can delete comments.

Returns a list of all users in the system that the authenticated user has access to see.

Response

Returns an array of user objects, each containing:

• id - User ID
• name - Full name
• email - Email address
• avatar - Avatar URL (if set)
• role - User role (user, admin, superadmin)
• is_active - Whether the user is active

Returns a list of all members who have access to the specified project.

Path Parameters

Response

Returns an array of member objects with user details and their access role in the project.

Adds a user to the project, granting them access.

Path Parameters

Request Body

Removes a user from the project, revoking their access.

Path Parameters

Returns all knowledge base articles in the specified project.

Path Parameters

Response

Returns an array of article objects, each containing:

• id - Article ID
• title - Article title
• content - Article content (HTML)
• created_at - Creation timestamp
• updated_at - Last update timestamp
• author - Author information
• tags - Array of associated tags

Creates a new knowledge base article in the project.

Path Parameters

Request Body

Updates an existing knowledge base article.

Path Parameters

Request Body

Deletes a knowledge base article.

Path Parameters

Returns documents in the selected project.

Path Parameters

Fulltext search in document title/content/description within one project.

Query Parameters

Returns HTML content of matching document title. If no matching document exists, returns false.

Compatibility Alias

Also available as: /project/{id}/docs/content?name=changelog

Creates a document in the project.

Request Body

Updates an existing document (title/content/flags).

Deletes (moves to trash) a document.

Global permission-aware fulltext search over projects, task lists, todos and comments (Algolia-backed).

Query Parameters

Vrací odpracovaný čas v projektu za zvolené období. Data lze agregovat per úkol, per uživatele, nebo vrátit jako jednotlivé záznamy. Podporuje filtry (fakturovatelnost, uživatel, seznam úkolů) a CSV export.

Path Parameters

Query Parameters

Response (JSON)

Pole items má strukturu podle parametru detail:

• detail=todo: { todo_id, todo_title, todolist_id, todolist_name, user_id, user_name, entries_count, seconds, hours, formatted }
• detail=todo&include_users=1: { todo_id, todo_title, todolist_id, todolist_name, seconds, hours, formatted, entries_count, users: [...] }
• detail=user: { user_id, user_name, user_email, entries_count, seconds, hours, formatted }
• detail=entries: { id, started_at, ended_at, seconds, hours, formatted, billable, source, todo_id, todo_title, todolist_id, todolist_name, user_id, user_name }

Přijme klientský požadavek a zařadí ho jako úkol do správného projektu. Pokud projekt neexistuje, založí ho.

Request Body

Response (200 OK)

Pošle přímou (direct) zprávu do chatu konkrétnímu uživateli. Pokud mezi odesílatelem a příjemcem ještě neexistuje přímá konverzace, automaticky se vytvoří. Zpráva se příjemci doručí real-time (Pusher) a pokud je offline/idle, dostane push notifikaci (OneSignal). Vyžaduje scope write.

Request Body

Response (201 Created)

Error Codes

1) Zpráva jménem vlastníka API klíče

curl -X POST /api/v1/chat/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "login": "jan.novak@firma.cz",
    "sender": "me",
    "text": "Ahoj, mrkni prosím na ten nový úkol."
  }'

2) Systémová zpráva od Autobota — pro automatizace (cron, n8n, monitoring), zpráva přijde od systémového účtu Autobot.

curl -X POST /api/v1/chat/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "login": "jan.novak@firma.cz",
    "sender": "autobot",
    "text": "Deploy projektu XYZ proběhl úspěšně ✅"
  }'

Příklad odpovědi

{
  "status": "ok",
  "data": {
    "message_id": 48211,
    "conversation_id": 392,
    "sender": "autobot",
    "sender_id": 7,
    "recipient_id": 15,
    "created_at": "2026-06-10 14:32:08"
  }
}