Get started

Requests & errors

How every Bitaloka endpoint takes input and reports results — learn it once, use it everywhere.

Base URL

https://api.bitaloka.io/v1

All endpoints are versioned under /v1 and served over HTTPS only.

Sending input

Path — identifiers go straight into the URL, e.g. GET /v1/nik/{nik}.
JSON body — text services take Content-Type: application/json.
Multipart form — PDF and image tools take multipart/form-data with file (or several files) plus options as text fields.

What comes back

Parsers, lookups and AI return JSON. PDF tools return the processed file (application/pdf, or application/zip for split) — write the body straight to disk.

Invalid input is not an error

A malformed NIK still gets HTTP 200, with valid: false and an errors list that explains why. Branch on valid, not on the status code.

GET /v1/nik/123 → 200 OK

{
  "valid": false,
  "input": "123",
  "normalized": "123",
  "gender": null,
  "birthDate": null,
  "region": null,
  "serial": null,
  "genderConsistent": false,
  "summary": "",
  "errors": [
    {
      "code": "INVALID_FORMAT",
      "message": "NIK must be exactly 16 digits"
    }
  ],
  "warnings": []
}

Errors

Real failures use standard HTTP status codes and a JSON body {"error": "…"}.

Status	Meaning
`400`	Missing or malformed input — e.g. no file, or an invalid page range.
`401`	API key missing or not recognised (once keys are enforced).
`413`	Upload larger than 60 MB.
`503`	A dependency is briefly unavailable. Retry with exponential backoff.

Limits

Uploads up to 60 MB per request. Batch parsing takes up to 100 items per call.

Calling from a browser

CORS is open, so web pages can call the API directly. Never ship a secret key in front-end code — call through your own server instead.