Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

HTTP API

The Fluree HTTP API provides RESTful endpoints for all database operations. This section documents the complete API surface including request formats, authentication, and error handling.

Core Endpoints

Overview

High-level introduction to the Fluree HTTP API, including:

  • API design principles
  • Authentication overview
  • Rate limiting (not built in; handled by a proxy or gateway)
  • API versioning

Endpoints

Complete reference for all HTTP endpoints:

  • POST /update - Submit update transactions (WHERE/DELETE/INSERT or SPARQL UPDATE)
  • POST /query - Execute queries (JSON-LD, SPARQL, Cypher)
  • POST /graphql/*ledger - GraphQL over the schema derived from the ledger’s data
  • GET /graphql-schema/*ledger - that schema as SDL
  • POST /multi-query - Bundle multiple queries against a shared snapshot (dedicated doc)
  • GET /v1/fluree/ledgers - List ledgers
  • GET /health - Health checks
  • GET /v1/fluree/stats - Server status
  • And more…

Multi-query envelope

Bundle multiple JSON-LD and/or SPARQL queries into a single request that runs against one shared snapshot moment, with envelope-level @context / opts defaults and per-alias result assembly.

GraphQL

A GraphQL endpoint on every ledger, with the schema derived from its data and SHACL shapes rather than registered. Read and write, with explain showing the JSON-LD query each field lowered to.

Bolt protocol

The Neo4j wire protocol served against the openCypher surface: protocol versions and session model, typed value mappings (nodes, relationships, temporal values), and explicit-transaction semantics.

Headers, Content Types, and Request Sizing

HTTP headers and request format details:

  • Content-Type negotiation
  • Accept headers for response formats
  • Request size limits
  • Compression support
  • Custom headers

Signed Requests (JWS/VC)

Cryptographically signed and verifiable requests:

  • JSON Web Signature (JWS) format
  • Verifiable Credentials (VC) support
  • Public key verification
  • DID authentication
  • Signature validation

Errors and Status Codes

HTTP status codes and error responses:

  • Standard HTTP status codes
  • Fluree-specific error codes
  • Error response format
  • Troubleshooting common errors

API Characteristics

RESTful Design

The Fluree API follows REST principles:

  • Resource-oriented URLs
  • Standard HTTP methods (GET, POST)
  • Stateless requests
  • Standard status codes

Content Negotiation

Fluree supports multiple content types for requests and responses:

Request Content-Types:

  • application/json - JSON-LD transactions and queries
  • application/sparql-query - SPARQL queries
  • text/turtle - Turtle RDF format
  • application/ld+json - Explicit JSON-LD

Response Content-Types:

  • application/json - Default JSON format
  • application/ld+json - JSON-LD with context
  • application/sparql-results+json - SPARQL result format

Authentication

Fluree supports multiple authentication mechanisms:

  1. No Authentication (development only)
  2. Signed Requests (JWS/VC for production)
  3. Bearer Tokens (JWT authentication)

See Signed Requests for cryptographic authentication details.

Quick Examples

Transaction Request

curl -X POST http://localhost:8090/v1/fluree/insert?ledger=mydb:main \
  -H "Content-Type: application/json" \
  -d '{
    "@context": {
      "ex": "http://example.org/ns/"
    },
    "@graph": [
      { "@id": "ex:alice", "ex:name": "Alice" }
    ]
  }'

Query Request

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/json" \
  -d '{
    "from": "mydb:main",
    "select": ["?name"],
    "where": [
      { "@id": "?person", "ex:name": "?name" }
    ]
  }'

SPARQL Query

curl -X POST http://localhost:8090/v1/fluree/query \
  -H "Content-Type: application/sparql-query" \
  -d 'SELECT ?name FROM <mydb:main> WHERE { ?person ex:name ?name }'

Health Check

curl http://localhost:8090/health

API Clients

Command Line (curl)

All examples in this documentation use curl for simplicity. Curl is available on all major platforms.

Programming Languages

Fluree’s HTTP API can be accessed from any language with HTTP client support:

JavaScript/TypeScript:

const response = await fetch('http://localhost:8090/v1/fluree/query', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: 'mydb:main',
    select: ['?name'],
    where: [{ '@id': '?person', 'ex:name': '?name' }]
  })
});
const results = await response.json();

Python:

import requests

response = requests.post('http://localhost:8090/v1/fluree/query', json={
    'from': 'mydb:main',
    'select': ['?name'],
    'where': [{'@id': '?person', 'ex:name': '?name'}]
})
results = response.json()

Java:

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8090/v1/fluree/query"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(queryJson))
    .build();
HttpResponse<String> response = client.send(request, 
    HttpResponse.BodyHandlers.ofString());

Development vs Production

Development Setup

For local development, the API typically runs without authentication:

fluree server run --listen-addr 0.0.0.0:8090

Access: http://localhost:8090

Production Setup

For production deployments, enable authentication and use HTTPS:

fluree server run \
  --listen-addr 0.0.0.0:8090 \
  --connection-config /etc/fluree/connection.jsonld \
  -- \
  --data-auth-mode required \
  --data-auth-trusted-issuer did:key:z6Mk...

The server speaks plain HTTP; terminate TLS at a reverse proxy or load balancer in front of it. See Configuration for storage and auth options.

Access: https://api.yourdomain.com

Always use:

  • HTTPS in production (terminated at the proxy)
  • Signed requests or Bearer tokens
  • Rate limiting (at the proxy or API gateway; the server has none built in)
  • Request size limits (--body-limit)

Performance Considerations

Request Size Limits

A single request body limit applies to all requests: 50MB by default, configurable with --body-limit. There is no response size limit.

See Headers and Request Sizing for details.

Connection Management

  • Keep-alive connections supported
  • HTTP/2 support available
  • WebSocket support for streaming (planned)

Caching

  • Query results can be cached (ETag support)
  • Immutable historical queries cache well
  • Current queries should not be cached aggressively