> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jitra.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Jitra Public API

> Integrasikan Jitra Public API untuk membaca Objects, Positions, Geofences, Sites, dan Routes dari Organization Anda.

Jitra Public API menyediakan akses read-only ke data Organization seperti Objects, Positions, Geofences, Sites, dan Routes.

## Sebelum memulai

Siapkan hal berikut:

* API key yang valid untuk Organization Anda
* akses jaringan ke host API melalui HTTPS
* HTTP client seperti cURL, Postman, atau library HTTP

## Base URL dan versioning

Gunakan public base URL yang memiliki versi:

```text theme={null}
https://api.jitra.app/public/v1
```

Tambahkan resource path yang ditampilkan pada setiap halaman endpoint.

## Autentikasi

Semua endpoint memerlukan API key. Kirim key dengan salah satu header berikut:

```text theme={null}
x-api-key: <api_key>
Authorization: Bearer <api_key>
```

Lihat [Autentikasi](/id/api-reference/authentication) untuk contoh dan panduan keamanan.

## Rate limit

Request dibatasi per Organization.

| Pengaturan | Nilai |
| - | - |
| Jendela waktu | 10 detik |
| Maksimum | 10 request per jendela |

API mengembalikan `429 Too Many Requests` jika batas terlampaui. Batas penggunaan API per Object juga dapat berlaku pada endpoint posisi.

## Format respons

Respons sukses berisi `statusCode` dan `result`. Result dapat berupa object atau array, bergantung pada endpoint.

```json theme={null}
{
  "statusCode": 200,
  "result": {}
}
```

Error menggunakan wrapper yang konsisten:

```json theme={null}
{
  "statusCode": 400,
  "errorCode": "PUBLIC.400_001",
  "message": "Validation error message",
  "timestamp": "2026-05-17T01:00:00.000Z"
}
```

## Quickstart workflow

<Steps>
  <Step title="Verifikasi API key">
    Mulai dari daftar Object karena endpoint ini tidak memiliki path atau query parameter.

    ```bash theme={null}
    curl --request GET \
      --url https://api.jitra.app/public/v1/objects \
      --header 'x-api-key: <api_key>'
    ```
  </Step>

  <Step title="Baca satu Object">
    Gunakan `id` yang dikembalikan oleh request pertama.

    ```bash theme={null}
    curl --request GET \
      --url https://api.jitra.app/public/v1/objects/101 \
      --header 'x-api-key: <api_key>'
    ```
  </Step>

  <Step title="Baca posisi terbaru">
    Minta beberapa Object ID dalam satu request.

    ```bash theme={null}
    curl --request GET \
      --url 'https://api.jitra.app/public/v1/positions/latest?ids=101,102' \
      --header 'x-api-key: <api_key>'
    ```
  </Step>
</Steps>

## HTTP outcome umum

| Status | Arti | Tindakan |
| - | - | - |
| `200` | Request berhasil. | Proses `result`. |
| `400` | Input request tidak valid. | Perbaiki path atau query value. |
| `401` | Autentikasi gagal. | Periksa API key dan format header. |
| `404` | Resource tidak ditemukan. | Pastikan resource milik Organization. |
| `429` | Rate limit terlampaui. | Tunggu dan ulangi dengan backoff. |

## Integration checklist

* Simpan API key di secrets storage yang aman, bukan di source code.
* Gunakan HTTPS di semua environment.
* Tambahkan retry dan backoff untuk `429`.
* Catat status respons dan request identifier yang tersedia di client.
* Proses datetime sebagai timestamp ISO 8601 UTC.