HTTP workflows and endpoints

Use HTTP for observation ingestion, read-only direct queries, semantic workflows, onboarding, health checks, and administration. Use gRPC for typed streaming results and explicit multimodal transactions.

Examples assume Bash, curl, a running server, and SHRIKEDB_HTTP=http://127.0.0.1:8182 from the guide configuration. Add a bearer token or API key when authentication is enabled. Keep administration endpoints on a trusted network.

Execute a read-only query

POST /api/v1/query/direct

Requires semantic_query.enabled and semantic_query.rest_enabled. The caller needs tenant Read permission. Writes are rejected. The response cap is 1–1,000 rows.

export SHRIKEDB_HTTP='http://127.0.0.1:8182'
curl --fail-with-body "$SHRIKEDB_HTTP/api/v1/query/direct" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"cypher","query":"RETURN 1 AS ready","limit":10}'

The response contains mode, fields, rows, row_count, returned_rows, limit, truncated, elapsed_ms, query_hash, and read_only. Check truncated before treating the rows as a complete result.

Ask a question about a cloud workspace

POST /api/v1/chat

Send a question with a tenant bearer token or private API key. Create the key in your Cloud workspace’s API endpoints screen, then set SHRIKEDB_API_KEY to that private value. The assistant prepares a bounded read-only query against that tenant’s graph, runs it, and returns an answer with the executed query and row count. The Cloud console’s Chat screen uses this endpoint.

curl --fail-with-body 'https://shrikedb.com/api/v1/chat' \
  -H "x-shrikedb-api-key: $SHRIKEDB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"question":"How many nodes are in this workspace?","history":[]}'

history accepts up to four previous {"question":"…","answer":"…"} pairs. The response contains answer, mode, query, rows, truncated, and elapsed_ms. The service sends the question, schema names, and selected result rows to OpenAI to compose the answer. Its model credential stays on the server. Requests cannot modify workspace data.

Load and search cloud vectors

The Cloud workspace offers the same workflow on its Vectors screen. Use a tenant bearer token or private API key. Vector writes and reads use the database owned by that tenant. Each named index has a fixed dimension; the first batch sets it.

export SHRIKEDB_HTTP='https://shrikedb.com'
export SHRIKEDB_API_KEY='your-private-key'
curl --fail-with-body "$SHRIKEDB_HTTP/api/v1/vector/insert" \
  -H "x-shrikedb-api-key: $SHRIKEDB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"index_name":"incident_text_v3","vectors":[{"entity_id":"10042","vector":[0.18,-0.04,0.61,0.22]}]}'
curl --fail-with-body "$SHRIKEDB_HTTP/api/v1/vector/search" \
  -H "x-shrikedb-api-key: $SHRIKEDB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"index_name":"incident_text_v3","query_vector":[0.17,-0.02,0.60,0.24],"k":10,"ef_search":128}'

GET /api/v1/vector/indexes lists the tenant’s named indexes. Insert accepts up to 256 distinct IDs per batch and 2 MiB per request. IDs are decimal strings so full 64-bit graph UIDs survive JSON clients. Search returns ordered matches with entity_id and metric score. Use the returned IDs in CALL vector.knn(...) and graph patterns in the query editor.

Append geospatial observations

POST /api/v1/spacekey/:index/observations

The caller needs tenant Write permission. Replace :index with a named index, such as events. The first append creates it. Add x-shrikedb-database to select a non-default logical database.

curl --fail-with-body "$SHRIKEDB_HTTP/api/v1/spacekey/events/observations" \
  -H 'Content-Type: application/json' \
  -d '{
    "batch": "example-0001",
    "domain": {"start_ms":1672531200000,"end_ms":1704067200000},
    "observations": [{
      "id":1,"entity":1001,"time_ms":1672531201000,
      "position":{"crs":"WGS84","x":-77.0,"y":38.9}
    }]
  }'

A successful response includes generation, run_digest, accepted, normalization receipts, commit_domain: "multimodal-transaction", and grid semantics. The server commits the batch through the same transaction and HA path used by other database writes.

Use TransactionInsertSpaceKey when graph, vector, key–value, and geospatial changes need one explicit commit. Read the index through Cypher or SPARQL.

Store and retrieve a payload

Create an appropriate schema first using POST /api/v1/schema with id, name, and fields. The payload API accepts base64-encoded bytes.

curl --fail-with-body "$SHRIKEDB_HTTP/api/v1/kv" \
  -H 'Content-Type: application/json' \
  -d '{"subject_id":0,"schema_id":1,"key":1001,"value":"aGVsbG8="}'
curl --fail-with-body "$SHRIKEDB_HTTP/api/v1/kv/0/1001"

This local example stores hello under schema 1, subject 0, key 1001. A read returns found and, when present, a base64 value. Use the gRPC methods for typed, bulk, or transactional operations.

Check service health

The guide configuration exposes the admin listener on 127.0.0.1:9190. Check readiness before routing traffic; a live process can still be recovering.

curl --fail-with-body http://127.0.0.1:9190/health/live
curl --fail-with-body http://127.0.0.1:9190/health/ready

Browse registered routes

The inventory below is generated from server route registration. It distinguishes the HTTP and admin listeners and links each family to its workflow documentation. Availability depends on feature configuration and caller permissions.

Data and administration

Geospatial

Onboarding

Semantic workflows and direct queries

Cloud tenant portal

Cloud accounts and platform administration

Cloud vector search

Cloud chat

Health · admin listener