{"openapi":"3.1.0","info":{"title":"Clarity (BYOK) API","version":"0.1.0","description":"Clarity (BYOK) lets an AI assistant read your own Clarity data through the Clarity API with a key you supply (Clarity API key (user or application key)). Read-only: 7 tools (list_nodes, get_node, list_node_status, list_datasources, get_datasource, list_subscriptions, get_recent_measurements). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-clarity.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-clarity/docs"},"termsOfService":"https://connectorbay.com/byok-clarity/terms"},"servers":[{"url":"https://byok-clarity.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-clarity/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_nodes":{"post":{"operationId":"list_nodes","summary":"List the Clarity sensor nodes of an organization with node id, SKU, model, life stage and paired accessory modules. The ","description":"List the Clarity sensor nodes of an organization with node id, SKU, model, life stage and paired accessory modules. The configured site location is left out. Use for \"Which Clarity air monitoring nodes does my organization have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org":{"description":"Organization id (for example 'myorgVD43'); shown in the Clarity Dashboard under your user profile.","maxLength":40,"title":"Org","type":"string"}},"required":["org"],"title":"list_nodesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_node":{"post":{"operationId":"get_node","summary":"Get one Clarity node: model, SKU, life stage, paired accessory modules and deployment details (indoor or outdoor, height","description":"Get one Clarity node: model, SKU, life stage, paired accessory modules and deployment details (indoor or outdoor, height above ground, distance from road). Coordinates and photos are left out. Use for \"Is Clarity node A0000001 installed indoors and how high is it\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"node_id":{"description":"Node id printed on the device, as returned by list_nodes, for example 'A0000001'.","maxLength":40,"title":"Node Id","type":"string"},"org":{"description":"Organization id (for example 'myorgVD43'); shown in the Clarity Dashboard under your user profile.","maxLength":40,"title":"Org","type":"string"}},"required":["node_id","org"],"title":"get_nodeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_node_status":{"post":{"operationId":"list_node_status","summary":"List the health of an organization's Clarity nodes: last reading time, battery percent, signal level, overall status (he","description":"List the health of an organization's Clarity nodes: last reading time, battery percent, signal level, overall status (healthy, needs attention, offline) and alarm summary per category. Use for \"Which of my Clarity nodes are offline or low on battery\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org":{"description":"Organization id (for example 'myorgVD43'); shown in the Clarity Dashboard under your user profile.","maxLength":40,"title":"Org","type":"string"}},"required":["org"],"title":"list_node_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_datasources":{"post":{"operationId":"list_datasources","summary":"List the datasources (monitoring locations) visible to an organization with the installed device, source type, subscript","description":"List the datasources (monitoring locations) visible to an organization with the installed device, source type, subscription, name, group and tags. Use for \"Which Clarity monitoring locations do I have and what are they called\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org":{"description":"Organization id (for example 'myorgVD43'); shown in the Clarity Dashboard under your user profile.","maxLength":40,"title":"Org","type":"string"}},"required":["org"],"title":"list_datasourcesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_datasource":{"post":{"operationId":"get_datasource","summary":"Get one datasource (monitoring location): installed source, open-data status, organization annotations, source history a","description":"Get one datasource (monitoring location): installed source, open-data status, organization annotations, source history and when measurements are accessible. Use for \"Show the details and device history of Clarity monitoring location DHARP5723\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"datasource_id":{"description":"Datasource (monitoring location) id as returned by list_datasources, for example 'DHARP5723'.","maxLength":40,"title":"Datasource Id","type":"string"},"org":{"description":"Organization id (for example 'myorgVD43'); shown in the Clarity Dashboard under your user profile.","maxLength":40,"title":"Org","type":"string"}},"required":["datasource_id","org"],"title":"get_datasourceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_subscriptions":{"post":{"operationId":"list_subscriptions","summary":"List the Clarity subscriptions of an organization with type, attached datasource, period and days remaining. Use for \"Wh","description":"List the Clarity subscriptions of an organization with type, attached datasource, period and days remaining. Use for \"Which Clarity subscriptions are about to expire\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org":{"description":"Organization id (for example 'myorgVD43'); shown in the Clarity Dashboard under your user profile.","maxLength":40,"title":"Org","type":"string"}},"required":["org"],"title":"list_subscriptionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_recent_measurements":{"post":{"operationId":"get_recent_measurements","summary":"Get recent measurements of one datasource from Clarity's cache (minute data for 24 hours, hourly means for 48 hours, dai","description":"Get recent measurements of one datasource from Clarity's cache (minute data for 24 hours, hourly means for 48 hours, daily means for 10 days), newest first, one row per metric. Use for \"What were the PM2.5 readings at Clarity location DNQPD5647 over the last day\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org":{"description":"Organization id, for example 'myorgVD43'.","maxLength":40,"title":"Org","type":"string"},"datasource_id":{"description":"Datasource id as returned by list_datasources.","maxLength":40,"title":"Datasource Id","type":"string"},"output_frequency":{"anyOf":[{"enum":["minute","hour","day"],"type":"string"},{"type":"null"}],"default":"hour","description":"minute for individual readings, hour for hourly means and NowCast, day for daily means.","title":"Output Frequency"},"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest time wanted, ISO 8601 such as 2026-10-18T00:00:00Z; only data still in the cache is returned.","title":"Start Time"}},"required":["org","datasource_id"],"title":"get_recent_measurementsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}