Response Format

All Shobdo API endpoints return a consistent JSON envelope. This makes it easy to build generic error handling and response parsing logic in your applications.

Standard Envelope

{
  "ok": true,
  "data": { ... },
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "took_ms": 38
  }
}

Envelope Fields

Field	Type	Present	Description
`ok`	boolean	Always	`true` for successful requests, `false` for errors.
`data`	object \| array	On success	The response payload. An array for list endpoints (search), an object for single-resource endpoints (entry).
`meta`	object	On success (list endpoints)	Pagination and performance metadata.
`error`	string	On failure	A human-readable error message describing what went wrong.

Meta Object

The meta object is included in list responses (e.g., search results) and contains:

Field	Type	Description
`total`	integer	Total number of results matching the query.
`limit`	integer	The maximum number of results returned in this response.
`offset`	integer	The number of results skipped (for pagination).
`took_ms`	integer	Server-side processing time in milliseconds.

Pagination

Use limit and offset to paginate through large result sets:

# Page 1 (first 20 results)
GET /api/v1/search?q=hello&limit=20&offset=0
 
# Page 2 (next 20 results)
GET /api/v1/search?q=hello&limit=20&offset=20
 
# Page 3
GET /api/v1/search?q=hello&limit=20&offset=40

Pagination Logic

You have reached the last page when offset + data.length >= meta.total.

Error Responses

When a request fails, the envelope looks like this:

{
  "ok": false,
  "error": "Missing required parameter: q"
}

See the Error Codes page for a full list of possible errors.

Ctrl+I

Assistant

Hi! I'm the Shobdo Assistant.
Ask me anything about the documentation.