# Welcome to CATAPA API Documentation

This site contains the technical resources required to build integrations with the CATAPA HRIS platform.

## Quick Start!

Copy code below and see it in action!

{% tabs %}
{% tab title="Python" %}

```bash
uv add catapa
```

```python
from catapa import Catapa

client = Catapa(tenant="zfrl", client_id="demo", client_secret="demo-secret")
employees = client.core.employees.list(page=0, size=10)

print(f"Found {len(employees.content)} employees")
```

{% endtab %}

{% tab title="cURL" %}

```shellscript
# If you have jq installed, copy code below right away.
# If not, copy token manually.
TOKEN=$(curl -s https://api.catapa.com/oauth/token \
  -u "demo:demo-secret" \
  -H "Tenant: zfrl" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" | jq -r '.access_token')

# Get Employees
curl https://api.catapa.com/core/v1/employees \
  -H "Authorization: Bearer $TOKEN" \
  -H "Tenant: zfrl"
```

{% endtab %}
{% endtabs %}

You should see something like this as a response

```json
{
  "content": [ ... ],
  "totalPages": 3,
  "totalElements": 21,
  "numberOfElements": 10,
  "size": 10,
  "number": 0,
  "first": true,
  "last": false
}
```

If you see that response in your terminal, you have successfully

* Exchanged your credentials for a Bearer Token.
* Passed that token through the Authorization Header.
* Retrieved live data from the Catapa Core API.

Congratulations :tada:

## Who is this documentation for?

You are in the right place if you are a **software engineer building a third-party integration.**

If you're here to learn about the product, then go to [CATAPA HRIS](https://gdplabs.gitbook.io/catapa/catapa-hris/catapa-services)

## Our Integration Options

To access CATAPA's resources, you have two integration options.

### Python SDK

{% hint style="warning" %}
Our Python SDK is currently in **beta**. Please be aware that breaking changes may occur in future updates as we continue to refine and improve the experience.
{% endhint %}

Our Python SDK is the fastest way to integrate with CATAPA. If your tech stack is already using python, you might consider using this Python SDK as you get native Type Safety and Automated Authentication.

Our **SDK is an exact mirror of our Public API**—if an endpoint exists in our documentation, a corresponding method exists in the SDK. Check full documentation here.

You can see example by choosing "Python SDK"

<figure><img src="/files/9JStLB4SGcjHmnCHKxLg" alt=""><figcaption><p>choose the "Python SDK" in the example dropdown</p></figcaption></figure>

### REST API

Standard JSON over HTTPS. Use this for lightweight integrations or if you prefer full control over your HTTP client.

#### Protocol & Format

* RESTful Design: We utilize standard HTTP methods: `GET` for retrieval, `POST` for creation, `PUT` for updates, and `DELETE` for removal.
* Data Exchange: All request and response bodies use the JSON format.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gdplabs.gitbook.io/catapa-api/get-started/welcome-to-catapa-api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.