REST API Reference

REST API Reference

Drasi Server Drasi Server A standalone Data Change Processing server running as a process or Docker container. Learn more exposes a REST API for managing sources Source A connection to an external system that Drasi monitors for data changes. Learn more , queries Continuous Query A query that runs continuously, maintaining an always-current result set as data changes. Learn more , and reactions Reaction A component that receives query result changes and takes action on them. Learn more .

Common Workflows

Start a complete pipeline dynamically

# 1. Create a source
curl -X POST http://localhost:8080/api/v1/sources \
  -H "Content-Type: application/json" \
  -d '{"kind":"postgres","id":"db","host":"localhost","port":5432,"database":"mydb","user":"user","password":"pass","tables":["public.items"]}'

# 2. Create a query that subscribes to the source
curl -X POST http://localhost:8080/api/v1/queries \
  -H "Content-Type: application/json" \
  -d '{"id":"active-items","query":"MATCH (i:items) WHERE i.active RETURN i","sources":[{"sourceId":"db"}]}'

# 3. Create a reaction that consumes query results
curl -X POST http://localhost:8080/api/v1/reactions \
  -H "Content-Type: application/json" \
  -d '{"kind":"log","id":"logger","queries":["active-items"]}'

# 4. Start all components (if autoStart was not set)
curl -X POST http://localhost:8080/api/v1/sources/db/start
curl -X POST http://localhost:8080/api/v1/queries/active-items/start
curl -X POST http://localhost:8080/api/v1/reactions/logger/start

Poll query results

# Get current query result set
curl http://localhost:8080/api/v1/queries/active-items/results

# Check if results have changed (compare counts or hashes)
watch -n 1 'curl -s http://localhost:8080/api/v1/queries/active-items/results | jq .data.count'

Restart a component

# Stop and restart a source (useful after database changes)
curl -X POST http://localhost:8080/api/v1/sources/db/stop
curl -X POST http://localhost:8080/api/v1/sources/db/start

Delete a pipeline (in order)

# Stop and delete in reverse order: reactions → queries → sources
curl -X DELETE http://localhost:8080/api/v1/reactions/logger
curl -X DELETE http://localhost:8080/api/v1/queries/active-items  
curl -X DELETE http://localhost:8080/api/v1/sources/db

Base URL

http://localhost:8080/api/v1/

API Documentation

Interactive API documentation is available at:

http://localhost:8080/api/v1/docs/

OpenAPI specification:

http://localhost:8080/api/v1/openapi.json

Response Format

All responses follow this structure:

{
  "status": "success",
  "message": "Operation completed",
  "data": { ... }
}

Error responses:

{
  "status": "error",
  "message": "Error description",
  "data": null
}

HTTP Status Codes

Common Error Responses

Resource not found:

{
  "status": "error",
  "message": "Source 'my-source' not found"
}

Duplicate ID:

{
  "status": "error",
  "message": "Source with id 'my-source' already exists"
}

Invalid configuration:

{
  "status": "error", 
  "message": "Invalid source config: missing required field 'host'"
}

Dependency in use:

{
  "status": "error",
  "message": "Cannot delete source 'my-source': subscribed by query 'my-query'"
}

Health

Check Health

GET /health

Response:

{"status":"healthy"}

Use for: Load balancer health checks, monitoring.

API Versions

List API Versions

GET /api/versions

Response:

{
  "versions": ["v1"]
}

Instances

List Instances

GET /api/v1/instances

Response:

{
  "status": "success",
  "data": [
    {
      "id": "default",
      "sources_count": 2,
      "queries_count": 3,
      "reactions_count": 2
    }
  ]
}

Sources

List Sources

GET /api/v1/sources

Response:

{
  "status": "success",
  "data": [
    {
      "id": "my-source",
      "kind": "postgres",
      "status": "running",
      "auto_start": true
    }
  ]
}

Create Source

POST /api/v1/sources
Content-Type: application/json

Request Body:

{
  "kind": "postgres",
  "id": "my-source",
  "auto_start": true,
  "host": "localhost",
  "port": 5432,
  "database": "mydb",
  "user": "postgres",
  "password": "secret",
  "tables": ["public.orders"]
}

Response:

{
  "status": "success",
  "message": "Source created",
  "data": {
    "id": "my-source",
    "kind": "postgres",
    "status": "starting"
  }
}

Get Source

GET /api/v1/sources/{id}

Response:

{
  "status": "success",
  "data": {
    "id": "my-source",
    "kind": "postgres",
    "status": "running",
    "config": { ... }
  }
}

Delete Source

DELETE /api/v1/sources/{id}

Response:

{
  "status": "success",
  "message": "Source deleted"
}

Start Source

POST /api/v1/sources/{id}/start

Response:

