# Authentication — Public Read-Only API (thiensg.vn)

**Last updated: 2026-10-09**

## Do I need an API key?

**No.** This API is completely public and read-only. There is:

- **no API key**, no token, no OAuth client, no account, no sign-up;
- **no authentication header** — you do not need `Authorization`, `X-API-Key` or cookies;
- **no consent screen** — send a plain `GET` and you will receive JSON.

Nothing you can do through this API can change the website. It accepts **`GET` only**; every other
method returns `405 Method Not Allowed` with an `Allow: GET` header and a JSON error body.

## What the API returns

Only information that is **already published on the public website**: the legal entity's name, tax
code, hotline, published addresses and official Facebook page; published services, projects and
articles; and the Owner-approved reference price list. It never returns customer, lead, order,
quotation, HR or internal data, and it never exposes internal database identifiers.

**Base URL:** `https://thiensg.vn/api/v1/`

## Endpoints

| Method | Path | Returns |
|---|---|---|
| GET | `/api/v1/` | Self-describing index: name, version, endpoint list, links to spec and this document |
| GET | `/api/v1/company` | Public legal entity: legal name, tax code, hotline, email, addresses, official Facebook page |
| GET | `/api/v1/products` | Always `200` with an **empty array** on this site — thiensg.vn publishes no product catalogue (`?limit=`, `?offset=`, `?category=` are still validated) |
| GET | `/api/v1/products/{slug}` | Always `404` JSON on this site — there is no product catalogue to look up |
| GET | `/api/v1/categories` | Always `200` with an **empty array** on this site (no product catalogue) |
| GET | `/api/v1/posts` | Published services, projects and articles — `?limit=`, `?offset=` |
| GET | `/api/v1/pricing` | Reference price list, mirroring `/pricing.md` |

The kitchen brand of the same legal entity, **tubepthien.vn**, does publish a product catalogue and
is served by the same contract at `https://tubepthien.vn/api/v1/`.

Machine-readable contract: **`https://thiensg.vn/openapi.json`** (OpenAPI 3.1).
Human-readable developer resources: **`https://thiensg.vn/docs/`**.

## Rate limit

**60 requests per minute per IP address.** Responses carry `X-RateLimit-Limit`,
`X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. When you exceed the limit you get
`429 Too Many Requests` with a `Retry-After` header (seconds) — back off and retry after that delay.
Please cache responses (they include `Cache-Control`) instead of polling.

## Errors

Every error is JSON, in the same shape, including `400`, `404`, `405`, `429` and `500`:

```json
{
  "error": {
    "code": "not_found",
    "message": "Product not found",
    "status": 404,
    "documentation": "https://thiensg.vn/docs/",
    "request_id": "sg_9f3c1a2b"
  }
}
```

`code` is stable and safe to branch on: `bad_request`, `not_found`, `method_not_allowed`,
`rate_limited`, `internal_error`.

## Contact

- **Legal entity:** CÔNG TY TNHH THIẾT KẾ XÂY DỰNG NỘI THẤT THIÊN
- **Tax code:** 0316017419
- **Hotline:** 0767587878
- **Email:** tubepthien@thiensg.com
- **Showroom:** 95/13 Lương Định Của, Phường An Khánh, Thành phố Hồ Chí Minh
- **Xưởng sản xuất:** 58b Bưng Ông Thoàn, Phường Long Trường, Thành phố Hồ Chí Minh
- **Official Facebook:** https://www.facebook.com/Thien-furnituresg.vn
- **Website:** https://thiensg.vn

Questions about the API, or a request for a field that is not exposed, go to the hotline above.