FROM YOUR FIRST REQUEST TO YOUR FIRST CHART

REST API documentation for metric tracking

Create a project, add a metric and create an API key on that metric’s page. Full keys remain visible to the metric owner. Open Usage examples under a key and copy a complete curl command for that metric; the examples include the key and follow its permissions. Older hash-only keys must be explicitly replaced before their full value and examples can be displayed. The main API uses HTTPS with a publicly trusted certificate. A dedicated HTTP input endpoint for older devices is described below.

https://chartedvalues.com/api/v1

Older project keys with exactly one metric are assigned automatically. If a project has several metrics, open the intended metric and choose Assign to this metric. Unassigned keys cannot access the API; assigning a key preserves its token and settings.

HTTPS and device compatibility

Call the API with one HTTPS request and an API key, without signing in or using cookies. Your device needs TLS 1.2 or 1.3, an up-to-date set of trusted root certificates and a correctly set clock. Use the HTTPS URL directly and keep certificate verification enabled.

Python, PHP, curl and modern IoT devices can call this API directly. JavaScript running on another origin requires CORS configuration for that specific origin; the browser may also send an OPTIONS preflight request.

1. Save a measurement

curl -X POST 'https://chartedvalues.com/api/v1/metrics/temperature/values' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-request-001' \
  -d '{"value":22.4,"timestamp":"2026-11-08T21:21:04Z","external_id":"sensor-001"}'

Replace temperature with your metric identifier. If timestamp is omitted, the server uses the time of receipt. ISO 8601 with a timezone is recommended; timestamps without a timezone are treated as UTC.

HTTP 201
{"inserted":1,"duplicates":0}

2. Send a batch

{
  "values": [
    {"value":22.4,"timestamp":"2026-10-31T10:00:00Z","external_id":"sensor-001"},
    {"value":22.7,"timestamp":"2026-10-31T10:05:00Z","external_id":"sensor-002"}
  ]
}

Use the same URL and headers as for a single measurement. Each request supports up to 1,000 measurements and 2 MiB of JSON. Batches are transactional: an invalid row rejects the entire batch. Values must be numeric, between −999999999999999 and +999999999999999, and are stored to eight decimal places. Measurement timestamps must fall between 1970 and 2100.

3. Read measurements and aggregations

GET /api/v1/metrics
GET /api/v1/metrics/temperature/values?period=30
GET /api/v1/metrics/temperature/values?from=2026-10-01&to=2026-10-31
GET /api/v1/metrics/temperature/values?from=2026-10-01&to=2026-10-31&aggregation=avg&interval=1h

GET /api/v1/metrics returns only the metric assigned to the key. Reading requires a key with read or both permissions. Without aggregation, the API returns paginated raw measurements (500 per page); follow next_page_url. The default period is seven days. Supported period values are 1, 7, 30, 90, 365 and all. Explicit from/to dates take precedence; a to date includes that entire day in UTC.

Aggregations: min, max, avg, sum, count. Intervals: auto, 1m, 5m, 1h, 1d, 1w. The limit is 2,000 chart points; select a larger interval for a longer period. The response includes series, full-period stats, interval_seconds and from/to. Empty intervals are not filled with zeros.

Retry without duplicates

• Idempotency-Key: up to 200 characters. Repeating the same request with the same key returns the saved result (200, Idempotency-Replayed: true). Different content with the same key returns 409. Requests to another metric return 404. Idempotency records remain until the API key is deleted.
• external_id: optional, up to 100 characters, unique within the metric. An identical retry counts as a duplicate; a different value or an explicitly different timestamp returns 409. An empty value means no identifier.
• Without these identifiers, every submission creates a new record, even when the value and timestamp are identical.

Permissions and limits

• Each API key has read, write or both permissions and a limit of 1–600 requests per minute (default: 120). A batch counts as one request.
• The X-RateLimit-Limit and X-RateLimit-Remaining headers describe the key limit. For 429 responses, respect Retry-After and use increasing delays between retries.
• The shared API limit is 1,000 requests per minute per IP address. Each metric can have up to 20 API keys. Keys can expire or be revoked immediately on the metric page.

HTTP GET input for Shelly UNI and similar devices

On the metric page, open HTTP API for this metric → Create HTTP key. Create a key for your device and copy the full URL. The URL remains visible to the metric owner after refreshing the page. Older keys without a saved URL can be explicitly replaced; update the URL on your device afterward. The key can only write to that metric and cannot read data, sign in or access other metrics.

GET http://chartedvalues.com/ingest/HTTP_KEY?value=22.4

Only the URL is needed. No Authorization header, JSON body, login or cookies are required. Use a separate HTTP key created on the metric; an HTTPS REST API key is not accepted here. This HTTP endpoint does not redirect to HTTPS. Other HTTP application pages still redirect.

HTTP 200
{"ok":true,"inserted":1,"duplicates":0}

The value parameter is required and must be numeric; use a decimal point. Optional parameters are an ISO 8601 timestamp and an external_id for deduplication. Without a timestamp, the server uses the receipt time in UTC. URL-encode parameters, especially + in timezone offsets as %2B. Without external_id, every GET request creates a new record, even for the same value.

You can revoke the key or set an expiration date. The default limit is 30 requests per minute, configurable from 1 to 120; the shared HTTP input limit is 120 requests per minute per IP address. For 429 responses, respect Retry-After. Each metric can have up to 10 HTTP keys. HEAD never writes data; other methods are not supported. Responses must not be cached.

HTTP transmits the key and value unencrypted. Do not publish these URLs or embed them in public pages. For digital events on Shelly UNI, change the value parameter to 1 or 0 as appropriate. This endpoint does not read the sensor automatically or add dynamic reading support to devices that lack it. The web application and main REST API use HTTPS.

Saved project locations

Open Locations from a project to save your current position with an optional name and description. Allow location access in your browser, review the position and accuracy, then confirm Save location. You can also choose a point on the map or enter coordinates. GPS is requested only when you press Use current location. Points are private to your account; metric API keys cannot access them.

The map shows all matching points. Search by name or description and filter by inclusive UTC capture dates. Edit or delete individual points, open navigation, or export the matching set as CSV or GeoJSON (longitude, latitude coordinate order). Manually changing coordinates clears the original accuracy. Reset all project locations requires typing RESET and confirmation; it deletes every point in that project while preserving metrics and other projects. Map background providers receive your IP and viewed area; point names and descriptions stay in Charted Values.

CSV and public charts

CSV files use UTF-8, commas and a timestamp,value or timestamp,value,external_id header. Each import supports up to 1,000 rows and 2 MiB. Exports cover the selected period. CSV timestamps use UTC. Potentially unsafe leading characters in external identifiers are escaped during export to prevent spreadsheet formulas.

Public charts are disabled by default. Once enabled, anyone with the link can view the selected metric. Disabling a chart immediately invalidates the old link; enabling it again creates a new one.