{
  "status": "success",
  "message": "Source started"
}

Stop Source

POST /api/v1/sources/{id}/stop

Response:

{
  "status": "success",
  "message": "Source stopped"
}

Queries

List Queries

GET /api/v1/queries

Response:

{
  "status": "success",
  "data": [
    {
      "id": "my-query",
      "status": "running",
      "sources": ["my-source"]
    }
  ]
}

Create Query

POST /api/v1/queries
Content-Type: application/json

Request Body:

{
  "id": "my-query",
  "query": "MATCH (n:Order) RETURN n",
  "sources": [
    {"source_id": "my-source"}
  ],
  "auto_start": true
}

Response:

{
  "status": "success",
  "message": "Query created",
  "data": {
    "id": "my-query",
    "status": "starting"
  }
}

Get Query

GET /api/v1/queries/{id}

Response:

{
  "status": "success",
  "data": {
    "id": "my-query",
    "status": "running",
    "query": "MATCH (n:Order) RETURN n",
    "sources": ["my-source"]
  }
}

Get Query Results

GET /api/v1/queries/{id}/results

Response:

{
  "status": "success",
  "data": {
    "results": [
      {"id": "1", "total": 100, "status": "pending"},
      {"id": "2", "total": 250, "status": "shipped"}
    ],
    "count": 2
  }
}

Delete Query

DELETE /api/v1/queries/{id}

Start Query

POST /api/v1/queries/{id}/start

Stop Query

POST /api/v1/queries/{id}/stop

Reactions

List Reactions

GET /api/v1/reactions

Response:

{
  "status": "success",
  "data": [
    {
      "id": "my-reaction",
      "kind": "log",
      "status": "running",
      "queries": ["my-query"]
    }
  ]
}

Create Reaction

POST /api/v1/reactions
Content-Type: application/json

Request Body:

{
  "kind": "log",
  "id": "my-reaction",
  "queries": ["my-query"],
  "auto_start": true
}

Get Reaction

GET /api/v1/reactions/{id}

Delete Reaction

DELETE /api/v1/reactions/{id}

Start Reaction

POST /api/v1/reactions/{id}/start

Stop Reaction

POST /api/v1/reactions/{id}/stop

Instance-Specific Endpoints

For multi-instance configurations, use instance-prefixed routes:

Sources

• GET /api/v1/instances/{instanceId}/sources
• POST /api/v1/instances/{instanceId}/sources
• GET /api/v1/instances/{instanceId}/sources/{id}
• DELETE /api/v1/instances/{instanceId}/sources/{id}
• POST /api/v1/instances/{instanceId}/sources/{id}/start
• POST /api/v1/instances/{instanceId}/sources/{id}/stop

Queries

• GET /api/v1/instances/{instanceId}/queries
• POST /api/v1/instances/{instanceId}/queries
• GET /api/v1/instances/{instanceId}/queries/{id}
• DELETE /api/v1/instances/{instanceId}/queries/{id}
• GET /api/v1/instances/{instanceId}/queries/{id}/results
• POST /api/v1/instances/{instanceId}/queries/{id}/start
• POST /api/v1/instances/{instanceId}/queries/{id}/stop

Reactions

• GET /api/v1/instances/{instanceId}/reactions
• POST /api/v1/instances/{instanceId}/reactions
• GET /api/v1/instances/{instanceId}/reactions/{id}
• DELETE /api/v1/instances/{instanceId}/reactions/{id}
• POST /api/v1/instances/{instanceId}/reactions/{id}/start
• POST /api/v1/instances/{instanceId}/reactions/{id}/stop

Examples

Create PostgreSQL Source

curl -X POST http://localhost:8080/api/v1/sources \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "postgres",
    "id": "orders-db",
    "host": "localhost",
    "port": 5432,
    "database": "ecommerce",
    "user": "postgres",
    "password": "secret",
    "tables": ["public.orders"]
  }'

Create Query with Join

curl -X POST http://localhost:8080/api/v1/queries \
  -H "Content-Type: application/json" \
  -d '{
    "id": "order-details",
    "query": "MATCH (o:orders)-[:CUSTOMER]->(c:customers) RETURN o.id, c.name",
    "sources": [{"source_id": "orders-db"}],
    "joins": [{
      "id": "CUSTOMER",
      "keys": [
        {"label": "orders", "property": "customer_id"},
        {"label": "customers", "property": "id"}
      ]
    }]
  }'

Create HTTP Reaction

curl -X POST http://localhost:8080/api/v1/reactions \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "http",
    "id": "webhook",
    "queries": ["order-details"],
    "base_url": "https://api.example.com",
    "routes": {
      "order-details": {
        "added": {
          "url": "/orders",
          "method": "POST"
        }
      }
    }
  }'