Skip to content

API Reference Overview

The Nymbl API is a RESTful API that implements a subset of the OData v4 protocol.

Base URL

https://api.nymbldev.com/

Standard OData Endpoints

Service Document

GET /

Returns a list of all available entity sets (resources).

Metadata Document

GET /$metadata

Returns the complete schema definition in EDMX format, including:

  • Entity types and their properties
  • Navigation properties and relationships
  • Data types and constraints
  • Capabilities and annotations

HTTP Methods

Method Usage Supported On
GET Retrieve resource(s) All entity sets
POST Upload a document Documents
PATCH Not supported -
PUT Not supported -
DELETE Not supported -

Request Headers

Required Headers

Authorization: Bearer {access_token}
x-api-key: {api_key}

Accept: application/json

Response Format

All responses are in JSON format following OData conventions.

Success Response

{
  "@odata.context": "https://api.nymbldev.com/$metadata#Patients",
  "value": [
    {
      "patient_id": 12345,
      "first_name": "John",
      "last_name": "Smith",
      "date_of_birth": "1980-05-15"
    }
  ]
}

Single Entity Response

{
  "@odata.context": "https://api.nymbldev.com/$metadata#Patients/$entity",
  "patient_id": 12345,
  "first_name": "John",
  "last_name": "Smith",
  "date_of_birth": "1980-05-15"
}

Error Response

{
  "error": {
    "code": "InvalidFilter",
    "message": "The query specified in the URI is not valid.",
    "details": "Property 'invalid_field' does not exist on type 'Patient'"
  }
}

HTTP Status Codes

Code Meaning When Used
200 OK Successful GET
400 Bad Request Invalid query syntax
401 Unauthorized Missing or invalid access token
403 Forbidden Insufficient permissions
404 Not Found Resource not found
500 Internal Server Error Server-side error

Rate Limits

The API enforces the following limits:

  • Page Size: Maximum 100 records per request
  • Expand Depth: Maximum 3 levels of nested expansion
  • Request Rate: 2–5 requests/second sustained (depending on plan), with burst allowances

Exceeding the rate limit returns a 429 Too Many Requests response. See Limits & Quotas for full details by plan and quota tier.

Data Types

OData Type JSON Type Example
Edm.String string "John Smith"
Edm.Int32 number 12345
Edm.Decimal string "99.99"
Edm.Boolean boolean true
Edm.Date string "2024-01-15"
Edm.DateTimeOffset string "2024-01-15T10:30:00Z"

Common Patterns

Retrieve All Records

Because the API returns a maximum of 100 records per request, use $count, $top, and $skip to page through the full dataset.

First page — request total count:

GET /Patients?$count=true&$top=100&$skip=0&$orderby=id asc

Response:

{
  "@odata.context": "https://api.nymbldev.com/$metadata#Patients",
  "@odata.count": 1500,
  "value": [ ... ]
}

Use @odata.count to determine how many pages remain: ceil(1500 / 100) = 15 pages.

Subsequent pages — increment $skip by 100 each request:

GET /Patients?$top=100&$skip=100&$orderby=id asc
GET /Patients?$top=100&$skip=200&$orderby=id asc

See the Pagination Guide for a complete code example.

Retrieve Single Record

GET /Patients(12345)

OpenAPI Specification

Download the OpenAPI 3.0 specification:

GET /openapi.json

This can be imported into tools like Postman, Swagger UI, or used to generate client SDKs.