๐ŸŽฏAPI Stability
Long-TermThis API is stable and will remain supported across versions with minimal breaking changes.

Summary

The findOrCreateBucketStorageEntity() mutation locates an existing bucket storage entity for the specified organization, or creates one if none exists. A bucket storage entity is a system configuration record that associates an organization with its external object storage target (S3, Azure Blob Storage, or GCS). Because this mutation is idempotent, you can call it safely at any point without creating duplicate records.

Call this mutation to confirm or initialize the bucket storage configuration before enabling transfers with addOrganizationForBucketTransfer(). The mutation returns the internal integer identifier of the bucket storage entity, confirming that the record is registered in the system.

Syntax

graphql
findOrCreateBucketStorageEntity(
      organizationId: String!
   ): Int!

The required organizationId argument is the unique string identifier of the organization. The mutation returns a non-null integer that is the internal identifier of the bucket storage entity. See the Show Organizations Query link to retrieve a list of organizations and their identifiers.

Hide Organizations Query

Show Organizations Query

Example

Raw
graphql
mutation {
  findOrCreateBucketStorageEntity (
    organizationId: "SINGLE_ORGANIZATION_ID"
    )
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  findOrCreateBucketStorageEntity (
    organizationId: \"SINGLE_ORGANIZATION_ID\"
    )
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  findOrCreateBucketStorageEntity (
    organizationId: \"SINGLE_ORGANIZATION_ID\"
    )
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  findOrCreateBucketStorageEntity ( ^
    organizationId: \"SINGLE_ORGANIZATION_ID\" ^
    ) ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  findOrCreateBucketStorageEntity (
    organizationId: \"SINGLE_ORGANIZATION_ID\"
    )
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  findOrCreateBucketStorageEntity (
    organizationId: \"SINGLE_ORGANIZATION_ID\"
    )
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  findOrCreateBucketStorageEntity (
    organizationId: \"SINGLE_ORGANIZATION_ID\"
    )
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  findOrCreateBucketStorageEntity (
    organizationId: \"SINGLE_ORGANIZATION_ID\"
    )
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();
Example Responses
Success (HTTP Response Code 200 OK)
json
{
  "data": {
    "findOrCreateBucketStorageEntity": 2
  }
}

Input Parameters

The organizationId argument is required. Obtain the value by querying searchOrganizations() and reading the organizationId field from each result entry.

Table: Input Parameters & Datatypes

Parameter Type Required Default Description
This table contains all input parameters for this mutation.
organizationId String yes ย  The unique string identifier of the organization for which to find or create the bucket storage entity. This value is assigned when the organization is created. Obtain it by querying searchOrganizations() and reading the organizationId field from the result entries.

Returned Values

The mutation returns a non-null integer (Int!) that is the internal identifier of the bucket storage entity. A positive value confirms that the entity exists and is registered in the system. This identifier is informational; subsequent bucket transfer mutations accept organizationId directly and do not require the storage entity identifier as input.