REST API

Every table and view in your database is an endpoint at https://api.hornethive.io/v1/rest/{database id}/{table}. The database id is on its page in the dashboard. Each request carries an API key from Settings → API keys as Authorization: Bearer <key>.

A key has the read scope, or read and write, and can be limited to one database or to a list of IP addresses. A read key can be used from the browser, from the origins you register; keep write keys on your server. The syntax follows PostgREST, so tools and habits from it carry over; the differences are listed at the end.

The API used to be at https://hornethive.io/api/…. Until 7 November 2026 it still answers, with Deprecation and Sunset headers and a Link to the same call here; from that day (midnight, Malaysia time) it answers 410 with the new address. Drop the /api and change the host: hornethive.io/api/rest/… is api.hornethive.io/v1/rest/….

GET /{table} returns an array of rows. select picks the columns, limit takes 1 to 1,000 rows (10 when left out), and offset skips rows for paging. GET /{table}/{key} returns one row by its primary key; a view, or a table without one, matches a column named id.

Lists are cached for 5 minutes and cleared by any write through the API. A write made straight to Postgres (psql, an ORM) is not seen by the cache, so a list can be up to 5 minutes old after one. The X-Cache header says HIT or MISS.

A filter is column=operator.value. Filters on different columns, and repeats of one column, must all match. A value with no operator is equality, so status=active still works as it always has.

In an in list or an or group, put double quotes around a value that holds a comma or a parenthesis: in.("Kuala Lumpur, MY",Ipoh). Values are sent to Postgres as parameters, never as SQL.

or=(…) matches rows that pass any of its conditions, written column.operator.value and separated by commas. Groups nest with and(…) and or(…), and not. negates one: not.and=(…), or=(a.eq.1,not.and(b.gt.2,c.is.null)).

order=col.desc,other.asc sorts by one column or more; each takes asc or desc, and nullsfirst or nullslast. The older orderBy=col&order=desc still works.

Send Prefer: count=exact for the number of matching rows in the Content-Range header, as first-last/total: 0-19/240. Without it the total is *. Browsers can read the header from your registered origins.

POST /{table} with a JSON object inserts one row and returns it; with an array it inserts them all in one statement and returns an array. Each value takes its column's type: a JSON object fills a jsonb column, a JSON array a Postgres array, a string a timestamp or a bytea written as \x0102. Needs the write scope.

The columns are every key that appears in any row. A column that no row names takes its default; a column that some rows leave out is NULL in those rows, as in PostgREST, so send the same keys in every row when a column has a default. select picks the columns returned, and Prefer: return=minimal returns nothing.

Add Prefer: resolution=merge-duplicates to update the rows whose key already exists and insert the rest, or resolution=ignore-duplicates to leave existing rows alone. The key is the primary key; on_conflict=email names another unique column or columns. Only the columns you send are changed.

PATCH /{table} sets the columns in the JSON body on every row that matches the filters, and returns those rows. DELETE /{table} removes them and returns {"deleted": n}, or the rows themselves with Prefer: return=representation. Both take any filter above, and both refuse a request with no filter, so one call cannot change a whole table by accident.

POST /rpc/{function} calls a Postgres function with named arguments from the JSON body; GET /rpc/{function}?arg=value does the same read-only. A function that returns a set gives an array of rows, a composite type an object, a scalar its value, and void an empty 204.

A key without the write scope runs the function in a read-only transaction, as does every GET, so it cannot change data. Use functions for joins, aggregates and anything else a single table cannot express.

Tables are read from the public schema. Accept-Profile: shop reads from another schema, and Content-Profile: shop writes to it, for tables and functions alike. Postgres's own schemas (pg_catalog, information_schema) are not served.

POST /query runs one SQL statement with $1, $2… parameters and returns {"columns": [...], "rows": [...]}. A key without the write scope runs it in a read-only transaction.

Integers, floats and booleans are JSON numbers and booleans. Timestamps and dates are ISO 8601 strings. numeric is a string, so no digit is lost. json and jsonb come back as a JSON string to parse; arrays in their Postgres text form, such as {red,blue}; bytea as hex. The OpenAPI document below states each column's type.

A refused request answers {"error": "…"}. When Postgres refused the statement the body also has code, its SQLSTATE, and details and hint when it gave them.

400 is a bad request or statement, 401 a missing or wrong key, 403 a key without the scope or for another database (or a privilege Postgres refused), 404 no such database, table, function or row, 409 a unique or foreign key conflict, and 429 the rate limit.

GET /openapi.json returns an OpenAPI 3.1 document for your database, built from its schema when you ask: every table with its columns and types, which ones are required on insert, the primary keys, and every function with its arguments. With Accept-Profile it describes another schema. Load it in Swagger UI, Postman or Insomnia, or generate a typed client with openapi-generator or openapi-typescript.

The same operations for any database, with no key needed, are at https://api.hornethive.io/v1/rest/openapi.json.

@hornetcloud/hive-js wraps all of this: every filter above, or(), getWithCount(), bulk insert(), upsert(), rpc(), schema() and openapi().

• No embedded relations (select=*,orders(*)): join in a view or a function. The GraphQL API does not follow foreign keys either.
• No JSON paths in select or filters (data->>name), and no aliases or casts in select.
• limit is 1 to 1,000 and 10 by default; PostgREST has no default. Page with offset and the count.
• No Range request header, no CSV or single-object responses, and only count=exact.
• A value with no operator is equality, where PostgREST refuses it.
• Lists are cached for up to 5 minutes, as above; PostgREST does not cache.
• Every key acts as the database's owner. Row-level security has no per-user role to act on, so keep write keys on your server.
• POST /query runs SQL, which PostgREST does not offer.