declaration_reporting_service.json

{
  "components": {
    "parameters": {
      "X-Environment-Id": {
        "description": "The environment UUID identifier.",
        "in": "header",
        "name": "X-Environment-Id",
        "required": true,
        "schema": {
          "example": "e77c1408-10c8-4007-b177-abc9157fbcaa",
          "format": "uuid",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
          "type": "string"
        }
      }
    },
    "schemas": {
      "ApiErrorDto": {
        "properties": {
          "errors": {
            "items": {
              "$ref": "#/components/schemas/ErrorDto"
            },
            "type": "array"
          },
          "httpStatus": {
            "description": "HTTP status of the response",
            "example": 400,
            "format": "int32",
            "maximum": 599,
            "minimum": 100,
            "type": "integer"
          },
          "traceId": {
            "description": "Trace ID",
            "example": "3e3819a63ae0f231",
            "type": "string"
          }
        },
        "required": [
          "errors"
        ],
        "type": "object"
      },
      "DeviceChannelsDto": {
        "properties": {
          "channels": {
            "description": "The channels associated with the device",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "deviceId": {
            "description": "The platform deviceId",
            "example": "179a77b6-aafb-45be-83de-915f531e4e39",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ErrorDto": {
        "properties": {
          "code": {
            "description": "Error-specific code that can be used to identify localization string, etc.",
            "example": "INVALID_FIELD",
            "type": "string"
          },
          "description": {
            "description": "A general description of error for troubleshooting/debugging. Generally this text should not be displayed to a user; instead refer to errorCode and its localized text.",
            "example": "Field name is required.",
            "type": "string"
          },
          "field": {
            "description": "Name of the field that caused the error.",
            "example": "name",
            "type": "string"
          },
          "id": {
            "description": "id of object with error",
            "example": "2b7b22dc-a0d4-48d2-a02d-8fdd88e1397c",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "FilteredDeclarationReportDto": {
        "properties": {
          "declarationIdentifier": {
            "description": "The declaration identifier",
            "example": "179a77b6-aafb-45be-83de-915f531e4e39",
            "type": "string"
          },
          "results": {
            "description": "The devices associated with the declaration that meet the required filters",
            "items": {
              "$ref": "#/components/schemas/FilteredResultDto"
            },
            "type": "array"
          },
          "totalCount": {
            "description": "The total number of devices reported for the declaration that meet the required filters",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "declarationIdentifier",
          "results",
          "totalCount"
        ],
        "type": "object"
      },
      "FilteredDeviceReportDto": {
        "properties": {
          "deviceId": {
            "description": "The platform deviceId",
            "example": "179a77b6-aafb-45be-83de-915f531e4e39",
            "type": "string"
          },
          "results": {
            "description": "The declarations associated with any channel on the device that meet the required filters",
            "items": {
              "$ref": "#/components/schemas/FilteredResultDto"
            },
            "type": "array"
          },
          "totalCount": {
            "description": "The total number of declarations reported for the device that meet the required filters",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "deviceId",
          "results",
          "totalCount"
        ],
        "type": "object"
      },
      "FilteredResultDto": {
        "externalDocs": {
          "description": "Apple Documentation: Status Management Declarations",
          "url": "https://developer.apple.com/documentation/devicemanagement/statusmanagementdeclarationsdeclarationobject"
        },
        "properties": {
          "active": {
            "description": "The active state of the declaration",
            "example": true,
            "type": "boolean"
          },
          "channel": {
            "description": "The channel of the client from which the report is sent",
            "example": "SYSTEM",
            "type": "string"
          },
          "dateUpdated": {
            "description": "The timestamp when this declaration status was last updated for the device",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "declarationIdentifier": {
            "description": "The identifier of the declaration",
            "example": "ea6ddcb3-729f-42b1-a67d-940008419baa",
            "type": "string"
          },
          "deviceId": {
            "description": "The platform deviceId",
            "example": "179a77b6-aafb-45be-83de-915f531e4e39",
            "type": "string"
          },
          "lastReportTime": {
            "description": "The timestamp of the device's last status report",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "reasons": {
            "description": "Reasons associated with the declaration, if any",
            "items": {
              "$ref": "#/components/schemas/StatusReportDeclarationReasonDto"
            },
            "type": "array"
          },
          "serverToken": {
            "description": "The server token for the declaration",
            "example": "2c9e3ec8907bf6e58fd93f2e28a02883ac58dde58906671003074deb84de6ff8",
            "type": "string"
          },
          "status": {
            "description": "The installation status of the declaration",
            "enum": [
              "PENDING",
              "SUCCESSFUL",
              "AWAITING_SYNC",
              "UNSUCCESSFUL",
              "UNKNOWN"
            ],
            "example": "PENDING",
            "type": "string"
          },
          "type": {
            "description": "The type of the declaration",
            "enum": [
              "ASSET",
              "MANAGEMENT",
              "CONFIGURATION",
              "ACTIVATION",
              "UNKNOWN"
            ],
            "example": "CONFIGURATION",
            "type": "string"
          },
          "validityState": {
            "description": "The validity state of the declaration",
            "enum": [
              "VALID",
              "INVALID",
              "UNKNOWN"
            ],
            "example": "VALID",
            "type": "string"
          }
        },
        "required": [
          "active",
          "channel",
          "declarationIdentifier",
          "deviceId",
          "serverToken",
          "status",
          "type",
          "validityState"
        ],
        "type": "object"
      },
      "StatusReportDeclarationReasonDetailDto": {
        "properties": {
          "description": {
            "description": "The description of the detail key",
            "example": "f5d98fac-5f8a-4bde-b1f8-308a062dd591",
            "type": "string"
          },
          "key": {
            "description": "The reason detail key",
            "example": "Identifier",
            "type": "string"
          }
        },
        "required": [
          "description",
          "key"
        ],
        "type": "object"
      },
      "StatusReportDeclarationReasonDto": {
        "properties": {
          "code": {
            "description": "The reason code",
            "example": "Error.ConfigurationAlreadyPresent",
            "type": "string"
          },
          "description": {
            "description": "The description of the reason",
            "example": "Configuration cannot be applied as another is already present",
            "type": "string"
          },
          "details": {
            "description": "Details associated with the reason, if any",
            "items": {
              "$ref": "#/components/schemas/StatusReportDeclarationReasonDetailDto"
            },
            "type": "array"
          }
        },
        "required": [
          "code",
          "description"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "oauth2": {
        "description": "Obtain an access token by calling the API Gateway's token endpoint using the OAuth2 client-credentials flow.",
        "flows": {
          "clientCredentials": {
            "scopes": {
              "declarations:read": ""
            },
            "tokenUrl": "https://{region}.api.jamfcloud.com/auth/token"
          }
        },
        "type": "oauth2"
      }
    }
  },
  "info": {
    "contact": {
      "name": "Jamf Developer",
      "url": "https://developer.jamf.com"
    },
    "description": "API for accessing device and declaration status reports",
    "termsOfService": "https://www.jamf.com/developer-resources/api-license-agreement/",
    "title": "Declaration Reporting Service",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/v1/declarations/{declarationIdentifier}/devices": {
      "get": {
        "description": "Get a declaration report containing the filtered devices currently reporting the provided declarationIdentifier. Supports pagination, sorting, and filtering with RSQL syntax. **Filtering:** Filters only apply to declarations already on the device (excludes PENDING status). Supported filter fields: `deviceId`, `channel`, `lastReportTime`, `active`, `validityState`, `declarationType`, `dateUpdated`. **Sorting:** Use `?sort=field,direction` (e.g., `?sort=declarationType,asc`). For more information on RSQL, see [Jamf Developer Portal](https://developer.jamf.com)\n\n**Required Permissions:** `declarations:read`",
        "operationId": "getDeclarationReportByFilter",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Environment-Id"
          },
          {
            "description": "The declarationIdentifier present on a status report",
            "example": "179a77b6-aafb-45be-83de-915f531e4e39",
            "in": "path",
            "name": "declarationIdentifier",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RSQL filter expression. Allowed fields: deviceId, channel, lastReportTime, active, validityState, declarationType, dateUpdated",
            "example": "channel==SYSTEM;active==true",
            "in": "query",
            "name": "filter",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Zero-based page index (0..N)",
            "in": "query",
            "name": "page",
            "schema": {
              "default": 0,
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "The size of the page to be returned",
            "in": "query",
            "name": "size",
            "schema": {
              "default": 20,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
            "in": "query",
            "name": "sort",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilteredDeclarationReportDto"
                }
              }
            },
            "description": "Successfully retrieved the filtered declaration report"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": "INVALID_FILTER",
                      "description": "Unsupported filter field: 'unknownField'. Supported fields are: deviceId, channel, lastReportTime, active, validityState, declarationType, dateUpdated",
                      "field": null,
                      "id": null
                    }
                  ],
                  "httpStatus": 400,
                  "traceId": "3e3819a63ae0f231"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            },
            "description": "Bad request - invalid RSQL filter or unsupported field"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": null,
                      "description": "An unexpected error occurred",
                      "field": null,
                      "id": null
                    }
                  ],
                  "httpStatus": 500,
                  "traceId": "3e3819a63ae0f231"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            },
            "description": "Unknown error occurred"
          },
          "503": {
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": "BULKHEAD_LIMIT_REACHED",
                      "description": "Bulkhead limit reached",
                      "field": null,
                      "id": null
                    }
                  ],
                  "httpStatus": 503,
                  "traceId": "3e3819a63ae0f231"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            },
            "description": "Too many requests - bulkhead limit reached"
          }
        },
        "security": [
          {
            "oauth2": [
              "declarations:read"
            ]
          }
        ],
        "summary": "Get filtered declaration report devices",
        "tags": [
          "declaration-reports"
        ],
        "x-required-privileges": [
          "declarations:read"
        ]
      }
    },
    "/v1/devices/{deviceId}/channels": {
      "get": {
        "description": "Get a list of all channels available for the provided deviceId.\n\n**Required Permissions:** `declarations:read`",
        "operationId": "getDeviceChannels",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Environment-Id"
          },
          {
            "description": "The platform deviceId",
            "example": "179a77b6-aafb-45be-83de-915f531e4e39",
            "in": "path",
            "name": "deviceId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceChannelsDto"
                }
              }
            },
            "description": "Successfully retrieved the device channels"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": null,
                      "description": "Failed to process status report",
                      "field": null,
                      "id": null
                    }
                  ],
                  "httpStatus": 400,
                  "traceId": "3e3819a63ae0f231"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            },
            "description": "Bad request"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": null,
                      "description": "An unexpected error occurred",
                      "field": null,
                      "id": null
                    }
                  ],
                  "httpStatus": 500,
                  "traceId": "3e3819a63ae0f231"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            },
            "description": "Unknown error occurred"
          },
          "503": {
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": "BULKHEAD_LIMIT_REACHED",
                      "description": "Bulkhead limit reached",
                      "field": null,
                      "id": null
                    }
                  ],
                  "httpStatus": 503,
                  "traceId": "3e3819a63ae0f231"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            },
            "description": "Too many requests - bulkhead limit reached"
          }
        },
        "security": [
          {
            "oauth2": [
              "declarations:read"
            ]
          }
        ],
        "summary": "Get device channels",
        "tags": [
          "device-reports"
        ],
        "x-required-privileges": [
          "declarations:read"
        ]
      }
    },
    "/v1/devices/{deviceId}/declarations": {
      "get": {
        "description": "Get a device report containing the filtered declarations reported for the provided deviceId. Supports pagination, sorting, and filtering with RSQL syntax. **Filtering:** Filters only apply to declarations already on the device (excludes PENDING status). Supported filter fields: `declarationIdentifier`, `active`, `declarationType`, `validityState`, `dateUpdated`, `channel`. **Note:** Wildcard matching on declarationIdentifier (e.g. `declarationIdentifier==Blueprint_*`) is case-insensitive. **Sorting:** Use `?sort=field,direction` (e.g., `?sort=declarationType,asc\u0026sort=declarationIdentifier,desc`). Supported sort fields: declarationIdentifier, declarationType, active, validityState, dateUpdated. Results are returned in database order if no sort parameter is provided. For more information on RSQL, see [Jamf Developer Portal](https://developer.jamf.com)\n\n**Required Permissions:** `declarations:read`",
        "operationId": "getDeviceReportByFilter",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Environment-Id"
          },
          {
            "description": "The platform deviceId",
            "example": "179a77b6-aafb-45be-83de-915f531e4e39",
            "in": "path",
            "name": "deviceId",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RSQL filter expression. Allowed fields: declarationIdentifier, active, validityState, declarationType, dateUpdated, channel",
            "example": "declarationIdentifier==Blueprint_66446f3a-03c8-44d6-ba31-46cf156bb448*;declarationType==CONFIGURATION",
            "in": "query",
            "name": "filter",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Zero-based page index (0..N)",
            "in": "query",
            "name": "page",
            "schema": {
              "default": 0,
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "The size of the page to be returned",
            "in": "query",
            "name": "size",
            "schema": {
              "default": 20,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
            "in": "query",
            "name": "sort",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FilteredDeviceReportDto"
                }
              }
            },
            "description": "Successfully retrieved the filtered device report"
          },
          "400": {
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": "INVALID_FILTER",
                      "description": "Unsupported filter field: 'unknownField'. Supported fields are: declarationIdentifier, active, declarationType, validityState, dateUpdated, channel",
                      "field": null,
                      "id": null
                    }
                  ],
                  "httpStatus": 400,
                  "traceId": "3e3819a63ae0f231"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            },
            "description": "Bad request - invalid RSQL filter or unsupported field"
          },
          "500": {
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": null,
                      "description": "An unexpected error occurred",
                      "field": null,
                      "id": null
                    }
                  ],
                  "httpStatus": 500,
                  "traceId": "3e3819a63ae0f231"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            },
            "description": "Unknown error occurred"
          },
          "503": {
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": "BULKHEAD_LIMIT_REACHED",
                      "description": "Bulkhead limit reached",
                      "field": null,
                      "id": null
                    }
                  ],
                  "httpStatus": 503,
                  "traceId": "3e3819a63ae0f231"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            },
            "description": "Too many requests - bulkhead limit reached"
          }
        },
        "security": [
          {
            "oauth2": [
              "declarations:read"
            ]
          }
        ],
        "summary": "Get filtered device report declarations",
        "tags": [
          "device-reports"
        ],
        "x-required-privileges": [
          "declarations:read"
        ]
      }
    }
  },
  "security": [
    {
      "oauth2": []
    }
  ],
  "servers": [
    {
      "description": "Jamf Beta API Gateway - prod",
      "url": "https://{region}.api.jamfcloud.com/ddm/report",
      "variables": {
        "region": {
          "default": "us",
          "description": "Geographic deployment region",
          "enum": [
            "us",
            "eu",
            "apac"
          ]
        }
      }
    }
  ],
  "tags": [
    {
      "name": "device report"
    },
    {
      "name": "declaration report"
    }
  ],
  "x-scope-types": [
    "environment"
  ]
}