Onyx Cloud Database API Documentation

Use this endpoint to create or update one or more entities in a table.

Example

Insert or update a record with id = "123":

PUT https://api.onyx.dev/data/{databaseId}/{MyTable}
Content-Type: application/json
x-onyx-key: YOUR_KEY
x-onyx-secret: YOUR_SECRET

[
  {
    
    id": "123",
    "name": "Sample Entity",
    "description": "A descriptive sample entity."
  }
]

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "123",
    "name": "Sample Entity",
    "description": "A descriptive sample entity."
  }
]

Fetch a single record by its primary key. Optional parameters let you specify a partition or fetch related data.

Example

GET https://api.onyx.dev/data/{databaseId}/{MyTable}/123?fetch=relatedData
x-onyx-key: YOUR_KEY
x-onyx-secret: YOUR_SECRET

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "123",
  "name": "Sample Entity",
  "description": "A descriptive sample entity.",
  "relatedData": [
    {
      "id": "rel-1",
      "info": "Related item info"
    }
  ]
}

Remove a single record by its primary key.

Example

DELETE https://api.onyx.dev/data/{databaseId}/{MyTable}/123
x-onyx-key: YOUR_KEY
x-onyx-secret: YOUR_SECRET

Response: If successful:

HTTP/1.1 200 OK

Perform advanced queries to fetch data that meets certain conditions. Provide a SelectQuery in the request body.

Endpoint

SelectQuery Structure

Paging Support

When specifying a pageSize parameter, if the total records exceed the specified pageSize, the results will be returned in pages. The response will include a nextPage token if more records remain. To retrieve subsequent pages, send another request with the nextPage token as a query parameter.

• If pageSize is greater than 1000, a 400 Bad Request is returned with an error message.
• If the provided nextPage token is invalid or expired, a 404 Not Found is returned.
• If nextPage is omitted, a fresh query is executed and, if needed, caching and paging are set up.

QueryCriteriaOperator

Operators define how to match field values (e.g., EQUAL, NOT_EQUAL, IN, LIKE, etc.).

Example (Without Paging)

Query all records where name equals "Sample Entity":

PUT https://api.onyx.dev/data/{databaseId}/query/{MyTable}
Content-Type: application/json
x-onyx-key: YOUR_KEY
x-onyx-secret: YOUR_SECRET

{
  "conditions": {
    "criteria": {
      "field": "name",
      "operator": "EQUAL",
      "value": "Sample Entity"
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "records": [
  {
    "id": "123",
    "name": "Sample Entity",
    "description": "A descriptive sample entity."
  }
  ],
  "totalRecords": 1,
  "nextPage": null
}

Example (With Paging)

Suppose you have many matching records and want them in batches of 50. Set pageSize=50:

PUT https://api.onyx.dev/data/{databaseId}/query/{MyTable}?pageSize=50
Content-Type: application/json
x-onyx-key: YOUR_KEY
x-onyx-secret: YOUR_SECRET

{
  "conditions": {
    "criteria": {
      "field": "status",
      "operator": "EQUAL",
      "value": "Active"
    }
  }
}

Response (First Page):

HTTP/1.1 201 Created
Content-Type: application/json

{
  "records": [
    { "id": "100", "name": "Entity A", "status": "Active" },
    { "id": "101", "name": "Entity B", "status": "Active" },
    ...
    // 50 records total
  ],
  "totalRecords": 2000,
  "nextPage": "a1b2c3d4|1" // A token to fetch the next page
}

To fetch the next page, use the returned nextPage token:

PUT https://api.onyx.dev/data/{databaseId}/query/{MyTable}?nextPage=a1b2c3d4|1
Content-Type: application/json
x-onyx-key: YOUR_KEY
x-onyx-secret: YOUR_SECRET

This will return the next batch of 50 records and possibly another nextPage token if more records remain.

Use an UpdateQuery to update multiple records that match certain conditions.

UpdateQuery Structure

Example

Update all records where name equals "Sample Entity":

PUT https://api.onyx.dev/data/{databaseId}/query/update/{MyTable}
Content-Type: application/json
x-onyx-key: YOUR_KEY
x-onyx-secret: YOUR_SECRET

{
  "conditions": {
    "criteria": {
      "field": "name",
      "operator": "EQUAL",
      "value": "Sample Entity"
    }
  },
  "updates": {
    "description": "Updated description for all matching records."
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "updatedCount": 5
}

Use a SelectQuery to identify which records to remove.

Example

Delete all records where name equals "Obsolete Entity":

PUT https://api.onyx.dev/data/{databaseId}/query/delete/{MyTable}
Content-Type: application/json
x-onyx-key: YOUR_KEY
x-onyx-secret: YOUR_SECRET

{
  "conditions": {
    "criteria": {
      "field": "name",
      "operator": "EQUAL",
      "value": "Obsolete Entity"
    }
  }
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "deletedCount": 2
}

This endpoint allows you to subscribe to real-time changes in query results. You submit a SelectQuery, and the server streams updates as records are created, updated, or deleted. The stream also periodically sends keep-alive messages.

Example

The following request sets up a stream for a query. If includeQueryResults=true, the current matching records are sent first. As changes occur (creation, updates, or deletions), the server sends new JSON lines.

PUT https://api.onyx.dev/data/{databaseId}/query/stream/{MyTable}?includeQueryResults=true
Content-Type: application/json
x-onyx-key: YOUR_KEY
x-onyx-secret: YOUR_SECRET

{
  "conditions": {
    "criteria": {
      "field": "name",
      "operator": "EQUAL",
      "value": "Active Entity"
    }
  }
}

Response: This endpoint returns a stream of JSON objects, one per line. Each object has an action field indicating the event type:

• QUERY_RESPONSE: Initial records that matched your query.
• CREATE: A new record was added that matches your query.
• UPDATE: An existing matching record was updated.
• DELETE: A matching record was removed.
• KEEP_ALIVE: A periodic message to keep the connection alive.

HTTP/1.1 200 OK
Content-Type: application/json

{"action":"QUERY_RESPONSE","entity":{"id":"123","name":"Active Entity","description":"Currently active record"}}
{"action":"KEEP_ALIVE","entity":null}
{"action":"CREATE","entity":{"id":"124","name":"Active Entity","description":"A newly created matching record"}}
{"action":"UPDATE","entity":{"id":"123","name":"Active Entity","description":"Updated description"}}
{"action":"DELETE","entity":{"id":"124","name":"Active Entity","description":"A newly created matching record"}}
{"action":"KEEP_ALIVE","entity":null}
...

You can continue reading from the stream as long as the connection remains open. The client should handle each line as it arrives.

The Onyx Cloud Database API also allows you to save and serve binary documents (such as images, PDFs, etc.) associated with your database. These documents are stored separately from your tabular data and can be retrieved as needed.