BasekickLabs

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:8000

Authentication

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/verify

Token header (InfluxDB 2.x style)

curl -H "Authorization: Token $ARC_TOKEN" http://localhost:8000/api/v1/auth/verify

API key header

curl -H "x-api-key: $ARC_TOKEN" http://localhost:8000/api/v1/auth/verify

Query 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 check
  • GET /ready - Readiness probe
  • GET /metrics - Prometheus metrics
  • GET /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/health

Health & 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/metrics

GET /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, or api
  • ?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 TOKEN
  • Content-Type: application/msgpack
  • Content-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/plain
  • Authorization: Bearer TOKEN (or use p query param)

Body:

cpu,host=server01 usage=45.2 1697472000000000000
mem,host=server01 used=8.2,total=16.0 1697472000000000000

Example:

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/plain
  • Authorization: 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/plain
  • Authorization: Bearer TOKEN
  • x-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):

FieldMeaning
truncatedOptional. Present as true when streaming fails after the response has started; absent on a complete response.
truncation_reasonOptional. The sanitized failure reason, accompanying truncated: true.
rows_cappedOptional. Present as true when the result stopped at a governance row cap. The body is complete and valid up to that cap.
row_capOptional. The cap that was reached, accompanying rows_capped: true.
row_countRows 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/databases requires a grant covering every database. A token scoped to particular ones is refused rather than given a partial list — the same bar SHOW DATABASES applies, 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/measurements then 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

StatusBodyMeaning
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 = true in configuration
  • ?confirm=true query 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:

FieldTypeRequiredDefaultDescription
namestringYes-Unique subscription name
brokerstringYes-Broker URL (tcp://, ssl://, ws://)
topicsarrayYes-Topics to subscribe
databasestringYes-Target Arc database
qosintNo1QoS level: 0, 1, or 2
client_idstringNoautoMQTT client ID
usernamestringNo-MQTT username
passwordstringNo-MQTT password (encrypted at rest)
tls_enabledboolNofalseEnable TLS/SSL
tls_cert_pathstringNo-Client certificate path
tls_key_pathstringNo-Client key path
tls_ca_pathstringNo-CA certificate path
topic_mappingobjectNoIn 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_startboolNofalseStart 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 - Success
  • 204 - No Content (successful write)
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden (requires admin)
  • 404 - Not Found
  • 500 - 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 conversion

4. 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

MethodEndpointDescription
GET/api/v1/clusterCluster status
GET/api/v1/cluster/nodesList cluster nodes
GET/api/v1/cluster/nodes/:idGet specific node
GET/api/v1/cluster/localLocal node info
GET/api/v1/cluster/healthHealth check

See Clustering & High Availability for detailed API documentation.

RBAC

MethodEndpointDescription
POST/GET/PATCH/DELETE/api/v1/rbac/organizationsOrganization management
POST/GET/PATCH/DELETE/api/v1/rbac/organizations/:org_id/teamsTeam management
POST/GET/PATCH/DELETE/api/v1/rbac/teams/:team_id/rolesRole management
POST/GET/DELETE/api/v1/rbac/roles/:role_id/measurementsMeasurement permissions

See RBAC for detailed API documentation.

Tiered storage

MethodEndpointDescription
GET/api/v1/tiering/statusTiering status
GET/api/v1/tiering/filesList files, filtered by tier and/or database
POST/api/v1/tiering/migrateTrigger migration
POST/api/v1/tiering/scanRescan tier metadata against storage
GET/api/v1/tiering/statsMigration statistics
GET/api/v1/tiering/policiesList 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}/effectivePolicy in effect, with global defaults

See Tiered Storage for detailed API documentation.

Audit logging

MethodEndpointDescription
GET/api/v1/audit/logsQuery audit logs
GET/api/v1/audit/statsAudit statistics

See Audit Logging for detailed API documentation.

Query governance

MethodEndpointDescription
POST/GET/PUT/DELETE/api/v1/governance/policiesPolicy management
GET/api/v1/governance/usage/:token_idUsage monitoring

See Query Governance for detailed API documentation.

Query management

