REST API: Authentication and Basic Calls

Authentication
Paging, filtering and sorting
- Filter syntax
Error format
Most frequently used endpoints

The REST API lets an external application create cases, work with tasks and variables, upload documents and read TAS data. This chapter describes how to connect to the API, how lists and filters work and what error responses look like. It is intended for integrators and administrators who are preparing an integration. The addresses and parameters correspond to TAS version 5.19.12.

No common prefix
The API has no common prefix such as /api or /rest. The paths in this chapter (e.g. /tasks) are appended directly to the address of your TAS installation, for example https://vase-tas.cz/tasks.

Authentication

TAS accepts three kinds of authentication token, all in the same header:

Authorization: Bearer <token>

Kind	Where the token comes from	When to use it
API token	Administration › API Access › API Tokens	Long-term server-to-server integration without OAuth.
OAuth access token	`POST /oauth/token` (OAuth client)	New integrations, short-lived tokens, applications that need user consent.
Session (cookie)	Signing in through the browser	Only for calls from the TAS web interface itself, not for external integrations.

TAS recognises all three kinds by the content of the token and handles them the same way – the call runs with the permissions of the user the token represents (for an API token and a confidential OAuth client, this is the assigned system user; for an OAuth client with user consent, it is the user who approved the access). How to obtain a token or client and how to work with it is described in detail in the article API tokens and OAuth clients in practice.

The header name can be renamed per installation; the default name, valid in the vast majority of installations, is Authorization.

Paging, filtering and sorting

List endpoints (for example GET /tasks) accept the following query string parameters:

Parameter	Meaning
`limit`	Number of records returned. If omitted, the installation's default limit applies.
`offset`	How many records to skip from the start.
`order`	Comma-separated columns to sort by, e.g. `order=createdAt,name`. Dot notation across a relation can also be used, e.g. `order=owner.name`.
`sort`	Sort direction for each column in `order`, comma-separated: `asc` or `desc`. A column without a matching direction is sorted in ascending order.
`filter`	Filter condition, see the syntax below.
`total_count`	When `true` (default), the response includes the total number of records.
`only_count`	When `true`, only `{ "items": [], "totalCount": N }` is returned, without data.
`columns`	Limits the returned columns to those listed.
`distinct`	Returns only distinct records.
`includeDeleted`	Includes deleted records in the result.
`nullsLast`	Sorts empty values to the end (PostgreSQL only).
`disable_accent`	Turns off accent-insensitive comparison when filtering.

Filter syntax

A condition has the form pole<operátor>"hodnota" (field, operator, value); conditions can be combined with <and> / <or> and grouped in parentheses:

Operator	Meaning
`<eq>`	equals
`<ne>`	does not equal
`<gt>`	greater than
`<lt>`	less than
`<ge>`	greater than or equal to
`<le>`	less than or equal to
`<like>`	contains (LIKE); the value may contain `%`
`<nlike>`	does not contain
`<in>`	is one of the comma-separated values
`<nin>`	is none of the values
`<isn>`	is empty (NULL)
`<isnn>`	is not empty

curl "https://vase-tas.cz/tasks?filter=(name<like>\"%Objednávka%\"<or>state<eq>\"Open\")<and>ownerId<eq>\"123\"&order=dueDate&sort=asc&limit=20" \
  -H "Authorization: Bearer <token>"

Fields in camelCase
Field names in the filter and in order/sort are entity properties in camelCase (e.g. dueDate), not database column names. TAS does convert uppercase letters and underscores automatically, but camelCase is the safe choice across versions.

Error format

A failed call returns an error code (400, 401, 403, 404, 409, 500 …) and the body:

{
  "error": {
    "createdAt": "2026-10-31T08:15:00.000Z",
    "message": "Unauthorized.",
    "codeName": "UNAUTHORIZED",
    "error": "Unauthorized",
    "status": 401,
    "statusCode": 401,
    "chain": null,
    "meta": {}
  }
}

codeName is a machine-readable error code, message is text for display or logging. For an authentication error, the response may also contain sessionExpired: true.

Most frequently used endpoints

Creating a case from a header

curl -X POST "https://vase-tas.cz/processes/activate/61" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"header_id": 2270}'

61 is the template ID (tproc_id), header_id is the ID of the specific header from which the case is created. The response contains the ID of the created case and the first task waiting on the case:

{
  "result": true,
  "IPROC_ID": 27500,
  "NEXT_ITASK_ID": 420999,
  "NEXT_ITASK_NAME": "Vyplnění objednávky",
  "taskQueue": [{ "ITASK_ID": 420999, "ITASK_NAME": "Vyplnění objednávky", "IPROC_ID": 27500 }]
}

To find out which headers the signed-in user (or the API token's user) may use, call GET /template-processes/to-start.

Task list

curl "https://vase-tas.cz/tasks?filter=itaskStateId<eq>\"1\"&limit=50" \
  -H "Authorization: Bearer <token>"

Returns the tasks that the user represented by the token is allowed to see, with the paging and filter described above. To read a single task, use GET /tasks/:id.

Completing a task

curl -X POST "https://vase-tas.cz/tasks/finish/420999" \
  -H "Authorization: Bearer <token>"

The task must be in progress for the user/token making the call; otherwise TAS responds with an insufficient permissions error. The response contains information about the next task the case has moved to.

Reading and writing task variables

curl "https://vase-tas.cz/tasks/420999/variables" \
  -H "Authorization: Bearer <token>"

curl -X POST "https://vase-tas.cz/tasks/420999/variables" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[{"id": 15321, "value": "IKEA"}]'

id is the ID of the variable on the task (ivar_id), not the ID of the template variable. Writing requires that the task is being handled by the user/token making the call.

Case variables for administrators only
The similar endpoints GET and POST /processes/:iprocId/variables read and write variables at the level of the whole case. Writing (POST) is allowed only for administrators – with a regular user API token, it fails with an insufficient permissions error. For writing from a regular integration, use task variables.

Uploading a document to a case

curl -X POST "https://vase-tas.cz/dms/upload" \
  -H "Authorization: Bearer <token>" \
  -F "iprocId=27500" \
  -F "filename=Objednavka.pdf" \
  -F "file=@./Objednavka.pdf"

The file is uploaded as multipart/form-data. Instead of iprocId, you can specify itaskId if you want to attach the document to a specific task. The caller must have permission to write documents to the case.

Related: API tokens and OAuth clients in practice, MCP server, API Access.

API Tokens and OAuth Clients in Practice

(opens in a new tab)