Calibrations¶

The Calibrations API manages all calibration operations. Every calibration belongs to exactly one device: the calibration's id is the former CTAG, and inventory_id is the device's former MTAG (see IDs: MTAG, CTAG and the other tags).

Endpoints¶

Method	Path	Description	Permission
`GET`	`/api/v2/calibrations`	List all calibrations	`calibration_view`
`GET`	`/api/v2/calibrations/{id}`	Retrieve a single calibration	`calibration_view`
`POST`	`/api/v2/calibrations`	Create a calibration	`calibration_edit`
`PUT`	`/api/v2/calibrations/{id}`	Update a calibration	`calibration_edit`
`DELETE`	`/api/v2/calibrations/{id}`	Delete a calibration	`calibration_delete`

Sub-Resources¶

Method	Path	Description
`GET`	`/api/v2/calibrations/{id}/results`	Measurement results of the calibration
`GET`	`/api/v2/calibrations/{id}/standards`	Reference standards used

Field Mapping¶

Metrology Code	API Field Name	Description
`C2301`	`calibration_date`	Calibration date
`C2303`	`next_calibration_date`	Next calibration
`C2306`	`certificate_number`	Certificate number
`C2323`	`cal_result`	Calibration result
`C2333`	`calibration_time`	Calibration time

List All Calibrations¶

curl -X GET "https://example.com/api/v2/calibrations?page[number]=1&page[size]=25" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Query Parameters¶

Parameter	Type	Description
`page[number]`	integer	Page number (default: 1)
`page[size]`	integer	Items per page (default: 25)
`sort`	string	Sort field, e.g. `calibration_date` or `-next_calibration_date`
`filter[cal_result]`	string	Filter by result (e.g. `passed`, `failed`)
`filter[inventory_id]`	uuid	Calibrations of a specific device (V1: its `MTAG`)
`filter[calibration_date_from]`	date	From date (YYYY-MM-DD)
`filter[calibration_date_to]`	date	To date (YYYY-MM-DD)

Response¶

{
  "data": [
    {
      "id": "3b17ad90-88c2-4e15-b0aa-2f9e6c4471aa",
      "inventory_id": "ea79f4c2-1b3d-4c88-9f21-7c0a5d13e001",
      "calibration_date": "2024-06-15",
      "next_calibration_date": "2025-06-15",
      "result": "passed",
      "uncertainty": "0.05 %",
      "procedure": "DAkkS-DKD-R 5-1",
      "relationships": {
        "results": [
          { "id": 30, "measured_value": "10.002", "reference_value": "10.000" }
        ],
        "standards": [
          { "id": 7, "name": "Referenznormal RN-001", "certificate": "DAkkS-K-12345" }
        ]
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 58,
    "last_page": 3
  },
  "links": {
    "first": "/api/v2/calibrations?page=1",
    "last": "/api/v2/calibrations?page=3",
    "next": "/api/v2/calibrations?page=2",
    "prev": null
  }
}

Retrieve a Single Calibration¶

curl -X GET "https://example.com/api/v2/calibrations/3b17ad90-88c2-4e15-b0aa-2f9e6c4471aa" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Create a Calibration¶

A calibration is linked to a device via inventory_id. That is the value V1 knows as MTAG; the V1 key name is accepted on writes as well.

curl -X POST "https://example.com/api/v2/calibrations" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "inventory_id": "ea79f4c2-1b3d-4c88-9f21-7c0a5d13e001",
    "calibration_date": "2024-06-15",
    "next_calibration_date": "2025-06-15",
    "result": "passed",
    "uncertainty": "0.05 %",
    "procedure": "DAkkS-DKD-R 5-1"
  }'

Linking to Inventory

inventory_id is required and cannot be changed afterwards: the certificate, measurements and test steps belong to that device. For a different device, create a separate calibration.

Successful Response (201)¶

{
  "data": {
    "id": "7f4c1e08-2ab9-49d7-8c33-5e1b90aa4d12",
    "inventory_id": "ea79f4c2-1b3d-4c88-9f21-7c0a5d13e001",
    "calibration_date": "2024-06-15",
    "next_calibration_date": "2025-06-15",
    "result": "passed",
    "uncertainty": "0.05 %",
    "procedure": "DAkkS-DKD-R 5-1"
  }
}

Update a Calibration¶

curl -X PUT "https://example.com/api/v2/calibrations/7f4c1e08-2ab9-49d7-8c33-5e1b90aa4d12" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "result": "failed",
    "uncertainty": "0.08 %"
  }'

Delete a Calibration¶

curl -X DELETE "https://example.com/api/v2/calibrations/7f4c1e08-2ab9-49d7-8c33-5e1b90aa4d12" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Caution

Deleting a calibration also removes all associated measurement results and standard assignments.

Sub-Resources¶

Retrieve Measurement Results¶

curl -X GET "https://example.com/api/v2/calibrations/3b17ad90-88c2-4e15-b0aa-2f9e6c4471aa/results" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

{
  "data": [
    {
      "id": 30,
      "calibration_id": "3b17ad90-88c2-4e15-b0aa-2f9e6c4471aa",
      "measured_value": "10.002",
      "reference_value": "10.000",
      "deviation": "0.002",
      "unit": "V",
      "in_tolerance": true
    }
  ]
}

Retrieve Reference Standards Used¶

curl -X GET "https://example.com/api/v2/calibrations/3b17ad90-88c2-4e15-b0aa-2f9e6c4471aa/standards" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

{
  "data": [
    {
      "id": 7,
      "name": "Referenznormal RN-001",
      "certificate": "DAkkS-K-12345",
      "valid_until": "2025-12-31"
    }
  ]
}

Filter Examples¶

# Only failed calibrations
curl "https://example.com/api/v2/calibrations?filter[result]=failed" \
  -H "Authorization: Bearer {token}"

# Calibrations of an inventory item, sorted by date
curl "https://example.com/api/v2/calibrations?filter[inventory_id]=ea79f4c2-1b3d-4c88-9f21-7c0a5d13e001&sort=-calibration_date" \
  -H "Authorization: Bearer {token}"

# Calibrations within a date range
curl "https://example.com/api/v2/calibrations?filter[calibration_date_from]=2024-01-01&filter[calibration_date_to]=2024-12-31" \
  -H "Authorization: Bearer {token}"

Error Codes¶

HTTP Status	Meaning
`401`	Not authenticated — invalid or missing token
`403`	Insufficient permissions (`calibration_view`, `calibration_edit`, or `calibration_delete` missing)
`404`	Calibration not found
`422`	Validation error — e.g. invalid date or missing `inventory_id`
`429`	Rate limit exceeded