HTTP API

The SDKs are thin wrappers over this HTTP API, so anything they do you can do with curl, fetch or any HTTP client. All bodies are JSON unless a route says otherwise.

#Base URL and project

Send requests to your project URL, https://<project-ref>.sovaria.in (shown in the console under Connect). The project URL already identifies the project, so you never send project ids.

Tools that manage several projects can call https://api.sovaria.in instead, adding X-Sovaria-Org-ID and X-Sovaria-Project-ID headers. A key only works for the project it belongs to, whichever host you use.

#Authentication

Access tokens last 15 minutes. Exchange the refresh token for a new pair before they expire (POST /api/v1/auth/refresh); the SDKs do this automatically.

#Sign up, sign in and sessions

URL=https://<project-ref>.sovaria.in
ANON=<anon-key>

curl -s -X POST $URL/api/v1/auth/register -H "apikey: $ANON" \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"a-long-passphrase","name":"Ada"}'

TOKEN=$(curl -s -X POST $URL/api/v1/auth/project/login -H "apikey: $ANON" \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"a-long-passphrase"}' | jq -r .access_token)

Magic links, email codes, password reset and social sign-in are covered in Authentication overview.

#Database (SQL)

POST /api/v1/sql/query runs one SELECT, INSERT, UPDATE, DELETE or EXPLAIN. Pass values as params for $1, $2, …; they are bound by the database and never become part of the SQL. Schema changes (CREATE, ALTER, DROP) belong in the SQL editor or Migrations, not in app code.

curl -s -X POST $URL/api/v1/sql/query \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"sql":"select id, body from notes where id = $1","params":[42]}'

Rows are arrays in the order of columns. For UPDATE and DELETE, row_count is the number of rows changed — 0 when row-level security hid every row from the caller.

#Documents

#Storage

curl -s -X POST $URL/api/v1/store/objects/avatars/$USER_ID/me.png \
  -H "Authorization: Bearer $TOKEN" -F file=@me.png

curl -s -X POST $URL/api/v1/store/objects/avatars/$USER_ID/me.png/sign-download \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"expires_in":600}'

#Realtime

#Functions

POST /functions/v1/{name} calls a deployed function. The JSON body becomes event; the caller (user, anon or key) becomes context.caller. The response is whatever the function returns.

curl -s -X POST $URL/functions/v1/order-total \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"items":[{"sku":"BK-1","qty":2}]}'

#Errors

Errors use standard status codes. The body always has detail: a sentence, or an object with a code for errors you may want to handle in code. Some gateway errors also carry code and trace_id at the top level — include the trace_id (or the X-Request-ID response header) when you contact support.

#Rate limits

Requests are limited per project and per caller; the limits grow with your plan. Rate-limited responses are 429 with Retry-After, X-RateLimit-Limit and X-RateLimit-Reset headers (and X-RateLimit-Remaining where it applies). Retry with exponential backoff rather than in a tight loop.

#Everything else

Organizations, members, policies, billing, function management and the rest are listed with their routes in the JavaScript SDK reference and Python SDK reference (each method shows the HTTP route it calls).