Skip to main content

Transactions

Endpoints for modifying data in ledgers.

fluree/transact​


POST /v1/fluree/transact

Commit a transaction to a ledger. This is the most flexible transaction endpoint, supporting where/delete/insert patterns for conditional updates.

Request Object​

KeyRequiredValue
@contextnoobject • a map of terms for the transaction (See our Guide on Using Context)
ledgeryesstring • the name of the existing ledger
insertnoobject or array • data to be asserted
wherenoobject or array • a subquery to bind logic variables for use in your delete and/or insert clauses
deletenoobject or array • data to be retracted

NOTE: While insert, delete, and where are not required, either/both insert & delete must be used to qualify a valid transaction. You could only insert data, you could only delete data, or you could use both insert + delete to qualify a sort of update to data state.

Example Request Object​


{
"@context": {
"schema": "http://schema.org/"
},
"ledger": "cookbook/base",
"where": { "@id": "?s", "schema:description": "We ❤️ All Blood" },
"delete": { "@id": "?s", "schema:description": "We ❤️ All Blood" },
"insert": {
"@id": "?s",
"schema:description": ["We ❤️ Human Blood", "We ❤️ Animal Blood"]
}
}

Curl Example​


curl --location 'http://localhost:58090/v1/fluree/transact' --header 'Content-Type: application/json' --data $'{
"@context": {
"schema": "http://schema.org/"
},
"ledger": "cookbook/base",
"where": { "@id": "?s", "schema:description": "We ❤️ All Blood" },
"delete": { "@id": "?s", "schema:description": "We ❤️ All Blood" },
"insert": {
"@id": "?s",
"schema:description": ["We ❤️ Human Blood", "We ❤️ Animal Blood"]
}
}'

Example Response​


{
"commit": {
"address": "fluree:file://cookbook/base/commit/bhkmj3wnwq2g4ji5l3zixl6os54uvhn6on3zgph6izyrxatoc4jn.json",
"hash": "bhkmj3wnwq2g4ji5l3zixl6os54uvhn6on3zgph6izyrxatoc4jn"
},
"t": 2,
"tx-id": "c1d0efce42e92f08bb45f32cf06b193c313eec08d7839f07464d1f244c4b307f",
"ledger": "cookbook/base"
}

fluree/insert​


POST /v1/fluree/insert

Insert new data into a ledger. This is a simplified endpoint for pure insertions.

Request Headers​

HeaderRequiredValue
Content-Typeyesstring • application/json or text/turtle
fluree-ledgeryesstring • the name of the target ledger

Request Body​

The request body should contain the data to insert, either as JSON-LD or Turtle format.

Example Request (JSON-LD)​


{
"@context": {
"ex": "http://example.org/",
"schema": "http://schema.org/"
},
"@id": "ex:alice",
"@type": "schema:Person",
"schema:name": "Alice",
"schema:age": 30
}

Curl Example​


curl --location 'http://localhost:58090/v1/fluree/insert' \
--header 'Content-Type: application/json' \
--header 'fluree-ledger: cookbook/base' \
--data '{
"@context": {
"ex": "http://example.org/",
"schema": "http://schema.org/"
},
"@id": "ex:alice",
"@type": "schema:Person",
"schema:name": "Alice",
"schema:age": 30
}'

Example Response​


{
"commit": {
"address": "fluree:file://cookbook/base/commit/buvyh74ej4rb3x5jm3htgiim5f5qeqntxhmaosxztkguumvb3ii.json",
"hash": "buvyh74ej4rb3x5jm3htgiim5f5qeqntxhmaosxztkguumvb3ii"
},
"t": 3,
"tx-id": "8e6e9863372b1d61b16e0f915172329308b41e316cc1028c2e7e28fcf7c348e6",
"ledger": "cookbook/base"
}

fluree/upsert​


POST /v1/fluree/upsert

Insert or update data in a ledger. If an entity with the given @id exists, its properties will be merged/updated. If it doesn't exist, a new entity will be created.

Request Headers​

HeaderRequiredValue
Content-Typeyesstring • application/json or text/turtle
fluree-ledgeryesstring • the name of the target ledger

Request Body​

The request body should contain the data to upsert, either as JSON-LD or Turtle format.

Example Request (JSON-LD)​


{
"@context": {
"ex": "http://example.org/",
"schema": "http://schema.org/"
},
"@id": "ex:alice",
"@type": "schema:Person",
"schema:name": "Alice Updated",
"schema:age": 31,
"schema:email": "alice@example.org"
}

Curl Example​


curl --location 'http://localhost:58090/v1/fluree/upsert' \
--header 'Content-Type: application/json' \
--header 'fluree-ledger: cookbook/base' \
--data '{
"@context": {
"ex": "http://example.org/",
"schema": "http://schema.org/"
},
"@id": "ex:alice",
"@type": "schema:Person",
"schema:name": "Alice Updated",
"schema:age": 31,
"schema:email": "alice@example.org"
}'

Example Response​


{
"commit": {
"address": "fluree:file://cookbook/base/commit/f46abtqcr2df6abaog6litbjunmulhzrsadc22pdafok5dj2lwp.json",
"hash": "f46abtqcr2df6abaog6litbjunmulhzrsadc22pdafok5dj2lwp"
},
"t": 4,
"tx-id": "912f872d1a3da1f2ac5792cf4971ed1129d7430c35f2b6663b575aa45c1d9851",
"ledger": "cookbook/base"
}

fluree/update​


POST /v1/fluree/update

Update data in a ledger using pattern matching. This is functionally equivalent to /v1/fluree/transact and supports the same where/delete/insert pattern for conditional updates.

Request Object​

KeyRequiredValue
@contextnoobject • a map of terms for the transaction (See our Guide on Using Context)
ledgeryesstring • the name of the existing ledger
wherenoobject or array • a subquery to bind logic variables for use in your delete and/or insert clauses
deletenoobject or array • data to be retracted
insertnoobject or array • data to be asserted

Example Request Object​


{
"@context": {
"ex": "http://example.org/",
"schema": "http://schema.org/"
},
"ledger": "cookbook/base",
"where": { "@id": "?s", "schema:name": "Alice" },
"delete": { "@id": "?s", "schema:name": "Alice" },
"insert": { "@id": "?s", "schema:name": "Alice Smith" }
}

Curl Example​


curl --location 'http://localhost:58090/v1/fluree/update' \
--header 'Content-Type: application/json' \
--data '{
"@context": {
"ex": "http://example.org/",
"schema": "http://schema.org/"
},
"ledger": "cookbook/base",
"where": { "@id": "?s", "schema:name": "Alice" },
"delete": { "@id": "?s", "schema:name": "Alice" },
"insert": { "@id": "?s", "schema:name": "Alice Smith" }
}'

Example Response​


{
"commit": {
"address": "fluree:file://cookbook/base/commit/pdkobei2kowojearflqck64og5lvrjbz2leyqcrsravhvo4rfrl.json",
"hash": "pdkobei2kowojearflqck64og5lvrjbz2leyqcrsravhvo4rfrl"
},
"t": 5,
"tx-id": "bef7fc4f5d674a2ba21b154474780538c4977e1fccfcbb3f1933bf1c66fe9502",
"ledger": "cookbook/base"
}