Jomioz REST API Reference: Base URLs, Requests & Errors

The Jomioz REST API gives you full programmatic control over every feature available in the dashboard — manage users, create and update resources, subscribe to events, and configure integrations, all from your own code. Every endpoint follows REST conventions: predictable URL structures, standard HTTP verbs, and JSON request and response bodies.

Base URL

All API requests target a versioned base URL. Use the production URL for live workloads and the sandbox URL for testing without affecting real data.

Production:  https://api.jomioz.com/v1
Sandbox:     https://sandbox.api.jomioz.com/v1

The Jomioz API is stable at v1. Any backward-compatible changes — such as new optional fields or additional endpoints — are made without a version bump and will never break existing integrations.

Request Format

Send all request bodies as JSON and include a Content-Type: application/json header on every request that carries a body (POST, PUT, PATCH).

curl https://api.jomioz.com/v1/resources \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "name": "My Resource", "type": "widget" }'

Requests without a body (GET, DELETE) do not need the Content-Type header.

Response Format

Every successful response is a JSON object wrapped in a consistent envelope. The data field contains the resource or array of resources you requested. The meta field carries pagination information when the response is a list.

{
  "data": [
    { "id": "usr_01J9XK", "email": "ada@example.com" }
  ],
  "meta": {
    "limit": 20,
    "next_cursor": "cur_01J9ZM",
    "prev_cursor": null,
    "total": 142
  }
}

Single-object responses omit the meta field and place the object directly in data:

{
  "data": {
    "id": "usr_01J9XK",
    "email": "ada@example.com",
    "role": "admin",
    "created_at": "2024-03-15T10:22:00Z"
  }
}

Error Responses

When a request fails, Jomioz returns a non-2xx HTTP status code and an error envelope. The code field is a machine-readable string you can match programmatically; message is a human-readable explanation; details is an optional array of per-field validation errors.

{
  "error": {
    "code": "validation_failed",
    "message": "Request body contains invalid fields.",
    "details": [
      {
        "field": "email",
        "issue": "Must be a valid email address."
      }
    ]
  }
}

The table below lists the HTTP status codes the API returns and what each means.

Status Code	Name	When It Occurs
`400`	Bad Request	The request body or query parameters are malformed or missing.
`401`	Unauthorized	No API key was provided, or the key is invalid or expired.
`403`	Forbidden	The API key does not have the required scope for this action.
`404`	Not Found	The requested resource does not exist in your workspace.
`422`	Unprocessable Entity	The body is valid JSON but fails business-rule validation.
`429`	Too Many Requests	You have exceeded your plan’s rate limit for the current window.
`500`	Internal Server Error	An unexpected error occurred on the Jomioz side. Retry with backoff.

Versioning

The current API version is v1, embedded directly in the URL path (e.g., https://api.jomioz.com/v1/resources). When Jomioz introduces breaking changes, a new version (e.g., v2) will be released alongside v1, giving you time to migrate. The deprecation timeline and migration guides will be announced in the changelog before any old version is retired.

Webhooks API

Jomioz exposes POST /v1/webhooks and DELETE /v1/webhooks/{id} for managing webhook subscriptions programmatically. Full endpoint documentation — including payload shapes, signature verification, and retry behavior — is covered in the Webhooks reference.

API Overview

Endpoints

Jomioz REST API Reference: Base URLs, Requests & Errors

Base URL

Request Format

Response Format

Error Responses

Versioning

Webhooks API

​Base URL

​Request Format

​Response Format

​Error Responses

​Versioning

​Webhooks API

Base URL

Request Format

Response Format

Error Responses

Versioning

Webhooks API