Create a queue
curl --request POST \
--url https://queue.{region}.basaltic.sh/v1/queues \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "orders",
"visibility_timeout_seconds": 30,
"message_retention_seconds": 345600,
"max_message_bytes": 262144,
"delay_seconds": 0,
"receive_wait_time_seconds": 0,
"kms_data_key_reuse_period_seconds": 300,
"content_based_deduplication": false,
"kms_key": "crn:kms:sa-saopaulo-1:acme:key/service-key",
"tags": {
"environment": "production",
"team": "backend"
}
}
'import requests
url = "https://queue.{region}.basaltic.sh/v1/queues"
payload = {
"name": "orders",
"visibility_timeout_seconds": 30,
"message_retention_seconds": 345600,
"max_message_bytes": 262144,
"delay_seconds": 0,
"receive_wait_time_seconds": 0,
"kms_data_key_reuse_period_seconds": 300,
"content_based_deduplication": False,
"kms_key": "crn:kms:sa-saopaulo-1:acme:key/service-key",
"tags": {
"environment": "production",
"team": "backend"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'orders',
visibility_timeout_seconds: 30,
message_retention_seconds: 345600,
max_message_bytes: 262144,
delay_seconds: 0,
receive_wait_time_seconds: 0,
kms_data_key_reuse_period_seconds: 300,
content_based_deduplication: false,
kms_key: 'crn:kms:sa-saopaulo-1:acme:key/service-key',
tags: {environment: 'production', team: 'backend'}
})
};
fetch('https://queue.{region}.basaltic.sh/v1/queues', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://queue.{region}.basaltic.sh/v1/queues",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'orders',
'visibility_timeout_seconds' => 30,
'message_retention_seconds' => 345600,
'max_message_bytes' => 262144,
'delay_seconds' => 0,
'receive_wait_time_seconds' => 0,
'kms_data_key_reuse_period_seconds' => 300,
'content_based_deduplication' => false,
'kms_key' => 'crn:kms:sa-saopaulo-1:acme:key/service-key',
'tags' => [
'environment' => 'production',
'team' => 'backend'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://queue.{region}.basaltic.sh/v1/queues"
payload := strings.NewReader("{\n \"name\": \"orders\",\n \"visibility_timeout_seconds\": 30,\n \"message_retention_seconds\": 345600,\n \"max_message_bytes\": 262144,\n \"delay_seconds\": 0,\n \"receive_wait_time_seconds\": 0,\n \"kms_data_key_reuse_period_seconds\": 300,\n \"content_based_deduplication\": false,\n \"kms_key\": \"crn:kms:sa-saopaulo-1:acme:key/service-key\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://queue.{region}.basaltic.sh/v1/queues")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"orders\",\n \"visibility_timeout_seconds\": 30,\n \"message_retention_seconds\": 345600,\n \"max_message_bytes\": 262144,\n \"delay_seconds\": 0,\n \"receive_wait_time_seconds\": 0,\n \"kms_data_key_reuse_period_seconds\": 300,\n \"content_based_deduplication\": false,\n \"kms_key\": \"crn:kms:sa-saopaulo-1:acme:key/service-key\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://queue.{region}.basaltic.sh/v1/queues")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"orders\",\n \"visibility_timeout_seconds\": 30,\n \"message_retention_seconds\": 345600,\n \"max_message_bytes\": 262144,\n \"delay_seconds\": 0,\n \"receive_wait_time_seconds\": 0,\n \"kms_data_key_reuse_period_seconds\": 300,\n \"content_based_deduplication\": false,\n \"kms_key\": \"crn:kms:sa-saopaulo-1:acme:key/service-key\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}"
response = http.request(request)
puts response.read_body{
"queue": {
"id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"crn": "crn:queue:sa-saopaulo-1:my-account:queue/orders",
"name": "orders",
"kind": "standard",
"attributes": {
"visibility_timeout_seconds": 30,
"message_retention_seconds": 345600,
"max_message_bytes": 262144,
"delay_seconds": 0,
"receive_wait_time_seconds": 0,
"kms_data_key_reuse_period_seconds": 300
},
"created_at": "2026-01-15T09:30:00Z",
"updated_at": "2026-01-18T11:45:00Z",
"redrive_policy": {
"dead_letter_queue": {
"id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"crn": "crn:queue:sa-saopaulo-1:acme:queue/failed-orders",
"name": "failed-orders"
},
"max_receive_count": 5
},
"content_based_deduplication": false,
"kms_key": {
"id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"crn": "crn:kms:sa-saopaulo-1:acme:key/service-key",
"name": "service-key"
},
"tags": {
"environment": "production",
"team": "backend"
},
"depth": {
"approximate_available": 42,
"approximate_in_flight": 3,
"approximate_delayed": 0,
"counts_capped": false
}
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "ACCESS_DENIED",
"message": "You don't have permission to perform this action",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"params": {
"instances": 2,
"pools": 0
}
}
}{
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "This Idempotency-Key was already used with a different request payload",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}Queues
Create a queue
The kind is derived from the name: a name ending in .fifo
creates a FIFO queue, anything else a standard one. There is no
separate flag, so the two can never disagree.
POST
/
v1
/
queues
Create a queue
curl --request POST \
--url https://queue.{region}.basaltic.sh/v1/queues \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "orders",
"visibility_timeout_seconds": 30,
"message_retention_seconds": 345600,
"max_message_bytes": 262144,
"delay_seconds": 0,
"receive_wait_time_seconds": 0,
"kms_data_key_reuse_period_seconds": 300,
"content_based_deduplication": false,
"kms_key": "crn:kms:sa-saopaulo-1:acme:key/service-key",
"tags": {
"environment": "production",
"team": "backend"
}
}
'import requests
url = "https://queue.{region}.basaltic.sh/v1/queues"
payload = {
"name": "orders",
"visibility_timeout_seconds": 30,
"message_retention_seconds": 345600,
"max_message_bytes": 262144,
"delay_seconds": 0,
"receive_wait_time_seconds": 0,
"kms_data_key_reuse_period_seconds": 300,
"content_based_deduplication": False,
"kms_key": "crn:kms:sa-saopaulo-1:acme:key/service-key",
"tags": {
"environment": "production",
"team": "backend"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'orders',
visibility_timeout_seconds: 30,
message_retention_seconds: 345600,
max_message_bytes: 262144,
delay_seconds: 0,
receive_wait_time_seconds: 0,
kms_data_key_reuse_period_seconds: 300,
content_based_deduplication: false,
kms_key: 'crn:kms:sa-saopaulo-1:acme:key/service-key',
tags: {environment: 'production', team: 'backend'}
})
};
fetch('https://queue.{region}.basaltic.sh/v1/queues', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://queue.{region}.basaltic.sh/v1/queues",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'orders',
'visibility_timeout_seconds' => 30,
'message_retention_seconds' => 345600,
'max_message_bytes' => 262144,
'delay_seconds' => 0,
'receive_wait_time_seconds' => 0,
'kms_data_key_reuse_period_seconds' => 300,
'content_based_deduplication' => false,
'kms_key' => 'crn:kms:sa-saopaulo-1:acme:key/service-key',
'tags' => [
'environment' => 'production',
'team' => 'backend'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://queue.{region}.basaltic.sh/v1/queues"
payload := strings.NewReader("{\n \"name\": \"orders\",\n \"visibility_timeout_seconds\": 30,\n \"message_retention_seconds\": 345600,\n \"max_message_bytes\": 262144,\n \"delay_seconds\": 0,\n \"receive_wait_time_seconds\": 0,\n \"kms_data_key_reuse_period_seconds\": 300,\n \"content_based_deduplication\": false,\n \"kms_key\": \"crn:kms:sa-saopaulo-1:acme:key/service-key\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://queue.{region}.basaltic.sh/v1/queues")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"orders\",\n \"visibility_timeout_seconds\": 30,\n \"message_retention_seconds\": 345600,\n \"max_message_bytes\": 262144,\n \"delay_seconds\": 0,\n \"receive_wait_time_seconds\": 0,\n \"kms_data_key_reuse_period_seconds\": 300,\n \"content_based_deduplication\": false,\n \"kms_key\": \"crn:kms:sa-saopaulo-1:acme:key/service-key\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://queue.{region}.basaltic.sh/v1/queues")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"orders\",\n \"visibility_timeout_seconds\": 30,\n \"message_retention_seconds\": 345600,\n \"max_message_bytes\": 262144,\n \"delay_seconds\": 0,\n \"receive_wait_time_seconds\": 0,\n \"kms_data_key_reuse_period_seconds\": 300,\n \"content_based_deduplication\": false,\n \"kms_key\": \"crn:kms:sa-saopaulo-1:acme:key/service-key\",\n \"tags\": {\n \"environment\": \"production\",\n \"team\": \"backend\"\n }\n}"
response = http.request(request)
puts response.read_body{
"queue": {
"id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"crn": "crn:queue:sa-saopaulo-1:my-account:queue/orders",
"name": "orders",
"kind": "standard",
"attributes": {
"visibility_timeout_seconds": 30,
"message_retention_seconds": 345600,
"max_message_bytes": 262144,
"delay_seconds": 0,
"receive_wait_time_seconds": 0,
"kms_data_key_reuse_period_seconds": 300
},
"created_at": "2026-01-15T09:30:00Z",
"updated_at": "2026-01-18T11:45:00Z",
"redrive_policy": {
"dead_letter_queue": {
"id": "b2c3d4e5-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"crn": "crn:queue:sa-saopaulo-1:acme:queue/failed-orders",
"name": "failed-orders"
},
"max_receive_count": 5
},
"content_based_deduplication": false,
"kms_key": {
"id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"crn": "crn:kms:sa-saopaulo-1:acme:key/service-key",
"name": "service-key"
},
"tags": {
"environment": "production",
"team": "backend"
},
"depth": {
"approximate_available": 42,
"approximate_in_flight": 3,
"approximate_delayed": 0,
"counts_capped": false
}
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "ACCESS_DENIED",
"message": "You don't have permission to perform this action",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "INVALID_INPUT",
"message": "Invalid request parameters",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"params": {
"instances": 2,
"pools": 0
}
}
}{
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "This Idempotency-Key was already used with a different request payload",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}Requires the IAM action
queue:CreateQueue. See QUEUE permissions for the full list, what each one covers, and an example policy.Authorizations
An OAuth 2.0 bearer token, sent as Authorization: Bearer <token>.
This is the recommended way to authenticate.
Get one by exchanging a service account's access key pair at
POST /v1/oauth/token with grant_type=client_credentials. It is the
standard client-credentials grant, so any OAuth-aware library will
obtain and refresh it for you.
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
Tokens last an hour by default. The same access key pair is separately your AWS SigV4 credential for the S3-compatible object endpoint, which speaks nothing else.
Headers
Optional client-generated key that makes a create replay-safe. Retrying a request with the same key returns the original outcome verbatim instead of creating a duplicate resource. Reusing a key with a different request body is rejected (422); a request whose key is still being processed returns 409. Records are honored for 24 hours. Use a UUID or similarly unique token.
Maximum string length:
255Body
application/json
Letters, digits, dot, dash, or underscore, starting with a
letter or digit. A name ending in .fifo creates a FIFO
queue. Resource names must not start with the literal crn: prefix or be UUIDs (canonical, compact, braced, or urn:uuid: forms, in either case).
Maximum string length:
80Example:
"orders"
Required range:
0 <= x <= 43200Example:
30
Required range:
60 <= x <= 1209600Example:
345600
Required range:
1024 <= x <= 262144Example:
262144
Required range:
0 <= x <= 900Example:
0
Required range:
0 <= x <= 20Example:
0
Required range:
60 <= x <= 86400Example:
300
FIFO queues only.
Example:
false
KMS key UUID, CRN or account-scoped name. Omit to use the platform key.
Example:
"crn:kms:sa-saopaulo-1:acme:key/service-key"
Target queue UUID, CRN or account-scoped name, resolved once and stored as an immutable UUID binding. Must be owned by this account, in this region, of the same kind, and different from the source queue. Invalid syntax, type or region returns 400; missing or foreign targets return 404. No lookup fallback is performed.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Example:
{
"environment": "production",
"team": "backend"
}
Response
Queue created.
Show child attributes
Show child attributes