API Convention

Base URL

First things first, as stated, we are using REST API as our convention. We tried our best to follow the standard defined by the RFC as our contract.

All API requests must be made over HTTPS. To ensure data security, plain HTTP requests are not supported and will be rejected.

Our Base URL which will be used throughout all endpoint is https://api.catapa.com

To maintain consistency across our ecosystem, we follow these architectural and formatting standards:

JSON & Data Standards

• Property Naming: We use camelCase for all JSON property names (e.g., employeeName, not employee_name).

• Date & Time: All timestamps are represented in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

• Identifiers: Global identifiers are provided as UUID strings (78257029-1f0b-4e9a-96c6-d1b66db793d9)

• Null Handling: To keep responses lean, fields with no value are generally returned as null , rather than empty strings ("") or being omitted entirely.

---

Pagination

We are dealing with thousands of data, and for that, many of our endpoint is paginated to keep the system fast and efficient.

For endpoints returning lists of data, we use a zero-based offset pagination model. Use the page and size query parameters to navigate results.

• page: The page number to retrieve (starts at 0).

• size: Number of elements per page (Maximum: 50).

Pagination Response Format

{
  "content": [ { ... }, { ... } ],
  "number": 0,
  "size": 10,
  "numberOfElements": 10,
  "totalElements": 100,
  "totalPages": 10
}

---

Search & Filtering

We have a very powerful and flexible search and filtering capability.

We are using a URL parameter with the key query. The syntax follows a <key><operator><value> pattern. With this structure, you can form a very complex query. Let's take a look at an example to see it in action

If you want to find all employee that have "John" in it's name, you can use

GET api.catapa.com/core/v1/employees?query=name:John

Or if you want to find all employee that have the name "John Doe" and have start date after 2020, you can use the following

GET api.catapa.com/core/v1/employees?query=Name:John%20Doe,startDate>2020-01-01

This capability present almost across all our GET endpoints. the supported key for every endpoint is not the same. If you want to know what key's that are supported by a certain endpoint, check the detail for each endpoint.

Here are all of the operators that we use

• : : Equal / Like (Search)

• > : Greater than or equal to

• < : Less than or equal to

• , : Logical AND

Lets take a look at a couple more example to help get a better grasp at the structure

Search Goal	Query Parameter
Exact ID	?query=identificationNumberIn:1111
Multiple IDs	?query=identificationNumberIn:1111;2222
Partial Name	?query=name:John%20Doe
Date Range	?query=startDate>2020-01-01,startDate<2020-12-31

---

Rate Limits

To ensure system stability and fair usage, the following limit is enforced

400 requests per minute, per Client ID.

Exceeding this limit will trigger an HTTP 429 (Too Many Requests) error. If you encounter this, please wait for a while before hitting the endpoint again.

If you require a higher limit for a specific integration, please contact our support team [e-mail]