Org Management

Create, retrieve, and update organisations in Minimal. All System API endpoints require X-Server-Key from your config.yml.

---

Create an Organisation

Register a new organisation. If it already exists, 208 Already Reported is returned — safe to ignore.

Request Body

Field	Type	Required	Description
org_id	string	❌ No	If omitted, Minimal auto-generates a ULID
name	string	✅ Yes	Full name of the organisation
abbreviation	string	✅ Yes	Short identifier — max 5 characters
admin_email	string	✅ Yes	Admin email address
admin_name	string	✅ Yes	Admin display name
address	string	✅ Yes	Street address
state	string	✅ Yes	State or province
country	string	✅ Yes	Country
pin_code	string	✅ Yes	Postal / ZIP code

Response

201 Created:

{
  "code": 201,
  "status": "Created",
  "message": "organisation created successfully"
}

208 Already Reported — org already exists, safe to proceed:

{
  "code": 208,
  "status": "Already Reported",
  "message": "organisation already exists"
}

---

Get Org Details

Returns details of a specific organisation.

Required Headers

Header	Description
X-Org-Id	Organisation identifier
X-User-Id	Authenticated user's identifier
X-User-Roles	Comma-separated roles (e.g., admin,user)
X-Server-Key	Server key from config.yml

---

Get All Orgs

Returns a list of all organisations on the server.

Required Headers

Header	Description
X-User-Id	Authenticated user's identifier
X-Server-Key	Server key from config.yml

---

Update Org Details

Updates an existing organisation. Pass org_id in the body to identify which org to update.

Request Body

Field	Type	Required	Description
org_id	string	✅ Yes	ID of the org to update
name	string	✅ Yes	Updated organisation name
abbreviation	string	✅ Yes	Short identifier — max 5 characters
admin_email	string	✅ Yes	Admin email address
admin_name	string	✅ Yes	Admin display name
address	string	✅ Yes	Street address
state	string	✅ Yes	State or province
country	string	✅ Yes	Country
pin_code	string	✅ Yes	Postal / ZIP code

Response

200 OK:

{
  "code": 200,
  "status": "OK",
  "message": "organisation updated successfully"
}

---

Common Errors

Code	Cause
400	Missing or malformed request body
401	Missing X-User-Id header
403	Invalid or missing X-Server-Key
208	Organisation already exists — safe to ignore on create
417	A required field is missing
424	abbreviation is too long — keep to 5 characters max