01 Software

Response Format

API response format and type reference

Response Format

Reference for REST API and SDK response formats.

REST API Responses

List Query (Find)

GET /api/{collection}

{
  "docs": [
    {
      "id": "product_id",
      "title": "Product Name",
      "price": 10000,
      "createdAt": "2026-01-07T10:00:00Z",
      "updatedAt": "2026-01-07T10:00:00Z"
    }
  ],
  "totalDocs": 100,
  "limit": 10,
  "page": 1,
  "totalPages": 10,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}

Single Item Query (FindById)

GET /api/{collection}/{id}

{
  "id": "product_id",
  "title": "Product Name",
  "price": 10000,
  "createdAt": "2026-01-07T10:00:00Z",
  "updatedAt": "2026-01-07T10:00:00Z"
}

Create/Update

POST /api/{collection} or PATCH /api/{collection}/{id}

{
  "message": "Product created successfully",
  "doc": {
    "id": "product_id",
    "title": "Product Name",
    "price": 10000,
    "createdAt": "2026-01-07T10:00:00Z",
    "updatedAt": "2026-01-07T10:00:00Z"
  }
}

Delete

DELETE /api/{collection}/{id}

{
  "id": "product_id",
  "message": "Product deleted successfully"
}

SDK Response Types

PayloadFindResponse<T>

The type returned by the find() method.

interface PayloadFindResponse<T> {
  docs: T[]
  totalDocs: number
  limit: number
  totalPages: number
  page: number
  pagingCounter: number
  hasPrevPage: boolean
  hasNextPage: boolean
  prevPage: number | null
  nextPage: number | null
}
const response = await client.from('products').find({ limit: 10 })
// response: PayloadFindResponse<Product>

console.log(response.docs)        // Product[]
console.log(response.totalDocs)   // 100
console.log(response.hasNextPage) // true

PayloadMutationResponse<T>

The type returned by the create() and update() methods.

interface PayloadMutationResponse<T> {
  message: string
  doc: T
  errors?: unknown[]
}
const response = await client.from('products').create({ title: 'New Product', price: 10000 })
// response: PayloadMutationResponse<Product>

console.log(response.doc)     // Product
console.log(response.message) // "Product created successfully"

findById / remove Return

findById() and remove() return the document object T directly.

const product = await client.from('products').findById('id')
// product: Product

const deleted = await client.from('products').remove('id')
// deleted: Product

count Return

count() returns the document count.

const result = await client.from('products').count({
  where: { status: { equals: 'active' } }
})
// result: { totalDocs: number }

REST API Error Response

{
  "errors": [
    {
      "message": "Validation failed",
      "name": "ValidationError",
      "data": {
        "field": "email",
        "message": "Email is required"
      }
    }
  ]
}

GraphQL Error Response

{
  "errors": [
    {
      "message": "Error message",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["Products"],
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ],
  "data": null
}

HTTP Status Codes

CodeDescription
200Success
201Created
400Bad Request
401Authentication Required
403Forbidden
404Resource Not Found
429Too Many Requests
500Server Error

GraphQL Error Codes

CodeDescription
UNAUTHENTICATEDAuthentication required
FORBIDDENInsufficient permissions
BAD_USER_INPUTInvalid input
NOT_FOUNDResource not found
INTERNAL_SERVER_ERRORServer error

On this page