Introduction

Base URL

All API requests should be made to the following base URL. Every endpoint path documented in this reference is relative to this base.

For example, to list patients, you would send a request to:

Versioning

The current API version is v1, reflected in the URL path segment /api/v1/. We use path-based versioning so you can pin to a specific major version and receive backward-compatible updates without breaking changes.

When a new major version is released, the previous version will be supported for at least 12 months. Deprecation notices are sent via email and announced in the changelog at least 6 months before a version is retired.

Response Format

All responses are returned as JSON with a Content-Type: application/json header. Every response follows a consistent envelope structure with a success boolean indicating whether the request succeeded.

Successful Responses

Successful responses return a success: true flag and a data object containing the result payload:

{
  "success": true,
  "data": {
    "id": "pat_5f8d3a2b1c9e4a7b",
    "first_name": "Priya",
    "last_name": "Sharma",
    "email": "priya.sharma@example.com",
    "phone": "+919876543210",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Error Responses

Error responses return success: false and an error object containing a machine-readable code and a human-readable message:

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided access token is invalid or malformed."
  }
}

Paginated List Responses

Endpoints that return lists use cursor-based pagination. The data object contains an items array and pagination metadata:

{
  "success": true,
  "data": {
    "items": [
      { "id": "pat_5f8d3a2b1c9e4a7b", "first_name": "Priya", "last_name": "Sharma" },
      { "id": "pat_3a7b9c1d2e5f8a4b", "first_name": "Rahul", "last_name": "Verma" }
    ],
    "pagination": {
      "has_more": true,
      "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNS0wMS0xNVQxMDozMDowMFoifQ==",
      "per_page": 20
    }
  }
}

Authentication Overview

The Odento API supports two authentication methods:

• JWT Tokens — Short-lived access tokens (15 min) obtained via login, refreshed using a long-lived refresh token (30 days). Best for user-facing applications.
• API Keys — Persistent key pairs passed via headers. Best for server-to-server integrations and automation. Keys follow the format ok_live_<24chars> for the key ID and os_<48chars> for the secret.

For full details, see the Authentication guide.

Your First Request

Here's a complete example using curl to list patients with an API key:

curl -X GET https://api.odento.app/api/v1/patients \
  -H "X-API-Key-ID: ok_live_abc123def456ghi789jkl012" \
  -H "X-API-Key-Secret: os_abc123def456ghi789jkl012mno345pqr678stu901vwx234yzab567"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "pat_5f8d3a2b1c9e4a7b",
        "first_name": "Priya",
        "last_name": "Sharma",
        "email": "priya.sharma@example.com",
        "phone": "+919876543210",
        "status": "active",
        "created_at": "2025-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "has_more": false,
      "next_cursor": null,
      "per_page": 20
    }
  }
}

API Modules

The Odento API is organized into modules. Each API key is scoped to specific modules based on your plan and configuration:

Next Steps