GET Search and page through devices in your workspace
/api/v1/devices
Search and page through devices in your workspace.
On this page
Access and permissions
Search and page through devices in your workspace.
Browser session: __Host-mb_session cookie.
Machine management credentials in Authorization: Bearer. Check the permissions (scopes) required by the operation.
Parameters and headers
| Field | Location | Type and limits | Required | Meaning |
|---|---|---|---|---|
| workspace_id | URL query | string; {"format":"uuid"} | Yes | UUID of an owned workspace. When optional, omission selects the documented default or all owned workspaces. |
| q | URL query | string; {"maxLength":128} | No | Search names, UUIDs and safe website origins or host/port targets. Credentials, URL paths and query secrets are excluded. |
| group_id | URL query | string; {"format":"uuid"} | JSON; {"const":"none"} | No | Filter by membership in this active group; none means no active group memberships. |
| type | URL query | string; {"default":"","enum":["","custom","server","http","job","workflow","sensor","application","ai_agent","industrial","tcp","udp","dns","tls","ping","service","browser"]} | No | Filter by monitor type. Omit this parameter or leave it empty to include all types. |
| state | URL query | string; {"default":"all","enum":["all","fresh","missing","attention","paused","up","down","unknown","warn"]} | No | Monitor state. warn selects monitors with open alarms, excluding paused monitors; up and down independently describe confirmed reachability. |
| sort | URL query | string; {"default":"newest","enum":["newest","oldest","name_asc","name_desc","manual"]} | No | Use manual with list_group=monitors or servers to read your personal order. Manual cursors also bind the acting user and order revision; stale cursors return 422. Other sort modes keep their existing behavior. |
| limit | URL query | integer; {"default":50,"maximum":100,"minimum":1} | No | Maximum number of returned rows; use the operation-specific default and upper bound. |
| cursor | URL query | string; {"maxLength":4096} | No | Bound to the account and filters; valid for 15 minutes |
| include_summary | URL query | boolean; {"default":false} | No | Include up to three automatically selected metrics for each returned monitor. Values include timestamps, validity and source information. Missing or outdated data is explicitly identified; this option does not start checks. Machine and MCP/OAuth access additionally requires telemetry:read. With this option, limit must not exceed 50. |
| list_group | URL query | string; {"enum":["all","monitors","servers"],"default":"all"} | No | Filter by Monitors or Servers before counts and pagination. Omit the filter or use all for the complete list. Cursors are bound to this selection. |
| types | URL query | string; {"maxLength":2048} | No | Comma-separated selection of up to 50 values. Values within a category match with OR; categories combine with AND. Do not combine with a conflicting singular filter. Group none selects ungrouped monitors. Locations refer to configured assignments, including unavailable locations. |
| group_ids | URL query | string; {"maxLength":2048} | No | Comma-separated selection of up to 50 values. Values within a category match with OR; categories combine with AND. Do not combine with a conflicting singular filter. Group none selects ungrouped monitors. Locations refer to configured assignments, including unavailable locations. |
| location_ids | URL query | string; {"maxLength":2048} | No | Comma-separated selection of up to 50 values. Values within a category match with OR; categories combine with AND. Do not combine with a conflicting singular filter. Group none selects ungrouped monitors. Locations refer to configured assignments, including unavailable locations. |
| include_facets | URL query | boolean; {"default":false} | No | Include list-wide totals, Up/Down counts and filter values before pagination (maximum 50 rows). Status counts ignore the state selection; each facet ignores its own category. Up/Down follow confirmed check, run or contact status, independently of open alarms. Paused and unknown checks are neither Up nor Down. |
| personal_order | URL query | boolean; {"default":false} | No | For browser monitor and server lists, include the personal order revision and resolve an omitted sort to the saved personal order or newest first. Explicit sorting is preserved. |
| view | URL query | string; {"enum":["options"]} | No | Set options for a bounded metadata-only monitor selector. Searches names and monitor IDs, uses name order, accepts at most 50 rows per page, and does not support summary, facets, personal order, state, group or location filters. |
| counts_only | URL query | string; {"enum":["1"]} | No | Return counts for the requested filter instead of table rows. Counts include search and other filters, excluding this filter selection, sorting and pagination. |
| count_filter | URL query | string; {"enum":["state"]} | No | Declared table filter to count. Requires counts_only=1. |
| snapshot | URL query | string; {"format":"date-time"} | No | Optional snapshot from the corresponding table page. |
Request body
No request body.
Responses
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | object | object | Yes | — |
| $ (anyOf 1) | object | No | — |
| $ (anyOf 1).devices | array<object> | Yes | — |
| $ (anyOf 1).devices[] | object | Yes | — |
| $ (anyOf 1).devices[].attention | boolean | Yes | — |
| $ (anyOf 1).devices[].created_at | string; {"format":"date-time"} | Yes | Creation timestamp in RFC 3339 UTC. |
| $ (anyOf 1).devices[].group_ids | array<string; {"format":"uuid"}> | Yes | IDs of active groups containing this device, or an empty array. |
| $ (anyOf 1).devices[].group_ids[] | string; {"format":"uuid"} | Yes | — |
| $ (anyOf 1).devices[].http_checked_at | string; {"format":"date-time"} | null | Yes | — |
| $ (anyOf 1).devices[].http_checked_at (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).devices[].http_checked_at (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].http_status | string | null | Yes | — |
| $ (anyOf 1).devices[].http_status (anyOf 1) | string | No | — |
| $ (anyOf 1).devices[].http_status (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].id | string | Yes | UUID of this resource. Keep the returned identifier for subsequent operations. |
| $ (anyOf 1).devices[].last_heartbeat_at | string; {"format":"date-time"} | null | Yes | Last accepted device contact timestamp; null before the first contact. |
| $ (anyOf 1).devices[].last_heartbeat_at (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).devices[].last_heartbeat_at (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].monitor_type | string | Yes | — |
| $ (anyOf 1).devices[].name | string | Yes | Human-readable resource name. Follow the listed length limit. |
| $ (anyOf 1).devices[].paused | boolean | Yes | Whether automatic monitor work is paused. Existing telemetry and historical data remain. |
| $ (anyOf 1).devices[].workspace_id | string | Yes | UUID of the owning workspace. Access is checked against the authenticated account. |
| $ (anyOf 1).devices[].check_result | object; {"additionalProperties":false} | No | Optional evaluated check result or latest retained run. Checks use the configured location policy, current node capability and valid observations. Unknown or stale evidence is not a passed check. Run outcomes describe the latest retained execution, not a service health guarantee. |
| $ (anyOf 1).devices[].check_result.status | string; {"enum":["up","down","unknown","paused","succeeded","failed","running","missing","overdue","cancelled"]} | Yes | — |
| $ (anyOf 1).devices[].check_result.checked_at | string; {"format":"date-time"} | null | Yes | — |
| $ (anyOf 1).devices[].check_result.checked_at (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).devices[].check_result.checked_at (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].check_result.freshness | string; {"enum":["current","stale","missing"]} | Yes | — |
| $ (anyOf 1).devices[].check_result.valid_until | string; {"format":"date-time"} | null | Yes | — |
| $ (anyOf 1).devices[].check_result.valid_until (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).devices[].check_result.valid_until (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].summary | MonitorListSummary | No | Optional metrics for this page only: stable IDs, values, units, freshness and source timestamps. Missing preferred metrics use current recorded alternatives; existing stale values remain visible. State groups distinguish confirmed yes, confirmed no and sources without a current value. A replacement identifies the missing metric and its reason. No additional collection is enabled. |
| $ (anyOf 1).devices[].summary.attention_reasons | array<string; {"maxLength":128}>; {"maxItems":8} | No | Names of up to eight unresolved alarms, critical alarms first. Includes acknowledged alarms and excludes archived rules. |
| $ (anyOf 1).devices[].summary.attention_reasons[] | string; {"maxLength":128} | Yes | — |
| $ (anyOf 1).devices[].summary.attention_count | integer; {"minimum":0} | No | Total number of unresolved alarms represented by the monitor warning. |
| $ (anyOf 1).devices[].summary.status | string; {"enum":["available","unavailable"]} | Yes | — |
| $ (anyOf 1).devices[].summary.target | string | Yes | — |
| $ (anyOf 1).devices[].summary.system | string | Yes | — |
| $ (anyOf 1).devices[].summary.interval_seconds | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).devices[].summary.metrics | array<object; {"additionalProperties":false}>; {"maxItems":3} | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[] | object; {"additionalProperties":false} | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].key | string | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].value | number | string | null | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].unit | string | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].freshness | string; {"enum":["fresh","stale","missing","reported","scheduled"]} | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].reason | string | No | — |
| $ (anyOf 1).devices[].summary.metrics[].measured_at | string; {"format":"date-time"} | null | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].measured_at (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).devices[].summary.metrics[].measured_at (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].summary.metrics[].valid_until | string; {"format":"date-time"} | null | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].valid_until (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).devices[].summary.metrics[].valid_until (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].summary.metrics[].sources | array<object; {"additionalProperties":false}> | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].sources[] | object; {"additionalProperties":false} | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].used | number | No | — |
| $ (anyOf 1).devices[].summary.metrics[].total | number | No | — |
| $ (anyOf 1).devices[].summary.metrics[].cores | number | No | — |
| $ (anyOf 1).devices[].summary.metrics[].path | string | No | — |
| $ (anyOf 1).devices[].summary.metrics[].engine | string | No | — |
| $ (anyOf 1).devices[].summary.metrics[].configured | integer; {"minimum":0} | No | — |
| $ (anyOf 1).devices[].summary.metrics[].id | string | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].label_key | string | No | — |
| $ (anyOf 1).devices[].summary.metrics[].name | string | No | — |
| $ (anyOf 1).devices[].summary.metrics[].component | string | No | — |
| $ (anyOf 1).devices[].summary.metrics[].kind | string; {"enum":["gauge","counter","boolean","enum"]} | No | — |
| $ (anyOf 1).devices[].summary.metrics[].aggregation | string; {"enum":["mean","min"]} | No | — |
| $ (anyOf 1).devices[].summary.metrics[].replaces | object; {"additionalProperties":false} | No | — |
| $ (anyOf 1).devices[].summary.metrics[].replaces.key | string | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].replaces.reason | string | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].group | object; {"additionalProperties":false} | No | — |
| $ (anyOf 1).devices[].summary.metrics[].group.total | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].group.positive | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].group.negative | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).devices[].summary.metrics[].group.unknown | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).devices[].summary.favicon_url | string | No | Relative, authenticated image URL for the favicon of an HTTP or browser monitor. |
| $ (anyOf 1).devices[].summary.location_count | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).devices[].summary.platform | string; {"enum":["linux","darwin","windows"]} | No | Agent-reported operating system. Omitted when it is unknown. |
| $ (anyOf 1).devices[].summary.last_value_received_at | string; {"format":"date-time"} | null | No | Receipt time of the latest retained original numeric or state value across active series. Excludes heartbeats, text events, disabled series and derived calculations. Null when no such value is available. |
| $ (anyOf 1).devices[].summary.last_value_received_at (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).devices[].summary.last_value_received_at (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].summary.agent_update | AgentUpdateInfo | No | — |
| $ (anyOf 1).devices[].summary.agent_update.operating_system | string | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.installed_version | string | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.latest_version | string | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.state | string; {"enum":["unknown","current","update_available"]} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.reason | string | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.can_update | boolean | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.target_id | string | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job | AgentUpdateJob | No | — |
| $ (anyOf 1).devices[].summary.agent_update.job.id | string; {"format":"uuid"} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.installation_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.state | string; {"enum":["pending","running","succeeded","failed","expired","unconfirmed"]} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.phase | string; {"enum":["downloading","installing","restarting","completed"]} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.target | AgentUpdateTarget | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.target.commit | string; {"pattern":"^[0-9a-f]{40}$"} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.target.version | string | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.target.created_at | string; {"format":"date-time"} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.target.file | object; {"additionalProperties":false} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.requested_at | string; {"format":"date-time"} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.updated_at | string; {"format":"date-time"} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.claimed_at | string; {"format":"date-time"} | null | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.claimed_at (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).devices[].summary.agent_update.job.claimed_at (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].summary.agent_update.job.finished_at | string; {"format":"date-time"} | null | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.finished_at (anyOf 1) | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).devices[].summary.agent_update.job.finished_at (anyOf 2) | null | No | — |
| $ (anyOf 1).devices[].summary.agent_update.job.error_code | string | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.monitor_id | string; {"format":"uuid"} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.operation_id | string; {"format":"uuid"} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.source_version | string; {"maxLength":128} | Yes | — |
| $ (anyOf 1).devices[].summary.agent_update.job.source_sha256 | string; {"pattern":"^[0-9a-f]{64}$"} | Yes | — |
| $ (anyOf 1).devices[].list_group | string; {"enum":["monitors","servers"]} | Yes | Effective list: server profiles always use servers; checks and scheduled runs use monitors. Other data sources use the explicit choice or confirmed native-agent detection. |
| $ (anyOf 1).devices[].health_state | string; {"enum":["up","down","unknown","paused"]} | No | — |
| $ (anyOf 1).limit | integer | Yes | Maximum number of returned entries within the documented bounds. |
| $ (anyOf 1).next_cursor | string | Yes | Cursor for the next page; null or empty, as specified by the schema, means the current list has ended. |
| $ (anyOf 1).snapshot | string | Yes | — |
| $ (anyOf 1).counts | object; {"additionalProperties":false} | No | Counts for the entire matching filter selection before cursor pagination. Current means a valid check result, retained run outcome or server contact; it does not prove all services healthy. Attention can overlap unknown results. |
| $ (anyOf 1).counts.total | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).counts.current | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).counts.attention | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).counts.unknown | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).counts.paused | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).order_revision | integer; {"minimum":0} | No | Current order revision. Supply it as expected_revision when moving or resetting; another change returns 409. |
| $ (anyOf 1).total_count | integer; {"minimum":0} | No | — |
| $ (anyOf 1).matched_count | integer; {"minimum":0} | No | — |
| $ (anyOf 1).workspace_id | string; {"format":"uuid"} | No | — |
| $ (anyOf 1).observed_at | string; {"format":"date-time"} | No | — |
| $ (anyOf 1).status_counts | object | No | — |
| $ (anyOf 1).status_counts.all | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).status_counts.up | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).status_counts.warn | integer; {"minimum":0} | No | Number of distinct unpaused monitors with open alarms, across all matching resources before pagination. Independent of up and down counts. |
| $ (anyOf 1).status_counts.down | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).status_counts.unknown | integer; {"minimum":0} | No | — |
| $ (anyOf 1).status_counts.paused | integer; {"minimum":0} | No | — |
| $ (anyOf 1).facets | object | No | — |
| $ (anyOf 1).facets.types | array<object> | No | — |
| $ (anyOf 1).facets.types[] | object | Yes | — |
| $ (anyOf 1).facets.types[].value | string | Yes | — |
| $ (anyOf 1).facets.types[].label | string | No | — |
| $ (anyOf 1).facets.types[].count | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).facets.group_ids | array<object> | No | — |
| $ (anyOf 1).facets.group_ids[] | object | Yes | — |
| $ (anyOf 1).facets.group_ids[].value | string | Yes | — |
| $ (anyOf 1).facets.group_ids[].label | string | No | — |
| $ (anyOf 1).facets.group_ids[].count | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).facets.location_ids | array<object> | No | — |
| $ (anyOf 1).facets.location_ids[] | object | Yes | — |
| $ (anyOf 1).facets.location_ids[].value | string | Yes | — |
| $ (anyOf 1).facets.location_ids[].label | string | No | — |
| $ (anyOf 1).facets.location_ids[].count | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).facets.state | array<object> | No | — |
| $ (anyOf 1).facets.state[] | object | Yes | — |
| $ (anyOf 1).facets.state[].value | string | Yes | — |
| $ (anyOf 1).facets.state[].label | string | No | — |
| $ (anyOf 1).facets.state[].count | integer; {"minimum":0} | Yes | — |
| $ (anyOf 1).has_custom_order | boolean | No | — |
| $ (anyOf 1).resolved_sort | string; {"enum":["newest","oldest","name_asc","name_desc","manual"]} | No | — |
| $ (anyOf 2) | object | No | — |
| $ (anyOf 2).filter_counts | TableFilterCounts | Yes | — |
| $ (anyOf 2).filter_counts.field | string | Yes | — |
| $ (anyOf 2).filter_counts.total | integer; {"minimum":0} | Yes | — |
| $ (anyOf 2).filter_counts.values | object | Yes | — |
| $ (anyOf 2).filter_counts.complete | boolean | Yes | — |
| $ (anyOf 2).filter_counts.snapshot | string; {"format":"date-time"} | Yes | — |
| $ (anyOf 2).filter_counts.counted_at | string; {"format":"date-time"} | Yes | — |
{
"devices": [],
"limit": 0,
"next_cursor": "demo",
"snapshot": "demo"
}| Stable error codes |
|---|
| invalid_credential |
| invalid_token |
| unauthorized |
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
{
"code": "demo",
"detail": "Demo error detail; inspect the documented code.",
"instance": "demo",
"message": "Demo error detail; inspect the documented code.",
"message_key": "errors.requestFailed",
"message_params": {},
"request_id": "00000000000000000000000000000000",
"status": 401,
"title": "Demo error",
"type": "about:blank"
}| Stable error codes |
|---|
| csrf |
| insufficient_scope |
| invalid_origin |
| browser_session_required |
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
{
"code": "demo",
"detail": "Demo error detail; inspect the documented code.",
"instance": "demo",
"message": "Demo error detail; inspect the documented code.",
"message_key": "errors.requestFailed",
"message_params": {},
"request_id": "00000000000000000000000000000000",
"status": 403,
"title": "Demo error",
"type": "about:blank"
}| Stable error codes |
|---|
| not_found |
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
{
"code": "demo",
"detail": "Demo error detail; inspect the documented code.",
"instance": "demo",
"message": "Demo error detail; inspect the documented code.",
"message_key": "errors.requestFailed",
"message_params": {},
"request_id": "00000000000000000000000000000000",
"status": 404,
"title": "Demo error",
"type": "about:blank"
}| Stable error codes |
|---|
| invalid_cursor |
| invalid_filter |
| invalid_filters |
| invalid_limit |
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
{
"code": "demo",
"detail": "Demo error detail; inspect the documented code.",
"instance": "demo",
"message": "Demo error detail; inspect the documented code.",
"message_key": "errors.requestFailed",
"message_params": {},
"request_id": "00000000000000000000000000000000",
"status": 422,
"title": "Demo error",
"type": "about:blank"
}| Stable error codes |
|---|
| unavailable |
| Header | Type and limits | Meaning |
|---|---|---|
| Cache-Control | string; {"pattern":"(?:^|,\\s*)no-store(?:,|$)"} | Private API responses prohibit storage. Public OAuth metadata is cached for 300 seconds; live streams additionally prohibit transformation. |
| Content-Language | string; {"enum":["en","de"]} | Language of human-readable response text, resolved from Accept-Language or the documented browser preference. Technical codes and identifiers remain stable. |
| Referrer-Policy | JSON; {"enum":["strict-origin-when-cross-origin","no-referrer"]} | The default referrer policy is strict-origin-when-cross-origin. Provider-login responses use no-referrer to protect login parameters. |
| Retry-After | string; {"pattern":"^[0-9]+$"} | Seconds before retry. Preserve supported idempotency identifiers and respect the operation’s mutation semantics. |
| Vary | string | Responses vary by Accept-Language; browser-rendered responses can also vary by the preference cookie. |
| X-Content-Type-Options | JSON; {"const":"nosniff"} | The browser must use the declared content type. |
| X-Frame-Options | JSON; {"const":"DENY"} | The response must not be embedded in a frame. |
| X-Request-ID | string | Server-generated request identifier. Include this when reporting an error; inbound values are not trusted. |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
{
"code": "demo",
"detail": "Demo error detail; inspect the documented code.",
"instance": "demo",
"message": "Demo error detail; inspect the documented code.",
"message_key": "errors.requestFailed",
"message_params": {},
"request_id": "00000000000000000000000000000000",
"status": 503,
"title": "Demo error",
"type": "about:blank"
}Retries and asynchronous work
This operation reads or validates without applying a resource mutation. Respect rate limits and credential lifetime.
Request examples
Replace demo IDs, timestamps and placeholders with your own values. For a retry, keep the same IDs, time and content. These examples do not run requests on this page.
Keep login links, codes, cookies and keys private. Do not print them in logs or share them in support requests.
curl --silent --show-error --output /dev/null --write-out "%{http_code}\n" \
--request GET \
--header @"$HOME/.config/metribeacon/headers.txt" \
"https://metribeacon.com/api/v1/devices?workspace_id=00000000-0000-4000-8000-000000000001"
import json
from pathlib import Path
from urllib.request import Request, HTTPRedirectHandler, build_opener
from urllib.error import HTTPError
headers = json.loads((Path.home() / ".config/metribeacon/headers.json").read_text())
request = Request("https://metribeacon.com/api/v1/devices?workspace_id=00000000-0000-4000-8000-000000000001", data=None, headers=headers, method="GET")
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, request, fp, code, message, headers, target):
return None
opener = build_opener(NoRedirect())
try:
with opener.open(request, timeout=10) as response:
print(response.status)
except HTTPError as error:
print(error.code)
error.close()
import { readFile } from "node:fs/promises";
import { homedir } from "node:os";
import { join } from "node:path";
const headers = JSON.parse(await readFile(join(homedir(), ".config/metribeacon/headers.json"), "utf8"));
const response = await fetch("https://metribeacon.com/api/v1/devices?workspace_id=00000000-0000-4000-8000-000000000001", {
method: "GET", headers, redirect: "manual",
signal: AbortSignal.timeout(10000),
});
console.log(response.status);
await response.body?.cancel();
package main
import (
"fmt"
"net/http"
"time"
"encoding/json"
"os"
"path/filepath"
)
func main() {
home, err := os.UserHomeDir(); if err != nil { panic("request failed; credentials and response omitted") }
raw, err := os.ReadFile(filepath.Join(home, ".config/metribeacon/headers.json")); if err != nil { panic("request failed; credentials and response omitted") }
var headers map[string]string
if json.Unmarshal(raw, &headers) != nil { panic("invalid local headers") }
request, err := http.NewRequest("GET", "https://metribeacon.com/api/v1/devices?workspace_id=00000000-0000-4000-8000-000000000001", nil)
if err != nil { panic("request failed; credentials and response omitted") }
for name, value := range headers { request.Header.Set(name, value) }
client := &http.Client{Timeout: 10*time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
response, err := client.Do(request)
if err != nil { panic("request failed; credentials and response omitted") }
defer response.Body.Close()
fmt.Println(response.StatusCode)
}
Related guides
- HTTP API, OAuth and MCP
Find the user API endpoints, their permissions, fields, examples and response formats.
- POST Create a device
Create a device.
- GET Read your active device
Read your active device.
- PATCH Update your device
Update your device.