POST /v2/commands/completions
cURL
Python
JavaScript
PHP
Go
Java
Ruby
curl --request POST \
--url 'http://localhost:7575/v2/commands/completions' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}'
import json
import requests
url = "http://localhost:7575/v2/commands/completions"
headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
payload = json.loads(r'''{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}''')
response = requests.request(
"POST", url, headers=headers, json=payload
)
print(response.text)
const response = await fetch('http://localhost:7575/v2/commands/completions', {
method: 'POST',
headers: {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
body: JSON.stringify({
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}),
});
console.log(await response.text());
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'http://localhost:7575/v2/commands/completions',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => <<<'JSON'
{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}
JSON,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
echo $response;
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "http://localhost:7575/v2/commands/completions", bytes.NewBufferString(`{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}`))
req.Header.Set("Authorization", "Bearer <token>")
req.Header.Set("Content-Type", "application/json")
response, _ := http.DefaultClient.Do(req)
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
var request = HttpRequest.newBuilder()
.uri(URI.create("http://localhost:7575/v2/commands/completions"))
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("""
{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}
"""))
.build();
var response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'uri'
uri = URI('http://localhost:7575/v2/commands/completions')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = <<~JSON
{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}
JSON
response = Net::HTTP.start(uri.hostname, uri.port) do |http|
http.request(request)
end
puts response.body
200
400
default
[
{
"completionResponse": {
"Completion": {
"value": {
"commandId": "<string>",
"status": {
"code": 123,
"message": "<string>",
"details": [
"<object>"
]
},
"updateId": "<string>",
"userId": "<string>",
"actAs": [
"<string>"
],
"submissionId": "<string>",
"deduplicationPeriod": "<object>",
"traceContext": {
"traceparent": "<string>",
"tracestate": "<string>"
},
"offset": 123,
"synchronizerTime": {
"synchronizerId": "<string>",
"recordTime": "<string>"
},
"paidTrafficCost": 123
}
}
}
}
]
<string>
{
"code": "<string>",
"cause": "<string>",
"correlationId": "<string>",
"traceId": "<string>",
"context": {},
"resources": [
[
"<string>"
]
],
"errorCategory": 123,
"grpcCodeValue": 123,
"retryInfo": "<string>",
"definiteAnswer": false
}
POST
/
v2
/
commands
/
completions
cURL
Python
JavaScript
PHP
Go
Java
Ruby
curl --request POST \
--url 'http://localhost:7575/v2/commands/completions' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}'
import json
import requests
url = "http://localhost:7575/v2/commands/completions"
headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
payload = json.loads(r'''{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}''')
response = requests.request(
"POST", url, headers=headers, json=payload
)
print(response.text)
const response = await fetch('http://localhost:7575/v2/commands/completions', {
method: 'POST',
headers: {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
body: JSON.stringify({
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}),
});
console.log(await response.text());
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'http://localhost:7575/v2/commands/completions',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => <<<'JSON'
{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}
JSON,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
echo $response;
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "http://localhost:7575/v2/commands/completions", bytes.NewBufferString(`{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}`))
req.Header.Set("Authorization", "Bearer <token>")
req.Header.Set("Content-Type", "application/json")
response, _ := http.DefaultClient.Do(req)
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
var request = HttpRequest.newBuilder()
.uri(URI.create("http://localhost:7575/v2/commands/completions"))
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("""
{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}
"""))
.build();
var response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'uri'
uri = URI('http://localhost:7575/v2/commands/completions')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = <<~JSON
{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}
JSON
response = Net::HTTP.start(uri.hostname, uri.port) do |http|
http.request(request)
end
puts response.body
200
400
default
[
{
"completionResponse": {
"Completion": {
"value": {
"commandId": "<string>",
"status": {
"code": 123,
"message": "<string>",
"details": [
"<object>"
]
},
"updateId": "<string>",
"userId": "<string>",
"actAs": [
"<string>"
],
"submissionId": "<string>",
"deduplicationPeriod": "<object>",
"traceContext": {
"traceparent": "<string>",
"tracestate": "<string>"
},
"offset": 123,
"synchronizerTime": {
"synchronizerId": "<string>",
"recordTime": "<string>"
},
"paidTrafficCost": 123
}
}
}
}
]
<string>
{
"code": "<string>",
"cause": "<string>",
"correlationId": "<string>",
"traceId": "<string>",
"context": {},
"resources": [
[
"<string>"
]
],
"errorCategory": 123,
"grpcCodeValue": 123,
"retryInfo": "<string>",
"definiteAnswer": false
}
Query completions list (blocking call) Deprecated: please use GetCompletions instead. Subscribe to command completion events. Notice: This endpoint should be used for small results set. When number of results exceeded node configuration limit (http-list-max-elements-limit) there will be an error (413 Content Too Large) returned. Increasing this limit may lead to performance issues and high memory consumption.
OpenAPIUpdated 3.5
cURL
Python
JavaScript
PHP
Go
Java
Ruby
curl --request POST \
--url 'http://localhost:7575/v2/commands/completions' \
--header 'Authorization: Bearer $TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}'
import json
import requests
url = "http://localhost:7575/v2/commands/completions"
headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
payload = json.loads(r'''{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}''')
response = requests.request(
"POST", url, headers=headers, json=payload
)
print(response.text)
const response = await fetch('http://localhost:7575/v2/commands/completions', {
method: 'POST',
headers: {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
},
body: JSON.stringify({
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}),
});
console.log(await response.text());
<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'http://localhost:7575/v2/commands/completions',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => <<<'JSON'
{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}
JSON,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
echo $response;
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "http://localhost:7575/v2/commands/completions", bytes.NewBufferString(`{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}`))
req.Header.Set("Authorization", "Bearer <token>")
req.Header.Set("Content-Type", "application/json")
response, _ := http.DefaultClient.Do(req)
defer response.Body.Close()
body, _ := io.ReadAll(response.Body)
fmt.Println(string(body))
}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
var request = HttpRequest.newBuilder()
.uri(URI.create("http://localhost:7575/v2/commands/completions"))
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("""
{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}
"""))
.build();
var response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
require 'net/http'
require 'uri'
uri = URI('http://localhost:7575/v2/commands/completions')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = <<~JSON
{
"userId": "<string>",
"parties": [
"<string>"
],
"beginExclusive": 123
}
JSON
response = Net::HTTP.start(uri.hostname, uri.port) do |http|
http.request(request)
end
puts response.body
200
400
default
[
{
"completionResponse": {
"Completion": {
"value": {
"commandId": "<string>",
"status": {
"code": 123,
"message": "<string>",
"details": [
"<object>"
]
},
"updateId": "<string>",
"userId": "<string>",
"actAs": [
"<string>"
],
"submissionId": "<string>",
"deduplicationPeriod": "<object>",
"traceContext": {
"traceparent": "<string>",
"tracestate": "<string>"
},
"offset": 123,
"synchronizerTime": {
"synchronizerId": "<string>",
"recordTime": "<string>"
},
"paidTrafficCost": 123
}
}
}
}
]
<string>
{
"code": "<string>",
"cause": "<string>",
"correlationId": "<string>",
"traceId": "<string>",
"context": {},
"resources": [
[
"<string>"
]
],
"errorCategory": 123,
"grpcCodeValue": 123,
"retryInfo": "<string>",
"definiteAnswer": false
}
Authorizations
httpAuth
Authorization
string
required
HTTP bearer authentication. Send the token as
Authorization: Bearer <token>. Ledger API standard JWT tokenapiKeyAuth
Sec-WebSocket-Protocol
string
required
API key authentication in the header. Ledger API standard JWT token (websocket)
Query parameters
limit
number
OpenAPI type:
integer (int64).maximum number of elements to return, this param is ignored if is bigger than server settingstream_idle_timeout_ms
number
OpenAPI type:
integer (int64).timeout to complete and send result if no new elements are received (for open ended streams)Body
application/json
userId
string
Only completions of commands submitted with the same user_id will be visible in the stream. Must be a valid UserIdString (as described in
value.proto). Required unless authentication is used with a user token. In that case, the token’s user-id will be used for the request’s user_id. Optionalparties
string[]
required
Non-empty list of parties whose data should be included. The stream shows only completions of commands for which at least one of the
act_as parties is in the given set of parties. Must be a valid PartyIdString (as described in value.proto). Required: must be non-emptybeginExclusive
number
OpenAPI type:
integer (int64).This optional field indicates the minimum offset for completions. This can be used to resume an earlier completion stream. If not set the ledger uses the ledger begin offset instead. If specified, it must be a valid absolute offset (positive integer) or zero (ledger begin offset). If the ledger has been pruned, this parameter must be specified and greater than the pruning offset. OptionalResponses
200
application/json
value
CompletionStreamResponse[]
required
Show child attributes
Show child attributes
completionResponse
CompletionResponse
Required
Show child attributes
Show child attributes
Variant 1
object
Show child attributes
Show child attributes
Completion
Completion
required
A completion represents the status of a submitted command on the ledger: it can be successful or failed.
Show child attributes
Show child attributes
value
Completion1
required
A completion represents the status of a submitted command on the ledger: it can be successful or failed.
Show child attributes
Show child attributes
commandId
string
required
The ID of the succeeded or failed command. Must be a valid LedgerString (as described in
value.proto). Requiredstatus
JsStatus
Identifies the exact type of the error. It uses the same format of conveying error details as it is used for the RPC responses of the APIs. Optional
updateId
string
The update_id of the transaction or reassignment that resulted from the command with command_id. Only set for successfully executed commands. Must be a valid LedgerString (as described in
value.proto). OptionaluserId
string
required
The user-id that was used for the submission, as described in
commands.proto. Must be a valid UserIdString (as described in value.proto). RequiredactAs
string[]
required
The set of parties on whose behalf the commands were executed. Contains the
act_as parties from commands.proto filtered to the requesting parties in CompletionStreamRequest. The order of the parties need not be the same as in the submission. Each element must be a valid PartyIdString (as described in value.proto). Required: must be non-emptysubmissionId
string
The submission ID this completion refers to, as described in
commands.proto. Must be a valid LedgerString (as described in value.proto). OptionaldeduplicationPeriod
DeduplicationPeriod1
The actual deduplication window used for the submission, which is derived from
Commands.deduplication_period. The ledger may convert the deduplication period into other descriptions and extend the period in implementation-specified ways. Used to audit the deduplication guarantee described in commands.proto. The deduplication guarantee applies even if the completion omits this field. OptionalShow child attributes
Show child attributes
Variant 1
object
Show child attributes
Show child attributes
DeduplicationDuration
DeduplicationDuration1
required
Variant 2
object
traceContext
TraceContext
The Ledger API trace context The trace context transported in this message corresponds to the trace context supplied by the client application in a HTTP2 header of the original command submission. We typically use a header to transfer this type of information. Here we use message body, because it is used in gRPC streams which do not support per message headers. This field will be populated with the trace context contained in the original submission. If that was not provided, a unique ledger-api-server generated trace context will be used instead. Optional
Show child attributes
Show child attributes
traceparent
string
https://www.w3.org/TR/trace-context/ Optional
tracestate
string
Optional
offset
integer (int64)
required
May be used in a subsequent CompletionStreamRequest to resume the consumption of this stream at a later time. Must be a valid absolute offset (positive integer). Required
synchronizerTime
SynchronizerTime
required
The synchronizer along with its record time. The synchronizer id provided, in case of - successful/failed transactions: identifies the synchronizer of the transaction - for successful/failed unassign commands: identifies the source synchronizer - for successful/failed assign commands: identifies the target synchronizer Required
paidTrafficCost
integer (int64)
The traffic cost paid by this participant node for the confirmation request for the submitted command. Commands whose execution is rejected before their corresponding confirmation request is ordered by the synchronizer will report a paid traffic cost of zero. If a confirmation request is ordered for a command, but the request fails (e.g., due to contention with a concurrent contract archival), the traffic cost is paid and reported on the failed completion for the request. If you want to correlate the traffic cost of a successful completion with the transaction that resulted from the command, you can use the
offset field to retrieve the transaction using UpdateService.GetUpdateByOffset on the same participant node; or alternatively use the update_id field to retrieve the transaction using UpdateService.GetUpdateById on any participant node that sees the transaction. Note: for completions processed before the participant started serving traffic cost on the Ledger API, this field will be set to zero. Additionally, the total cost incurred by the submitting node for the submission of the transaction may be greater than the reported cost, for example if retries were issued due to failed submissions to the synchronizer. The cost reported here is the one paid for ordering the confirmation request. OptionalVariant 3
object
Show child attributes
Show child attributes
OffsetCheckpoint
OffsetCheckpoint
required
OffsetCheckpoints may be used to: - detect time out of commands. - provide an offset which can be used to restart consumption.
Show child attributes
Show child attributes
value
OffsetCheckpoint1
required
OffsetCheckpoints may be used to: - detect time out of commands. - provide an offset which can be used to restart consumption.
Show child attributes
Show child attributes
offset
integer (int64)
required
The participant’s offset, the details of the offset field are described in
community/ledger-api/README.md. Must be a valid absolute offset (positive integer). RequiredsynchronizerTimes
SynchronizerTime[]
The times associated with each synchronizer at this offset. Optional: can be empty
400
Invalid value, Invalid value for: body, Invalid value for: query parameter limit, Invalid value for: query parameter stream_idle_timeout_mstext/plain
value
string
required
default
application/json
code
string
required
cause
string
required
correlationId
string
traceId
string
context
Map_String
required
resources
Tuple2_String_String[]
errorCategory
integer (int32)
required
grpcCodeValue
integer (int32)
retryInfo
string
definiteAnswer
boolean
History
Updated
3.5The POST /v2/commands/completions operation changed in this snapshot.