MethodEndpointDescription
GET/api/v1/queries/activeActive queries
GET/api/v1/queries/historyQuery history
GET/api/v1/queries/:idQuery details
DELETE/api/v1/queries/:idCancel query

See Query Management for detailed API documentation.

Next steps

On this page

Base URLAuthenticationBearer token (standard)Token header (InfluxDB 2.x style)API key headerQuery parameter (InfluxDB 1.x style)Public endpoints (no auth required)Quick examplesWrite data (MessagePack)Query data (JSON)Query data (Apache Arrow)Health checkHealth & monitoringGET /healthGET /readyGET /metricsGET /api/v1/metricsGET /api/v1/metrics/memoryGET /api/v1/metrics/query-poolGET /api/v1/metrics/endpointsGET /api/v1/metrics/timeseries/:typeGET /api/v1/logsData ingestionPOST /api/v1/write/msgpackGET /api/v1/write/msgpack/statsGET /api/v1/write/msgpack/specPOST /writePOST /api/v2/writePOST /api/v1/write/line-protocolPOST /api/v1/write/line-protocol/flushGET /api/v1/write/line-protocol/statsGET /api/v1/write/line-protocol/healthQueryingPOST /api/v1/queryPOST /api/v1/query/arrowRequest compressionPOST /api/v1/query/estimateGET /api/v1/measurementsGET /api/v1/query/:measurementAuthenticationGET /api/v1/auth/verifyGET /api/v1/auth/tokensPOST /api/v1/auth/tokensGET /api/v1/auth/tokens/:idPATCH /api/v1/auth/tokens/:idDELETE /api/v1/auth/tokens/:idPOST /api/v1/auth/tokens/:id/rotatePOST /api/v1/auth/tokens/:id/revokeGET /api/v1/auth/cache/statsPOST /api/v1/auth/cache/invalidateCompactionGET /api/v1/compaction/statusGET /api/v1/compaction/statsGET /api/v1/compaction/candidatesPOST /api/v1/compaction/triggerGET /api/v1/compaction/jobsGET /api/v1/compaction/historyGET /api/v1/compaction/cyclesGET /api/v1/compaction/cycles/{id}GET /api/v1/compaction/too-wideDELETE /api/v1/compaction/too-wideDelete operationsPOST /api/v1/deleteGET /api/v1/delete/configDatabase managementGET /api/v1/databasesPOST /api/v1/databasesGET /api/v1/databases/:nameGET /api/v1/databases/:name/measurementsErrors on the read endpointsTelling the refusals apartDELETE /api/v1/databases/:nameRetention policiesPOST /api/v1/retentionGET /api/v1/retentionGET /api/v1/retention/:idPUT /api/v1/retention/:idDELETE /api/v1/retention/:idPOST /api/v1/retention/:id/executeGET /api/v1/retention/:id/executionsContinuous queriesPOST /api/v1/continuous_queriesGET /api/v1/continuous_queriesGET /api/v1/continuous_queries/:idPUT /api/v1/continuous_queries/:idDELETE /api/v1/continuous_queries/:idPOST /api/v1/continuous_queries/:id/executeGET /api/v1/continuous_queries/:id/executionsMQTT subscriptionsPOST /api/v1/mqtt/subscriptionsGET /api/v1/mqtt/subscriptionsGET /api/v1/mqtt/subscriptions/:idPUT /api/v1/mqtt/subscriptions/:idDELETE /api/v1/mqtt/subscriptions/:idPOST /api/v1/mqtt/subscriptions/:id/startPOST /api/v1/mqtt/subscriptions/:id/stopPOST /api/v1/mqtt/subscriptions/:id/restartGET /api/v1/mqtt/subscriptions/:id/statsGET /api/v1/mqtt/statsGET /api/v1/mqtt/healthResponse formatsSuccess responseError responseHTTP status codesRate limitingCORSBest practices1. Use MessagePack for writes2. Batch your writes3. Use Arrow for large queries4. Enable gzip compressionClient librariesPython (official SDK)Enterprise API endpointsClusteringRBACTiered storageAudit loggingQuery governanceQuery managementNext steps