# BSGAI V9.8 Unified Gateway — developer reference

Base URL `https://YOUR-BSGAI-DOMAIN` (replace with the real deployed site; no made-up domain).

## Read: no API token required

| Method | Endpoint | Purpose |
|---|---|---|
| GET | `/api/v1/alliances` | Four alliance types and published counts |
| GET | `/api/v1/alliances/GBA/companies?locale=en&page=1&limit=12` | GBA published directory; repeat for `HWA`, `SGREA`, `SGAA` |
| GET | `/api/v1/alliances/SGAA/companies/your-studio-slug?locale=zh` | One approved studio/company record |

Supported `locale`: `zh,en,ja,ar,es,vi,de,ko,id,fr`; fallback to `zh` / `en` when an individual translation is missing. `limit` defaults to 12, maximum 50. `page` starts at 1. `search` and `region` are optional public list filters. No data is invented if the directory is empty. Public GET has `Access-Control-Allow-Origin: *` and `ETag` responses.

## Write: authenticated company server only

```bash
curl -X POST 'https://YOUR-BSGAI-DOMAIN/api/v1/alliances/SGAA/companies/your-studio-slug/sync' \
  -H "Authorization: Bearer $BSGAI_COMPANY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"name":{"en":"Shangyuan Art Studio"},"description":{"en":"Our portfolio"},"website":"https://your-real-site.example"}'
```

The bearer secret is created after company admin activation in `/company-portal/`; use a protected backend env variable, never in public JavaScript. Only the matching company and alliance can be modified. `202 Accepted` means queued for BSGAI central review, **not publicly synchronized**. After admin approval, the approved data appears in GET endpoints.

Invalid or unauthorized requests return `400`, `401`, `403`, `404`, `405` as appropriate. Public GET and POST CORS policies differ on purpose; do not send company API keys from a browser frontend. A company account itself must first be provisioned by BSGAI central admin via `/member-admin/`.

## Data contract

- Public directory returns `version`, `alliance`, `locale`, `total`, `page`, `limit`, `hasNext` and `items`.
- A company summary has `slug`, `alliance`, multilingual name, tagline, sector, region, website, cover, role, updatedAt, profileUrl, apiUrl.
- Public details return only a published company's existing public view and localized display fields. Private pledge reference IDs are excluded.
- Enterprise update request may supply standard editable V9.7 fields `name`, `description`, `tagline`, `products`, `terms`, `sector`, `region`, `website`, `youtube`, `price`, `currency`, `contactName`, `phone`, `email`, `images`. Immutable central fields `alliance`, `status`, `role`, `pledge` are ignored/rejected by legacy sanitization policy.