API reference overview
Arc Enterprise REST endpoints for MessagePack and line protocol writes, SQL and Arrow queries, health, and the token, RBAC, and query management routes used to administer a cluster.
Arc provides a comprehensive REST API for data ingestion, querying, and management.
Base URL
http://localhost:8000Authentication
All endpoints (except public ones) require authentication. Arc supports multiple authentication methods for compatibility with various clients. The header examples below call GET /api/v1/auth/verify, which answers 200 with the token's details when the token is valid; every other endpoint accepts the same headers.
Bearer token (standard)
curl -H "Authorization: Bearer $ARC_TOKEN" http://localhost:8000/api/v1/auth/verifyToken header (InfluxDB 2.x style)
curl -H "Authorization: Token $ARC_TOKEN" http://localhost:8000/api/v1/auth/verifyAPI key header
curl -H "x-api-key: $ARC_TOKEN" http://localhost:8000/api/v1/auth/verifyQuery parameter (InfluxDB 1.x style)
For InfluxDB 1.x client compatibility, tokens can be passed via the p query parameter:
curl "http://localhost:8000/write?db=mydb&p=$ARC_TOKEN" -d 'cpu,host=server01 usage=45.2'Public endpoints (no auth required)
GET /health- Health checkGET /ready- Readiness probeGET /metrics- Prometheus metricsGET /api/v1/auth/verify- Token verification
Quick examples
Write data (MessagePack)
import os
import msgpack
import requests
ARC_TOKEN = os.environ["ARC_TOKEN"]
data = {
"m": "cpu",
"columns": {
"time": [1697472000000],
"host": ["server01"],
"usage": [45.2]
}
}
response = requests.post(
"http://localhost:8000/api/v1/write/msgpack",
headers={
"Authorization": f"Bearer {ARC_TOKEN}",
"Content-Type": "application/msgpack",
"x-arc-database": "default"
},
data=msgpack.packb(data)
)Query data (JSON)
curl -X POST http://localhost:8000/api/v1/query \
-H "Authorization: Bearer $ARC_TOKEN" \
-H "Content-Type: application/json" \
-d '{"sql": "SELECT * FROM default.cpu LIMIT 10", "format": "json"}'Query data (Apache Arrow)
For large result sets, use Arrow format for the highest sustained row throughput:
import os
import requests
import pyarrow as pa
ARC_TOKEN = os.environ["ARC_TOKEN"]
response = requests.post(
"http://localhost:8000/api/v1/query/arrow",
headers={"Authorization": f"Bearer {ARC_TOKEN}"},
json={"sql": "SELECT * FROM default.cpu LIMIT 100000"}
)
reader = pa.ipc.open_stream(response.content)
arrow_table = reader.read_all()Health check
curl http://localhost:8000/healthHealth & monitoring
GET /health
Health check endpoint.
Response:
{
"status": "ok",
"time": "2024-12-02T10:30:00Z",
"uptime": "1h 23m 45s",
"uptime_sec": 5025
}GET /ready
Kubernetes readiness probe.
Response:
{
"status": "ready",
"time": "2024-12-02T10:30:00Z",
"uptime_sec": 5025
}GET /metrics
Prometheus-format metrics.
Response: text/plain (Prometheus format)
Or request JSON:
curl -H "Accept: application/json" http://localhost:8000/metricsGET /api/v1/metrics
All metrics in JSON format.
GET /api/v1/metrics/memory
Detailed memory statistics including the Go runtime and the query engine.
GET /api/v1/metrics/query-pool
Query engine connection pool statistics.
GET /api/v1/metrics/endpoints
Per-endpoint request statistics.
GET /api/v1/metrics/timeseries/:type
Timeseries metrics data.
Parameters:
:type-system,application, orapi?duration_minutes=30- Time range (default: 30, max: 1440)
GET /api/v1/logs
Recent application logs. Requires an admin token (Authorization: Bearer <admin-token>) when authentication is enabled.
Query Parameters:
?limit=100- Number of logs (default: 100, max: 1000)?level=error- Filter by level (error, warn, info, debug)?since_minutes=60- Time range (default: 60, max: 1440)
Data ingestion
POST /api/v1/write/msgpack
High-performance MessagePack binary writes (recommended).
Headers:
Authorization: Bearer TOKENContent-Type: application/msgpackContent-Encoding: gzip(optional)x-arc-database: default(optional)
Body (MessagePack):
{
"m": "measurement_name",
"columns": {
"time": [1697472000000, 1697472001000],
"host": ["server01", "server02"],
"value": [45.2, 67.8]
}
}Response: 204 No Content
Tag columns (optional): tag_keys names the columns that are tags:
{
"m": "cpu",
"columns": {
"time": [1697472000000, 1697472001000],
"host": ["server01", "server02"],
"value": [45.2, 67.8]
},
"tag_keys": ["host"]
}Arc records the tag names in each file it writes. Compaction uses them to
find and remove duplicate rows: a row is removed only when another row is
identical in every column, such as a batch a client sent twice. Without
tag_keys, the files carry no tag names, and compaction removes duplicates
only if another file in the same partition has them.
Arc leaves out a name that is empty, is time, contains a comma, starts
with _, repeats an earlier name, or is not a column of the data. Names
must match a column exactly, including case. The write still succeeds, and
the server logs a warning naming what it left out, at most once per second.
A name with characters other than letters, digits, _ and -, such as
service.name, is kept. Compaction then does not remove duplicates from
batches of files that include it.
GET /api/v1/write/msgpack/stats
MessagePack ingestion statistics.
GET /api/v1/write/msgpack/spec
MessagePack format specification.
POST /write
InfluxDB 1.x Line Protocol compatible endpoint. This path matches InfluxDB's native API for drop-in client compatibility.
Query Parameters:
db- Target database name (required)rp- Retention policy (optional, ignored)precision- Timestamp precision:ns,us,ms,s(default:ns)p- Authentication token (InfluxDB 1.x style)
Headers:
Content-Type: text/plainAuthorization: Bearer TOKEN(or usepquery param)
Body:
cpu,host=server01 usage=45.2 1697472000000000000
mem,host=server01 used=8.2,total=16.0 1697472000000000000Example:
curl -X POST "http://localhost:8000/write?db=mydb&p=$ARC_TOKEN" \
-d 'cpu,host=server01 usage=45.2'POST /api/v2/write
InfluxDB 2.x compatible endpoint. This path matches InfluxDB's native API for drop-in client compatibility.
Query Parameters:
bucket- Target database/bucket name (required)org- Organization (optional, ignored)precision- Timestamp precision:ns,us,ms,s(default:ns)
Headers:
Content-Type: text/plainAuthorization: Token ARC_TOKEN(InfluxDB 2.x style)
Example:
curl -X POST "http://localhost:8000/api/v2/write?bucket=mydb&org=myorg" \
-H "Authorization: Token $ARC_TOKEN" \
-d 'cpu,host=server01 usage=45.2'POST /api/v1/write/line-protocol
Arc-native Line Protocol endpoint. Uses headers instead of query parameters.
Headers:
Content-Type: text/plainAuthorization: Bearer TOKENx-arc-database: default- Target database
POST /api/v1/write/line-protocol/flush
Force buffer flush to disk.
GET /api/v1/write/line-protocol/stats
Line Protocol ingestion statistics.
GET /api/v1/write/line-protocol/health
Line Protocol handler health.
Querying
POST /api/v1/query
Execute SQL queries with JSON response.
The sql field is limited to query.max_sql_length bytes, 10000 by default
(see Configuration). A longer statement
is answered 400. The same limit applies to /api/v1/query/arrow,
/api/v1/query/msgpack and /api/v1/query/estimate.
Request:
{
"sql": "SELECT * FROM default.cpu LIMIT 10",
"format": "json"
}Response:
{
"columns": ["time", "host", "usage"],
"types": ["TIMESTAMP", "VARCHAR", "DOUBLE"],
"data": [
[1697472000000, "server01", 45.2],
[1697472001000, "server02", 67.8]
],
"row_count": 2,
"execution_time_ms": 12
}Stream completion fields (JSON):
| Field | Meaning |
|---|---|
truncated | Optional. Present as true when streaming fails after the response has started; absent on a complete response. |
truncation_reason | Optional. The sanitized failure reason, accompanying truncated: true. |
rows_capped | Optional. Present as true when the result stopped at a governance row cap. The body is complete and valid up to that cap. |
row_cap | Optional. The cap that was reached, accompanying rows_capped: true. |
row_count | Rows actually returned, not a guarantee that the full result was delivered. |
A streamed JSON response can begin successfully and still fail after some rows
have been sent. Clients must check truncated after reading the complete
response. If it is true, treat the query as failed rather than displaying
the partial rows as a complete result. An HTTP 200 response alone does not
establish that streaming completed successfully.
truncated and rows_capped mean nearly opposite things and have to be
checked separately. truncated says the body is short because the stream
failed, so its rows must not be trusted. rows_capped says the body is
short because policy said so: it is a complete, valid result up to the
cap, and a success to be labelled rather than an error. A client that checks
only truncated silently under-reports a capped result.
The cap comes from per-token query governance (governance.default_max_rows_per_query,
default 0 meaning unlimited). It requires the query_governance licence
feature and an authenticated token, so a deployment without both never sets
these two fields.
The POST /api/v1/query/msgpack endpoint uses a different completion
contract: the truncated and truncation_reason fields are JSON-only. It
materializes the full result before committing response headers, so a DuckDB
failure becomes a proper 5xx rather than a marked partial body. A failure
while writing the MessagePack body can still produce a partial response
without an in-band truncation marker.
The row cap is not JSON-only: the MessagePack envelope carries
rows_capped and row_cap as a pair, exactly as the JSON response does. So
this endpoint has no failure marker but does have a cap marker, and a client
reading it still has to check for one.
POST /api/v1/query/arrow
Execute SQL queries with Apache Arrow IPC response.
Request:
{
"sql": "SELECT * FROM default.cpu LIMIT 10000"
}Response: application/vnd.apache.arrow.stream
Incomplete streams: A failed Arrow IPC stream carries a non-empty
Arc-Stream-Truncated HTTP response trailer containing the failure reason.
The server also writes an invalid Arrow IPC message so a decoder rejects
the incomplete stream instead of accepting fewer rows as a complete result.
Treat either a decoding failure or a non-empty truncation trailer as a query
failure. Trailers are available after the response body has been consumed;
they are not ordinary initial response headers.
Capped streams: a non-empty Arc-Rows-Capped trailer means the stream
stopped at a governance row cap, and its value is the cap. This is the
opposite of Arc-Stream-Truncated: the Arrow stream is complete, decodes
cleanly, and simply holds fewer rows than the query matched. Read both — one
reports a failure, the other a labelled success. Both trailers are announced
in the Trailer header of every Arrow response, but each is sent only when it
has a value (since Arc 27.01.1; earlier releases sent an unset one empty), so
the contract for both is "non-empty means set": read the value, not whether
the trailer is present.
Response header: X-Arc-Query-ID when query management is enabled (v26.09.2+ on this endpoint; the JSON endpoint has always returned it). It is the id GET /api/v1/queries/:id and DELETE /api/v1/queries/:id take.
Request compression
Only the write endpoints accept a compressed request body: /api/v1/write/msgpack,
/api/v1/write/line-protocol, /write, /api/v2/write and /api/v1/write/tle.
They detect gzip and zstd from the body itself, so Content-Encoding is optional
there. Since Arc 27.01.1, every other endpoint, queries included, answers 415
to a request with a Content-Encoding other than identity: send those requests
uncompressed.
POST /api/v1/query/estimate
Estimate query cost before execution.
Request:
{
"sql": "SELECT * FROM default.cpu WHERE time > now() - INTERVAL '1 hour'"
}GET /api/v1/measurements
List all measurements across databases.
GET /api/v1/query/:measurement
Query a specific measurement directly.
Authentication
GET /api/v1/auth/verify
Verify token validity (public endpoint).
Returns 401 with "valid": false when the token is missing, invalid or expired. Accepts every token format listed under Authentication.
Response:
{
"valid": true,
"token_info": {
"id": 2,
"name": "my-token",
"description": "Token for my application",
"permissions": ["read", "write"],
"created_at": "2026-11-10T18:59:07Z",
"enabled": true,
"expires_at": null
},
"permissions": ["read", "write"]
}GET /api/v1/auth/tokens
List all tokens (admin only).
POST /api/v1/auth/tokens
Create a new token (admin only).
Request:
{
"name": "my-service",
"description": "Token for my service",
"permissions": ["read", "write"],
"expires_in": "90d"
}permissions defaults to read and write. expires_in is a duration
("24h") or a number of days ("7d"); leave it out for a token that does not
expire.
Response:
{
"success": true,
"token": "<new-api-token>",
"message": "Token created successfully. Store this token securely - it cannot be retrieved again."
}Since Arc 27.01.1: a name another token has answers 409 (was 500), and an
expires_in that is zero, negative or over 100 years ("36500d") answers
400. See Token management.
GET /api/v1/auth/tokens/:id
Get token details (admin only).
PATCH /api/v1/auth/tokens/:id
Update a token's name, description, permissions or expires_in (admin
only). Fields left out are kept. Since Arc 27.01.1: "name": "" answers
400, a name another token has answers 409 (was 500), expires_in
follows the create rules, and an unknown ID answers 404 with no fields in
the body too (standalone, it answered 200 before).
DELETE /api/v1/auth/tokens/:id
Delete a token (admin only). To disable it but keep its record, revoke it instead.
POST /api/v1/auth/tokens/:id/rotate
Rotate a token (admin only): the response's new_token replaces the old
value. Since Arc 27.01.1, a revoked token answers 409: create a new token
instead.
POST /api/v1/auth/tokens/:id/revoke
Revoke a token (admin only). Revocation is permanent.
PATCH, DELETE, rotate and revoke answer 404 for an unknown token
ID. In a cluster, before Arc 27.01.1, they answered 200 for one.
GET /api/v1/auth/cache/stats
Token cache statistics (admin only).
POST /api/v1/auth/cache/invalidate
Invalidate token cache (admin only).
Compaction
Available in main; ships in v27.01.1
Per-cycle lookup (/cycles, /cycles/{id}), the cycle_id job filter, a
working limit on /history, and a real active_jobs count are merged in
main but are not in a released binary yet. The first release carrying
them is v27.01.1. On v26.09.x the /cycles routes return 404,
/history?limit= is capped at 10 records, and active_jobs is null on
/status and always 0 on /jobs.
GET /api/v1/compaction/status
Current compaction status. The manager block counts attempts (one compaction subprocess invocation), not batches.
Response:
{
"manager": {
"active_jobs": 2,
"total_completed": 1894,
"total_failed": 3
},
"schedulers": {
"hourly": {
"enabled": true,
"running": true,
"schedule": "5 * * * *",
"next_run": "2027-01-14T15:05:00Z"
}
}
}active_jobs is null before v27.01.1.
GET /api/v1/compaction/stats
Compaction statistics.
GET /api/v1/compaction/candidates
List files eligible for compaction.
POST /api/v1/compaction/trigger
Manually trigger compaction.
Request:
{
"database": "default",
"measurement": "cpu"
}GET /api/v1/compaction/jobs
Attempts in flight: active_jobs, unit: "attempts", and an always-empty
jobs array. Returns 0 unconditionally before v27.01.1.
GET /api/v1/compaction/history
Job history, one record per attempt. Query parameters: limit (default 10,
capped at 100; ignored before v27.01.1) and cycle_id to filter to one cycle.
Records carry cycle_id and attempt_depth, the adaptive-splitter level.
GET /api/v1/compaction/cycles
v27.01.1+. Retained cycle history, newest first. limit defaults to 10, capped at 500.
Carries running_cycle_id while a cycle runs.
GET /api/v1/compaction/cycles/{id}
v27.01.1+. One cycle by id, including failed_partitions — a deduplicated map of
partition path to failed-batch count, which is the retry list. A 404 names
the retained window rather than claiming the cycle never ran.
GET /api/v1/compaction/too-wide
v27.01.1+. Partitions this node remembers as too wide to compact in a job's
memory, with the settings each failed under and the current ones; skipped
says whether the next cycle leaves it alone.
DELETE /api/v1/compaction/too-wide
v27.01.1+. Forgets them (all, or ?tier= and/or ?partition=) so the next
cycle tries again. Returns {"cleared": n}.
Delete operations
POST /api/v1/delete
Delete data matching conditions.
Request:
{
"database": "default",
"measurement": "cpu",
"where": "host = 'server01' AND time < '2024-01-01'",
"confirm": true
}Response:
{
"deleted_rows": 1523,
"deleted_files": 3
}GET /api/v1/delete/config
Get delete operation configuration.
Database management
Endpoints for managing databases programmatically.
The three read endpoints require read permission
GET /api/v1/databases, GET /api/v1/databases/:name and
GET /api/v1/databases/:name/measurements require a token with the read
permission. Where reads are restricted per database, each asks a different
question:
GET /api/v1/databasesrequires a grant covering every database. A token scoped to particular ones is refused rather than given a partial list — the same barSHOW DATABASESapplies, and a scoped caller names its database explicitly.- The two per-database routes require only that the caller can read
something inside the named database, and
/:name/measurementsthen filters the names it returns, so it never discloses a measurement the caller cannot read.
See Telling the refusals apart below.
GET /api/v1/databases
List all databases with measurement counts.
Response:
{
"databases": [
{"name": "default", "measurement_count": 5},
{"name": "production", "measurement_count": 12}
],
"count": 2
}POST /api/v1/databases
Create a new database.
Request:
{
"name": "my_database"
}Response (201 Created):
{
"name": "my_database",
"measurement_count": 0,
"created_at": "2024-12-21T10:30:00Z"
}Validation rules:
- Must start with a letter (a-z, A-Z)
- Can contain letters, numbers, underscores, and hyphens
- Maximum 64 characters
- Reserved names blocked:
system,internal,_internal
Error Response (400):
{
"error": "Invalid database name: must start with a letter and contain only alphanumeric characters, underscores, or hyphens"
}GET /api/v1/databases/:name
Get information about a specific database.
Response:
{
"name": "production",
"measurement_count": 12
}Error Response (404):
{
"error": "Database 'nonexistent' not found"
}GET /api/v1/databases/:name/measurements
List all measurements in a database.
Response:
{
"database": "production",
"measurements": [
{"name": "cpu"},
{"name": "memory"},
{"name": "disk"}
],
"count": 3
}Errors on the read endpoints
| Status | Body | Meaning |
|---|---|---|
401 | {"success": false, "error": "Authentication required"} | No token was sent |
401 | {"success": false, "error": "Invalid or expired token"} | Re-authenticate |
403 | {"success": false, "error": "no permission for read on database 'analytics'"} | The token's grants do not cover that database. Empty name on GET /api/v1/databases, which names none |
403 | {"success": false, "error": "token does not have 'read' permission"} | The token has no read permission; a different token is needed |
403 | {"success": false, "error": "permission data unavailable"} | Arc could not load the token's grants and refused rather than guess. A server-side fault — check the Arc server log |
404 | {"error": "Database 'nonexistent' not found"} | No such database |
Telling the refusals apart
All three 403s share a status code and differ only in message. They need
different responses, so do not collapse them:
- "no permission for … on database" — a normal state for a scoped token, not a failure. Name a database the token is granted. An identical retry is refused identically.
- "token does not have … permission" — a different token is required. Naming a database will not help.
- "permission data unavailable" — nothing about the token or the database caused this.
On GET /api/v1/databases/:name the permission check runs before the
existence check, so a database the token has no grant inside answers 403
rather than 404. A 404 only comes back for a database the token can read
inside, which is what prevents the endpoint being used to enumerate names. A
database whose measurements are all filtered out answers 200 with an empty
list, not 404.
DELETE /api/v1/databases/:name
Delete a database and all its data.
Destructive operation
This operation is destructive and cannot be undone. Requires:
delete.enabled = truein configuration?confirm=truequery parameter
In shared storage (Pattern 2), rows other nodes have acknowledged and not
flushed yet are flushed first, so they are deleted with the database (since
27.01.1). A node that cannot flush answers 503 with unflushed_nodes; add
&allow_unreachable=true to delete anyway and leave the rows those nodes
hold. A database whose only rows are still in a buffer answers 404.
Request:
curl -X DELETE -H "Authorization: Bearer $ARC_TOKEN" \
"http://localhost:8000/api/v1/databases/old_data?confirm=true"Response:
{
"message": "Database 'old_data' deleted successfully",
"files_deleted": 47
}Error Responses:
Delete disabled (403):
{
"error": "Delete operations are disabled. Set delete.enabled=true in arc.toml to enable."
}Missing confirmation (400):
{
"error": "Confirmation required. Add ?confirm=true to delete the database."
}Another node could not flush its rows of the database (503, shared storage):
{
"error": "database deletion rejected: 1 other node(s) could not flush their buffered rows of this scope first, so the delete would not see them; retry, or set allow_unreachable=true to leave the rows they hold",
"unflushed_nodes": ["node writer-0 (state dead): no answer: ...; bring it back, remove it from the cluster if it is gone for good, or set allow_unreachable=true to leave the rows it holds"]
}Another writer's file is not registered yet (503, shared storage): checked
before anything is deleted; retry after the Retry-After seconds.
{
"error": "database deletion not run: 1 file(s) another writer flushed are not registered in the cluster manifest yet (first: old_data/cpu/2026/10/15/03/cpu_20261015_032631_795423882.parquet); retry shortly"
}Retention policies
POST /api/v1/retention
Create a retention policy.
Request:
{
"name": "30-day-retention",
"database": "default",
"measurement": "cpu",
"duration": "30d",
"schedule": "0 2 * * *"
}GET /api/v1/retention
List all retention policies.
GET /api/v1/retention/:id
Get a specific policy.
PUT /api/v1/retention/:id
Update a retention policy.
DELETE /api/v1/retention/:id
Delete a retention policy.
POST /api/v1/retention/:id/execute
Execute a policy manually.
GET /api/v1/retention/:id/executions
Get policy execution history, newest first (limit, default 50). Since Arc
27.01.1, an unknown or deleted policy ID answers 404, and a policy that has
not run yet lists "executions": []; earlier versions answered 200 with
"executions": null. Also since 27.01.1, in a cluster, a node
that has not caught up with the cluster after a restart answers 503.
Continuous queries
POST /api/v1/continuous_queries
Create a continuous query.
Request:
{
"name": "hourly-rollup",
"database": "default",
"source_measurement": "cpu",
"destination_measurement": "cpu_hourly",
"query": "SELECT time_bucket('1 hour', time) as time, host, AVG(usage) as avg_usage FROM default.cpu WHERE time >= {start_time} AND time < {end_time} GROUP BY 1, 2",
"interval": "1h"
}GET /api/v1/continuous_queries
List all continuous queries.
GET /api/v1/continuous_queries/:id
Get a specific continuous query.
PUT /api/v1/continuous_queries/:id
Update a continuous query.
DELETE /api/v1/continuous_queries/:id
Delete a continuous query.
POST /api/v1/continuous_queries/:id/execute
Execute a continuous query manually.
GET /api/v1/continuous_queries/:id/executions
Get execution history, newest first (limit, default 50). Since Arc 27.01.1,
an unknown or deleted query ID answers 404, and a query that has not run yet
lists "executions": []; earlier versions answered 200 with
"executions": null. Also since 27.01.1, in a cluster, a node
that has not caught up with the cluster after a restart answers 503.
MQTT subscriptions
Available since v26.02.1
MQTT subscription management is available starting Arc v26.02.1.
Manage MQTT broker subscriptions for direct IoT data ingestion. See the MQTT Integration Guide for detailed usage.
POST /api/v1/mqtt/subscriptions
Create a new MQTT subscription.
Request:
{
"name": "factory-sensors",
"broker": "tcp://localhost:1883",
"topics": ["sensors/#"],
"database": "iot",
"qos": 1,
"auto_start": true
}Response (201 Created):
{
"success": true,
"subscription": {
"id": "056fbfda-eab0-4358-b139-42c539896a1f",
"name": "factory-sensors",
"broker": "tcp://localhost:1883",
"client_id": "arc-e5ccee1d",
"topics": ["sensors/#"],
"qos": 1,
"database": "iot",
"has_password": false,
"tls_enabled": false,
"tls_insecure_skip_verify": false,
"auto_start": true,
"status": "stopped",
"keep_alive_seconds": 60,
"connect_timeout_seconds": 30,
"reconnect_max_seconds": 60,
"clean_session": false,
"created_at": "2026-02-01T10:00:00Z",
"updated_at": "2026-02-01T10:00:00Z"
}
}Up to Arc 26.09.x, a new subscription is created stopped, even with "auto_start": true; from 27.01.1, auto_start also starts it on creation ("status": "running", or "error" with error_message). Otherwise, start it with POST /api/v1/mqtt/subscriptions/:id/start.
Full options:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | - | Unique subscription name |
broker | string | Yes | - | Broker URL (tcp://, ssl://, ws://) |
topics | array | Yes | - | Topics to subscribe |
database | string | Yes | - | Target Arc database |
qos | int | No | 1 | QoS level: 0, 1, or 2 |
client_id | string | No | auto | MQTT client ID |
username | string | No | - | MQTT username |
password | string | No | - | MQTT password (encrypted at rest) |
tls_enabled | bool | No | false | Enable TLS/SSL |
tls_cert_path | string | No | - | Client certificate path |
tls_key_path | string | No | - | Client key path |
tls_ca_path | string | No | - | CA certificate path |
topic_mapping | object | No | In 26.09.x and earlier: exact topic to database name. From v27.01.1: topic filter (+, #) to a database name or a rule with database, measurement and tags_from_topic. See the MQTT integration page | |
auto_start | bool | No | false | Start the subscription whenever Arc starts, and from 27.01.1 also on creation |
GET /api/v1/mqtt/subscriptions
List all MQTT subscriptions.
Response:
{
"success": true,
"subscriptions": [
{
"id": "056fbfda-eab0-4358-b139-42c539896a1f",
"name": "factory-sensors",
"broker": "tcp://localhost:1883",
"status": "running"
}
],
"count": 1
}GET /api/v1/mqtt/subscriptions/:id
Get subscription details.
PUT /api/v1/mqtt/subscriptions/:id
Update a subscription. Subscription must be stopped first.
DELETE /api/v1/mqtt/subscriptions/:id
Delete a subscription. Subscription must be stopped first.
POST /api/v1/mqtt/subscriptions/:id/start
Start a stopped subscription, including one that was just created.
Response:
{
"success": true,
"message": "Subscription started"
}If Arc cannot connect to the broker, the start answers HTTP 502 (Arc 27.01.1+; earlier versions answer 500 Failed to start subscription) with the reason. The same text is stored as the subscription's error_message, and the subscription stays in status error, not running:
{
"success": false,
"error": "could not connect to the broker: connection timeout after 30 seconds"
}A broker that is reached but refuses the connection, for example over bad credentials, gives "the broker refused the connection: ...". The text never contains the broker URL or its credentials.
POST /api/v1/mqtt/subscriptions/:id/stop
Stop a running subscription.
POST /api/v1/mqtt/subscriptions/:id/restart
Restart a subscription (stop + start). A failed connect answers like start: HTTP 502 on Arc 27.01.1+, and the subscription is left stopped in status error.
GET /api/v1/mqtt/subscriptions/:id/stats
Get statistics for a specific subscription.
Response:
{
"success": true,
"stats": {
"id": "997823d7-e5ca-44d3-a6f3-b5992bf81593",
"name": "factory-sensors",
"status": "stopped",
"messages_received": 0,
"messages_failed": 0,
"bytes_received": 0,
"reconnects": 0
}
}GET /api/v1/mqtt/stats
Statistics for every subscription, with a summary.
Response:
{
"success": true,
"stats": {
"subscriptions": [
{
"id": "997823d7-e5ca-44d3-a6f3-b5992bf81593",
"name": "factory-sensors",
"status": "stopped",
"messages_received": 0,
"messages_failed": 0,
"bytes_received": 0,
"reconnects": 0
}
],
"summary": {
"total_subscriptions": 1,
"running": 0,
"stopped": 1,
"error": 0,
"total_messages": 0,
"total_failed": 0,
"total_bytes": 0
}
}
}GET /api/v1/mqtt/health
MQTT service health check.
Response:
{
"status": "healthy",
"healthy": true,
"subscriptions": {
"total": 2,
"running": 2,
"stopped": 0,
"errors": 0
}
}status is degraded while any subscription is in an error state, and unhealthy when subscriptions exist but none is running (for example a new subscription before it is started), which overrides degraded. healthy is true only when status is healthy.
Response formats
Success response
{
"status": "success",
"data": [...],
"count": 10
}Error response
{
"error": "Error message"
}HTTP status codes
200- Success204- No Content (successful write)400- Bad Request401- Unauthorized403- Forbidden (requires admin)404- Not Found500- Internal Server Error
Rate limiting
Arc does not enforce rate limiting by default. For production deployments, consider:
- Reverse proxy rate limiting (Nginx, Traefik)
- API Gateway (AWS API Gateway, Kong)
- Application-level throttling
CORS
CORS is enabled by default with permissive settings. Configure via reverse proxy for production.
Best practices
1. Use MessagePack for writes
MessagePack is considerably faster than Line Protocol:
# Fast: MessagePack columnar
data = {"m": "cpu", "columns": {...}}
requests.post(url, data=msgpack.packb(data))
# Slower: Line Protocol text
data = "cpu,host=server01 usage=45.2"
requests.post(url, data=data)2. Batch your writes
Send multiple records per request:
# Good: Batch write
data = {
"m": "cpu",
"columns": {
"time": [t1, t2, t3, ...],
"host": [h1, h2, h3, ...],
"usage": [u1, u2, u3, ...]
}
}3. Use Arrow for large queries
For 10K+ rows, use the Arrow endpoint:
response = requests.post(url + "/api/v1/query/arrow", ...)
table = pa.ipc.open_stream(response.content).read_all()
df = table.to_pandas() # Zero-copy conversion4. Enable gzip compression
import gzip
compressed = gzip.compress(msgpack.packb(data))
requests.post(
url,
data=compressed,
headers={"Content-Encoding": "gzip", ...}
)Client libraries
Python (official SDK)
pip install arc-tsdb-client[all]from arc_client import ArcClient
with ArcClient(host="localhost", token="your-token") as client:
client.write.write_columnar(
measurement="cpu",
columns={"time": [...], "host": [...], "usage": [...]},
)
df = client.query.query_pandas("SELECT * FROM cpu LIMIT 10")Write measurement names unqualified (FROM cpu); see SQL syntax.
See Python SDK Documentation for full details.
Enterprise API endpoints
The following endpoints are available with an Arc Enterprise license.
Clustering
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/cluster | Cluster status |
GET | /api/v1/cluster/nodes | List cluster nodes |
GET | /api/v1/cluster/nodes/:id | Get specific node |
GET | /api/v1/cluster/local | Local node info |
GET | /api/v1/cluster/health | Health check |
See Clustering & High Availability for detailed API documentation.
RBAC
| Method | Endpoint | Description |
|---|---|---|
POST/GET/PATCH/DELETE | /api/v1/rbac/organizations | Organization management |
POST/GET/PATCH/DELETE | /api/v1/rbac/organizations/:org_id/teams | Team management |
POST/GET/PATCH/DELETE | /api/v1/rbac/teams/:team_id/roles | Role management |
POST/GET/DELETE | /api/v1/rbac/roles/:role_id/measurements | Measurement permissions |
See RBAC for detailed API documentation.
Tiered storage
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/tiering/status | Tiering status |
GET | /api/v1/tiering/files | List files, filtered by tier and/or database |
POST | /api/v1/tiering/migrate | Trigger migration |
POST | /api/v1/tiering/scan | Rescan tier metadata against storage |
GET | /api/v1/tiering/stats | Migration statistics |
GET | /api/v1/tiering/policies | List per-database policies |
GET/PUT/DELETE | /api/v1/tiering/policies/{database} | Get, set or delete a database's policy |
GET | /api/v1/tiering/policies/{database}/effective | Policy in effect, with global defaults |
See Tiered Storage for detailed API documentation.
Audit logging
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/audit/logs | Query audit logs |
GET | /api/v1/audit/stats | Audit statistics |
See Audit Logging for detailed API documentation.
Query governance
| Method | Endpoint | Description |
|---|---|---|
POST/GET/PUT/DELETE | /api/v1/governance/policies | Policy management |
GET | /api/v1/governance/usage/:token_id | Usage monitoring |
See Query Governance for detailed API documentation.
Query management
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/queries/active | Active queries |
GET | /api/v1/queries/history | Query history |
GET | /api/v1/queries/:id | Query details |
DELETE | /api/v1/queries/:id | Cancel query |
See Query Management for detailed API documentation.
Next steps
- Writing data - MessagePack and line protocol examples
- Python SDK - Official Python client
- Getting Started - Quick start guide
- Configuration - Server configuration