API Quick Reference

This is a condensed reference for the most common ObjectQL API operations.

Base Endpoint

POST /api/objectql
Content-Type: application/json
Authorization: Bearer <token>  (optional)

Common Operations

📋 List Records

{
  "op": "find",
  "object": "users",
  "args": {
    "fields": ["id", "name", "email"],
    "top": 20,
    "skip": 0
  }
}

🔍 Search Records

{
  "op": "find",
  "object": "products",
  "args": {
    "fields": ["id", "name", "price"],
    "filters": [
      ["category", "=", "electronics"],
      "and",
      ["price", "<", 1000]
    ],
    "sort": [["price", "asc"]]
  }
}

👤 Get Single Record

{
  "op": "findOne",
  "object": "users",
  "args": "user_123"
}

or with filters:

{
  "op": "findOne",
  "object": "users",
  "args": {
    "filters": [["email", "=", "alice@example.com"]]
  }
}

➕ Create Record

{
  "op": "create",
  "object": "tasks",
  "args": {
    "name": "Complete documentation",
    "priority": "high",
    "due_date": "2024-01-20"
  }
}

✏️ Update Record

{
  "op": "update",
  "object": "tasks",
  "args": {
    "id": "task_456",
    "data": {
      "status": "completed"
    }
  }
}

❌ Delete Record

{
  "op": "delete",
  "object": "tasks",
  "args": {
    "id": "task_456"
  }
}

🔢 Count Records

{
  "op": "count",
  "object": "orders",
  "args": {
    "filters": [["status", "=", "pending"]]
  }
}

⚡ Execute Action

{
  "op": "action",
  "object": "orders",
  "args": {
    "action": "approve",
    "id": "order_789",
    "input": {
      "notes": "Approved for expedited shipping"
    }
  }
}

Filter Operators

Operator	Description	Example
`=`	Equal	`["status", "=", "active"]`
`!=`	Not equal	`["status", "!=", "deleted"]`
`>`	Greater than	`["age", ">", 18]`
`>=`	Greater or equal	`["price", ">=", 100]`
`<`	Less than	`["stock", "<", 10]`
`<=`	Less or equal	`["rating", "<=", 3]`
`in`	In array	`["status", "in", ["pending", "active"]]`
`not in`	Not in array	`["status", "not in", ["deleted", "archived"]]`
`like`	SQL LIKE pattern	`["name", "like", "%john%"]`
`startswith`	Starts with	`["email", "startswith", "admin"]`
`endswith`	Ends with	`["domain", "endswith", ".com"]`
`contains`	Contains substring	`["tags", "contains", "urgent"]`
`between`	Between range	`["price", "between", [100, 500]]`

Combining Filters

AND Condition

{
  "filters": [
    ["status", "=", "active"],
    "and",
    ["age", ">", 18]
  ]
}

OR Condition

{
  "filters": [
    ["priority", "=", "high"],
    "or",
    ["urgent", "=", true]
  ]
}

Complex Nested Logic

{
  "filters": [
    ["status", "=", "active"],
    "and",
    [
      ["priority", "=", "high"],
      "or",
      ["overdue", "=", true]
    ]
  ]
}

Pagination

{
  "op": "find",
  "object": "posts",
  "args": {
    "top": 20,      // Page size
    "skip": 40,     // Skip first 40 (page 3)
    "sort": [["created_at", "desc"]]
  }
}

Sorting

Single Field

{
  "sort": [["created_at", "desc"]]
}

Multiple Fields

{
  "sort": [
    ["priority", "desc"],
    ["created_at", "asc"]
  ]
}

Field Selection

Specific Fields Only

{
  "fields": ["id", "name", "email"]
}

All Fields (Default)

{
  "fields": null  // or omit the fields property
}

Relationships (Expand/Join)

Basic Expand

{
  "op": "find",
  "object": "orders",
  "args": {
    "fields": ["id", "order_no", "amount"],
    "expand": {
      "customer": {
        "fields": ["name", "email"]
      }
    }
  }
}

Nested Expand

{
  "expand": {
    "customer": {
      "fields": ["name", "email"],
      "expand": {
        "company": {
          "fields": ["name", "industry"]
        }
      }
    }
  }
}

Expand with Filters

{
  "expand": {
    "orders": {
      "fields": ["order_no", "amount"],
      "filters": [["status", "=", "paid"]],
      "sort": [["created_at", "desc"]],
      "top": 5
    }
  }
}

Aggregation

{
  "op": "find",
  "object": "sales",
  "args": {
    "groupBy": ["category"],
    "aggregate": [
      {
        "func": "sum",
        "field": "amount",
        "alias": "total_sales"
      },
      {
        "func": "count",
        "field": "id",
        "alias": "num_orders"
      },
      {
        "func": "avg",
        "field": "amount",
        "alias": "avg_order_value"
      }
    ],
    "sort": [["total_sales", "desc"]]
  }
}

Aggregation Functions

count - Count records
sum - Sum values
avg - Average value
min - Minimum value
max - Maximum value

Error Handling

Validation Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "fields": {
        "email": "Invalid email format",
        "age": "Must be greater than 0"
      }
    }
  }
}

Permission Error Response

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  }
}

Not Found Response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Record not found"
  }
}

Special Variables

Use these in filters for dynamic values:

Variable	Description
`$current_user`	Current user's ID
`$current_user.role`	Current user's role
`$today`	Current date
`$now`	Current timestamp

Example:

{
  "filters": [
    ["owner", "=", "$current_user"],
    "and",
    ["due_date", "<", "$today"]
  ]
}

REST-Style Endpoints

List

GET /api/data/users?top=20&skip=0

Get One

GET /api/data/users/user_123

Create

POST /api/data/users
Content-Type: application/json
 
{"name": "Alice", "email": "alice@example.com"}

Update

PUT /api/data/users/user_123
Content-Type: application/json
 
{"role": "admin"}

Delete

DELETE /api/data/users/user_123

Metadata Endpoints

List All Objects

GET /api/metadata/objects

Get Object Schema

GET /api/metadata/objects/users

Get Field Metadata

GET /api/metadata/objects/users/fields/email

List Actions

GET /api/metadata/objects/orders/actions

Tips & Best Practices

✅ DO

Always specify fields to reduce payload size
Use pagination for large datasets
Add indexes for frequently filtered fields
Use expand instead of multiple requests
Include authentication tokens

❌ DON'T

Fetch all fields when you only need a few
Query without pagination on large tables
Make multiple requests when you can use expand
Expose sensitive fields to unauthorized users
Use raw SQL (ObjectQL prevents this by design)

Next Steps

Quick Tip: All examples use JSON-RPC format at POST /api/objectql. For REST endpoints, adapt to GET/POST/PUT/DELETE /api/data/:object.

API Quick Reference

On this page