Handlers

Listing and invocation require read permission. Creation requires admin permission. Database grants apply to handler queries.

Create named SQL endpoints with RawTree Cloud or RawTree BYOC. RawTree stores the handler definition and runs its query.

See SQL-defined HTTP endpoints for handler SQL, parameter rules, native errors, and database grants.

GET /v1/handlers

List handlers in the selected cluster.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Request:

# List handlers in the selected cluster.
curl -X GET "https://api.rawtree.com/v1/handlers?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"

Expected response: HTTP 200.

{
  "handlers": [
    {
      "name": "double_number",
      "url": "/double",
      "sql": "SELECT {value:UInt64} * 2 AS doubled FORMAT JSONEachRow"
    }
  ]
}

Errors: 400, 401, 403. See API errors.

POST /v1/handlers

Create a GET handler across the selected cluster.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Parameters:

Request:

# Create a GET handler across the selected cluster.
curl -X POST "https://api.rawtree.com/v1/handlers?database=analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "double_number",
  "url": "/double",
  "sql": "SELECT {value:UInt64} * 2 AS doubled FORMAT JSONEachRow"
}'

Expected response: HTTP 201.

{
  "name": "double_number",
  "url": "/double",
  "sql": "SELECT {value:UInt64} * 2 AS doubled FORMAT JSONEachRow"
}

Errors: 400, 401, 403, 409. See API errors.

GET /v1/handlers/{path}

Invoke a named handler.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Request:

# Invoke a named handler.
curl -X GET "https://api.rawtree.com/v1/handlers/double?database=analytics&value=21" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"

Expected response: HTTP 200.

{
  "doubled": 42
}

Errors: 400, 401, 403, 404, 429, 500. See API errors.

Handler behavior

Create a named query endpoint with POST /v1/handlers. Handler management requires an organization administrator or an admin API key.

curl -X POST 'https://api.rawtree.com/v1/handlers' \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "double_number",
    "url": "/double-number",
    "sql": "SELECT {n:UInt32} * 2 AS result"
  }'

The request requires exactly name, url, and sql. It creates a GET handler across the selected cluster and returns those fields with 201 Created. name is unique across the cluster's databases; url is a native path beginning with /. Duplicate names or overlapping URLs return 409 Conflict without replacing the existing definition. Execution defaults to JSON; include a supported FORMAT clause in sql to choose another format.

List handlers with GET /v1/handlers:

{
  "handlers": [
    {
      "name": "double_number",
      "url": "/double-number",
      "sql": "SELECT {n:UInt32} * 2 AS result"
    }
  ]
}

The list is sorted by name and includes definitions created through SQL. It uses the caller's database identity and preserves native metadata visibility and secret masking. Database-role keys need the native grants to read system.handlers, including SHOW HANDLERS to see its rows. GET /v1/handlers/ (with the trailing slash) invokes the native root path; it is not the listing endpoint.

You can also submit CREATE HANDLER to POST /v1/query or run it in the SQL editor. For example, to return one JSON object per row:

CREATE HANDLER double_number ON CLUSTER 'default'
URL '/double-number'
METHODS (GET)
AS SELECT {n:UInt32} * 2 AS result
FORMAT JSONEachRow;

Call the registered path under /v1/handlers with an authenticated GET request:

curl -X GET 'https://api.rawtree.com/v1/handlers/double-number?n=21' \
  -H "Authorization: Bearer $RAWTREE_API_KEY"

{"result":42}

Handler names and paths belong to the selected cluster, across its databases. The usual database query parameter or x-rawtree-database header selects the database used by unqualified table references when the endpoint runs. User sessions also supply the usual organization and cluster selectors. Native distributed DDL can resolve currentDatabase() when the handler is created or altered. Use qualified table names when an endpoint must always read from a specific database.

• Handler URLs are native database paths. Platform adds /v1/handlers to the public invocation path and removes that prefix when forwarding the request. URL '/hello' is called at /v1/handlers/hello; URL '/v1/handlers/hello' is called at /v1/handlers/v1/handlers/hello. Existing definitions keep their URLs, so callers of previously registered /v1/handlers/... paths must add the outer /v1/handlers prefix. URL prefixes and regular expressions are not supported.
• Only GET handlers with SELECT queries are supported. INSERT, CACHE INTO and URL table functions are rejected. METHODS (GET) is optional and is not inserted when omitted.
• Query parameters bind typed SQL parameters. They cannot override database credentials, query text, sessions or server settings. The names organization, cluster and database select the Platform scope; use param_cluster or param_database to bind SQL parameters named cluster or database. Handler parameters cannot be named default_format, readonly, log_comment, http_write_exception_in_output_format, max_execution_time, max_result_bytes, wait_end_of_query or buffer_size.
• Calls require read permission and use the caller's read identity. Database-role keys retain their table, column and row-policy grants. Query rate limits, usage enforcement and default execution/result limits apply. The administrator can override query defaults with SQL SETTINGS, as in the Query API. HEAD requests use the same permissions as GET and return no response body.
• Database errors retain their native HTTP status, headers and body, including missing handlers. Supported output formats encode execution failures as native exception records.
• Handler SQL submitted through /v1/query is executed exactly as submitted. Platform does not insert ON CLUSTER, METHODS, or rewrite URLs. To request distributed DDL, include ON CLUSTER 'default' after the handler name in CREATE, ALTER, or DROP. Without it, native database behavior determines the definition's scope. The cluster must support native HANDLER SQL.

To replace a handler, supply both its URL and SELECT query:

ALTER HANDLER double_number ON CLUSTER 'default'
URL '/double-number'
AS SELECT {n:UInt32} * 3 AS result FORMAT JSONEachRow;

Remove it with DROP HANDLER IF EXISTS double_number ON CLUSTER 'default'. CREATE HANDLER IF NOT EXISTS preserves an existing definition. The database validates handler URLs and rejects overlapping definitions with AMBIGUOUS_HANDLER. After a distributed-DDL timeout, inspect the replicas before changing definitions: timed-out DDL can still finish in the background. Coordinate direct database administration separately from Platform management.

HEAD /v1/handlers/{path}

Check a handler's response headers. The same read permissions and database grants apply as for GET.

Request:

# Read the handler headers without a response body.
curl -X HEAD -I 'https://api.rawtree.com/v1/handlers/double?database=analytics&value=21' \
  -H "Authorization: Bearer $RAWTREE_API_KEY"

Expected response: HTTP 200.

The response body is empty. Headers and errors depend on the handler's native output format.