Quick Start

Get from zero to your first live API response in 5 minutes.

What you need

• A running Minimal server
• Your server_key from config.yml
• A MySQL, PostgreSQL, MariaDB, or ClickHouse database with at least one table

---

Step 1 — Create an Organization

An organization is the top-level container for everything in Minimal. Run this once — if it already exists, the 208 response is safe to ignore.

curl --location 'https://<your-domain>/minimal/system/api/v1/org' \
--header 'X-User-Id: <your-user-id>' \
--header 'X-Server-Key: <your-server-key>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "AcmeLabs",
    "abbreviation": "acme",
    "admin_email": "admin@acme.com",
    "admin_name": "Admin",
    "address": "Bengaluru",
    "state": "Karnataka",
    "country": "India",
    "pin_code": "560001"
}'

✅ Expected response:

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

org_id is optional

If you omit org_id, Minimal generates one for you automatically. Only pass it if you need to control the ID yourself — for example when migrating an existing setup.

Note down the org_id and org_abbreviation from the response — you will need them in Steps 2 and 3.

---

Step 2 — Create a Project

A project connects Minimal to your database. Replace the database fields with your actual credentials.

curl --location 'https://<your-domain>/minimal/system/api/v1/project' \
--header 'X-Org-Id: <your-org-id>' \
--header 'X-User-Id: <your-user-id>' \
--header 'X-Server-Key: <your-server-key>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "My First Project",
    "abbreviation": "mfp",
    "description": "Connecting to my app database",
    "database": [
        {
            "host_details": [{ "host": "localhost", "port": "3306" }],
            "username": "<db-username>",
            "password": "db-****",
            "db_name": "<db-name>",
            "db_type": "mysql",
            "connect_timeout_secs": 60,
            "idle_timeout_secs": 900,
            "max_open_connections": 50,
            "max_idle_connections": 25
        }
    ]
}'

✅ Expected response:

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

Note down the project_id, project_abbreviation, and space_id from the response — every Auto API call needs them.

---

Step 3 — Make Your First API Call

You now have everything needed. Query any table in your database:

curl --location 'https://<your-domain>/minimal/api/rest/auto/v1/<org-abbr>/<project-abbr>/ms/<db-name>/<table-name>?pg=0&ps=10' \
--header 'X-Org-Id: <your-org-id>' \
--header 'X-Project-Id: <your-project-id>' \
--header 'X-Space-Id: <your-space-id>' \
--header 'X-User-Id: <your-user-id>' \
--header 'X-User-Roles: admin'

✅ Expected response:

[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob",   "email": "bob@example.com" }
]

---

URL Structure at a Glance

https://<your-domain>/minimal/api/rest/auto/v1/{org_abbr}/{project_abbr}/{db_type}/{db_name}/{table}
                                                     │            │           │         │        │
                                                     │            │           │         │        └── table name
                                                     │            │           │         └── database name
                                                     │            │           └── ms = MySQL   pg = PostgreSQL
                                                     │            │               ma = MariaDB  ch = ClickHouse
                                                     │            └── project abbreviation
                                                     └── org abbreviation

---

All 4 Operations — Quick Reference

Once Step 1–3 work, all four REST operations follow the same pattern:

List rows:

GET .../v1/<org-abbr>/<project-abbr>/<db-type>/<db-name>/<table>?pg=0&ps=10

Create a row:

POST .../v1/<org-abbr>/<project-abbr>/<db-type>/<db-name>/<table>
Body: [{ "name": "Alice", "email": "alice@example.com" }]

Update a row:

PUT .../v1/<org-abbr>/<project-abbr>/<db-type>/<db-name>/<table>?id=eq.1&set=name.OldName%20NewName

Delete a row:

DELETE .../v1/<org-abbr>/<project-abbr>/<db-type>/<db-name>/<table>?id=eq.1

---

Headers Cheat Sheet

Header	Required for	Where it comes from
X-Org-Id	Auto API	Returned in Step 1 response
X-Project-Id	Auto API	Returned in Step 2 response
X-Space-Id	Auto API	Returned in Step 2 response
X-User-Id	All APIs	Your auth system
X-User-Roles	Auto API	Your auth system
X-Server-Key	System API only	config.yml → service.server_key

---

Something went wrong?

Symptom	Likely cause	Fix
417 on org creation	A mandatory field is missing from the body	All 8 fields are required: name, abbreviation, admin_email, admin_name, address, state, country, pin_code
424 Failed Dependency	abbreviation is too long	Keep abbreviation to 5 characters max
400 Bad Request	Missing or malformed header or body	Check all required headers are present
401 Unauthorized	X-User-Id missing	Add X-User-Id header
403 Forbidden	Wrong X-Server-Key	Check server_key in config.yml
406 Not Acceptable	Missing pg or ps on GET	Add ?pg=0&ps=10 to the URL
417 Expectation Failed	Invalid filter operator or missing field	Check operator list in Filtering & Pagination
CORS error in browser	Minimal not reachable from browser	Check nginx CORS config — see How Minimal Works