gRPC and HTTP API reference

Browse generated gRPC methods, message fields, enums, streaming behavior, HTTP workflows, authentication metadata, and downloadable protocol definitions.

Search the reference

Loading the search index…

gRPC

Database API

Queries, graph reads, vectors, key–value operations, geospatial writes, and multimodal transactions.

Browse database methods ↗

Identity

Access management

Tenants, users, roles, API keys, login, and token rotation.

Browse identity methods ↗

HTTP

JSON workflows

Direct queries, transactional observation ingestion, administration, and onboarding.

Explore HTTP endpoints ↗

For complete requests, read the multimodal examples. Self-hosted language writes use gRPC with tenant Write permission and their server feature settings. The Cloud workspace and published HTTP query endpoints serve read queries.

Make your first call

Start a server using the quickstart configuration. These examples use its loopback ports: gRPC 50251, HTTP 8182, and administration 9190.

Download the database definition and identity definition. Supply the protocol file to grpcurl because the server does not expose reflection.

mkdir -p "$HOME/shrikedb-api"
curl --fail -o "$HOME/shrikedb-api/shrikedb.v2.proto" \
  https://shrikedb.com/downloads/shrikedb.v2.proto
export SHRIKEDB_API_DIR="$HOME/shrikedb-api"
grpcurl -plaintext \
  -import-path "$SHRIKEDB_API_DIR" -proto shrikedb.v2.proto \
  -d '{"query":"RETURN 1 AS ready"}' \
  127.0.0.1:50251 shrikedb.v2.ShrikeDbService/ExecuteCypher

The query returns one row with ready equal to 1. ProtoJSON represents its typed integer as {"bindings":{"ready":{"intVal":"1"}}}.

Wire format

Concept	Client behavior
64-bit integers	ProtoJSON represents these as decimal strings. Preserve the full range; avoid JavaScript Number for large IDs.
Bytes	Use base64 in ProtoJSON and HTTP byte-value fields.
oneof	Set at most one member of the named group. Query and result values use discriminated fields.
Optional fields	Omission differs from explicitly setting a default value. Follow the method's semantics.
Repeated and map fields	Arrays and JSON objects respectively. Map keys are strings in JSON.
Streaming	Read until the stream finishes and check its final status. Rows received before an error do not make a complete result.

Authentication and database selection

Authenticated deployments accept authorization: Bearer <JWT> or x-shrikedb-api-key: <key>. Add x-shrikedb-database to select a logical database.

grpcurl \
  -import-path "$SHRIKEDB_API_DIR" -proto shrikedb.v2.proto \
  -H "authorization: Bearer $SHRIKEDB_ACCESS_TOKEN" \
  -H "x-shrikedb-database: $SHRIKEDB_DATABASE" \
  -d '{"query":"RETURN 1 AS ready"}' \
  "$SHRIKEDB_GRPC_TLS_ADDRESS" shrikedb.v2.ShrikeDbService/ExecuteCypher

Set the token, logical database ID, and TLS host and port for your deployment. See connection setup for complete client configuration.

Failures and retries

Check gRPC status even when a streaming request has returned rows. Apply a client deadline suited to the operation. SpaceKey append supports an identical retry with the same batch token. Transaction clients should retain their transaction ID and inspect the commit outcome after an ambiguous response.

ExecuteSPARQLUpdate returns a committed receipt for supported standalone RDF DATA changes. A timed-out call has an uncertain outcome; read the affected triples before deciding whether to retry.

Version and availability

This reference is generated from the checked-in v2 protocol definitions. Match client definitions to the server revision. Feature configuration, authorization, and deployment mode determine method availability.