API v2 vs. v3

Two API versions are available to interact with your Simplicate environment. You can choose per use case. Both versions work on the same data and can be mixed.

API v2

API v2 is our most widely supported API version. It is a RESTful API that exposes Simplicate resources through CRUD actions. It offers support for a wide range of use cases, making it a reliable choice for most integrations.

In time, parts of API v2 will be deprecated and replaced by API v3. We'll ensure a smooth transition by providing clear timelines and support for deprecated v2 endpoints.

API v3

API v3 is a new RPC-style API, built following our API-first approach. It currently has a limited number of endpoints available. Its design is driven by three goals:

• Simplicity: the API is easy to understand and use.
• Clarity: it's obvious which endpoint fits your specific use case.
• Productivity: integrations can be built quickly and are easy to maintain.

What's different?

Commands instead of CRUD

API v2 lets you mutate resources directly: to change something, you update the right fields on the resource. API v3 exposes specific commands and queries, each with a clear, focused use case. You tell Simplicate what you want to do, and Simplicate works out which data changes.

For example, preparing a project service based on a default service. In v2 you fetch the default service and need to know which of its fields to copy onto a new project service:

GET /api/v2/services/defaultservice/{id}

In v3 you call the endpoint that does exactly that. It accepts only the project and the default service, and returns the project service configuration Simplicate builds from them, without storing anything yet:

POST /api/v3/projectService.build
Content-Type: application/json

{
  "projectId": "project:1234abcd",
  "defaultServiceId": "defaultservice:5678efgh"
}

This reduces complexity and minimizes the risk of errors, because you no longer need to know how a business action maps onto the fields of a resource.

Consistent terminology

API v3 follows a ubiquitous language: it uses the same terminology as the Simplicate UI and documentation, so the terms you see in the application are the terms you find in the API.

Stricter data validation

API v3 enforces a strict data model: only valid data can be persisted. This keeps the data in your environment consistent and avoids conflicts or mismatches with other Simplicate features.

Detailed error messages

API v3 returns specific, structured error messages that point out exactly which property needs to change to make your request valid.

At a glance

	API v2	API v3
Style	REST, CRUD on resources	RPC, commands and queries
Endpoints	GET /api/v2/crm/organization	GET /api/v3/organization.list
Pagination	limit / offset	page / itemsPerPage
Errors	Shape of errors differs per endpoint	One consistent format: problem details

What's the same?

• Authentication: both versions accept the same API tokens.
• Serialization: both versions use JSON.
• Shared state: both versions work on the same data. Changes made through one API are immediately visible in the other.
• Identifiers: identifiers are consistent between v2 and v3, so you can use them interchangeably. Treat them as opaque strings; you may encounter UUIDs and entity hashes such as project:1234abcd.

Which version should I use?

Use API v3 where an endpoint covers your use case, and API v2 for everything else. Because both versions share data and identifiers, a single integration can call both.