S3 Object Storage API
Buckets, credentials, replication, pull import, and dedicated servers (v2.10)
Overview
Manage RackCorp S3 from POST https://api.rackcorp.net/api/rest/v2.10/json.php
with Authorization: Bearer YOUR_JWT_TOKEN and a JSON body containing cmd.
Identifiers are s3BucketId, s3CredentialId, s3RegionId, and s3ServerId.
A subset of bucket and credential calls also exist as REST paths under /storages3. The command API below is the full surface. See openapi.json for the path map.
Concepts and endpoints
Two storage classes:
HIGHSPEED— placed on an S3 server in a high-speed region. Required for Object Lock, zone replication, and pull import.ARCHIVE— always served fromhttps://s3.rackcorp.com. Not bound to a dedicated server.
Bucket and credential responses include s3RegionEndpoint. Point S3 clients at that URL.
High-speed buckets use the server endpoint. When a credential is attached to buckets on a single endpoint, storage.s3.credential.get also returns s3RegionEndpoint.
Bucket names are lowercased and must be 3–63 characters, DNS-style (a-z, 0-9, ., -), not an IP address, and not the reserved name health.
On shared servers a name is globally unique, including deleted buckets. On a dedicated server the name only has to be unique on that server.
Creates and updates set operational status to PENDING until the storage platform applies them.
List calls return ACTIVE and INACTIVE records.
Optional pagination is resStart (default 0) and resWindow. Name filters are substring matches.
aws --endpoint-url "$S3_REGION_ENDPOINT" s3 ls s3://acme-backups
Regions
List regions before creating a bucket. s3RegionHighSpeed and s3RegionArchive say which storage classes that region offers. s3RegionEndpoint is filled from an active server, or from the archive endpoint when the region is archive-only.
POST storage.s3.region.getall
{
"cmd": "storage.s3.region.getall",
"highSpeedOnly": true,
"activeServerOnly": true
}
| Parameter | Required | Description |
|---|---|---|
s3RegionName | No | Substring filter on the region name. A string or an array of strings. |
highSpeedOnly | No | Only regions with high-speed storage. |
activeServerOnly | No | Only regions that have an active S3 server. |
resStart, resWindow | No | Pagination. |
The response regions array includes s3RegionId, s3RegionName, s3RegionCode, s3RegionHighSpeed, and s3RegionArchive.
POST storage.s3.region.get
Body: s3RegionId (or id). Returns region.
POST storage.s3.region.create
{
"cmd": "storage.s3.region.create",
"s3RegionName": "Ulaanbaatar",
"s3RegionCode": "mn-mgl1",
"s3RegionHighSpeed": "Y",
"s3RegionArchive": "N"
}
s3RegionName (1–128 characters) and s3RegionCode (1–64, lowercased to a-z, 0-9, and -) are required. Codes are unique. Optional customerId. High-speed defaults to Y, archive to N.
POST storage.s3.region.update / storage.s3.region.delete
Update sends s3RegionId plus any of s3RegionName, s3RegionCode, s3RegionHighSpeed, s3RegionArchive.
Delete sends s3RegionId. A region that still has servers or non-deleted buckets cannot be deleted.
POST storage.s3.server.getall
Servers you can place a high-speed bucket on. Pass s3BucketCustomerId and s3RegionId to see the servers that customer may use in that region, including ancestor servers with inherit enabled. Optional excludeRegionId and highSpeedOnly.
Buckets
POST storage.s3.bucket.getall
{
"cmd": "storage.s3.bucket.getall",
"s3BucketName": "acme",
"s3BucketRegionId": 1,
"resStart": 0,
"resWindow": 50
}
| Parameter | Required | Description |
|---|---|---|
s3BucketName | No | Substring filter. String or array. |
stdname | No | Substring filter on the customer trading name. |
s3BucketCustomerId | No | Limit to one customer. |
s3BucketRegionId | No | Limit to one region. |
s3BucketServerId | No | Limit to one S3 server. |
Each bucket includes name, customer, region, server, storage type id (1 archive, 2 high speed), policy, versioning, Object Lock, status, operational status, and s3RegionEndpoint.
POST storage.s3.bucket.get
Requires s3BucketId. Also returns replicationTargets, pullSource, and pullCurrentRun.
POST storage.s3.bucket.checkavailability
{
"cmd": "storage.s3.bucket.checkavailability",
"s3BucketName": "acme-backups",
"s3BucketCustomerId": 456,
"s3BucketRegionId": 1,
"s3BucketStorageType": "HIGHSPEED"
}
Success message is Available. A taken or illegal name returns a fault. Optional s3BucketServerId checks uniqueness on that dedicated server. If you omit the server and exactly one dedicated server applies to the customer and region, the check uses that server.
POST storage.s3.bucket.create
{
"cmd": "storage.s3.bucket.create",
"s3BucketName": "acme-backups",
"s3BucketCustomerId": 456,
"s3BucketRegionCode": "au-nsw",
"s3BucketStorageType": "HIGHSPEED",
"s3BucketServerId": 12,
"s3BucketPolicy": "PUBLICREAD_DISABLED",
"s3BucketVersioningEnabled": true,
"s3BucketObjectLockEnabled": false
}
| Parameter | Required | Description |
|---|---|---|
s3BucketName | Yes | Bucket name. Stored lowercase. |
s3BucketCustomerId | No | Defaults to the caller. |
s3BucketRegionId | One of region id or code | Region id. |
s3BucketRegionCode | One of region id or code | Region code. Defaults to au-nsw when both are omitted. |
s3BucketStorageType | No | HIGHSPEED or ARCHIVE. The region must offer that class. Omitted means archive. |
s3BucketServerId | When several servers match | High-speed placement. Ignored for archive. If one server matches, it is selected for you. |
s3BucketPolicy | No | PUBLICREAD_DISABLED (default), PUBLICREAD_ENABLED, or CUSTOM. |
s3BucketPolicyCustom | With CUSTOM | Custom bucket policy document. |
s3BucketVersioningEnabled | No | true, 1, Y, YES, or ON. Can only be turned on at create. |
s3BucketObjectLockEnabled | No | High-speed only, create only. Forces versioning on. |
s3BucketObjectLockRetentionDays | No | Default GOVERNANCE retention, 1–36500 days. Omit or 0 to let clients set retention. Requires Object Lock. |
Returns s3BucketId. Name, customer, region, and Object Lock cannot be changed later. Versioning cannot be enabled later unless Object Lock was already on.
POST storage.s3.bucket.update
Requires s3BucketId. You can set s3BucketStatus to ACTIVE or INACTIVE, and change s3BucketPolicy / s3BucketPolicyCustom.
POST storage.s3.bucket.delete
{
"cmd": "storage.s3.bucket.delete",
"s3BucketId": 123
}
Marks the bucket DELETED. Remove zone-replication targets first.
Remove pull sources that read from this bucket first. A pull source that writes into this bucket is disabled as part of the delete.
Credentials
A credential is an access key. Bucket access is the buckets list: each entry is s3BucketId plus permission of READONLY or FULLACCESS.
NOACCESS removes that bucket. Every bucket you grant must live on the same S3 server.
The credential-level s3CredentialPermission is NOACCESS, READONLY, or FULLACCESS (default NOACCESS on create).
The secret is shown once. Call storage.s3.credential.get with getSecret: true while s3CredentialSecretExists is true.
A later get returns an empty secret and clears it from the response. To rotate, update with s3CredentialResetSecret: true (also accepts yes), then get the new secret once.
List calls never return the secret. They return s3CredentialSecretExists when an unviewed secret is waiting.
POST storage.s3.credential.create
{
"cmd": "storage.s3.credential.create",
"s3CredentialName": "backup-writer",
"s3CredentialCustomerId": 456,
"s3CredentialPermission": "NOACCESS",
"s3CredentialStorageType": "HIGHSPEED",
"buckets": [
{ "s3BucketId": 123, "permission": "FULLACCESS" }
]
}
| Parameter | Required | Description |
|---|---|---|
s3CredentialName | Yes | Unique among your active and inactive credentials. |
s3CredentialCustomerId | No | Defaults to the caller. |
s3CredentialPermission | No | NOACCESS, READONLY, or FULLACCESS. |
s3CredentialStorageType | No | HIGHSPEED or ARCHIVE. If omitted, taken from the first high-speed bucket in buckets, otherwise archive. |
s3CredentialExpires | No | Unix timestamp. Omit for no expiry. |
buckets | No | Array of { s3BucketId, permission }. |
Returns s3CredentialId. Fetch the secret immediately with getSecret.
POST storage.s3.credential.getall
Optional filters: s3CredentialName, s3CredentialAccessKey, s3CredentialNameAccessKey (name or access key), stdname, resStart, resWindow. Response key is credentials, plus matches. Each row includes s3CredentialUsesBucketPolicy and s3CredentialBucketPolicyCount.
POST storage.s3.credential.get
{
"cmd": "storage.s3.credential.get",
"s3CredentialId": 88,
"getSecret": true
}
Requires s3CredentialId. Returns the credential, its buckets (id, name, region, server, endpoint, permission), and the secret only when getSecret is set and the secret has not been viewed.
POST storage.s3.credential.update
Requires s3CredentialId (or s3CredentialAccessKey to look it up).
Optional: s3CredentialName, s3CredentialCustomerId, s3CredentialStatus (ACTIVE or INACTIVE), s3CredentialPermission, s3CredentialExpires, s3CredentialResetSecret, and a replacement buckets array.
Sending buckets replaces the assignment set. An empty expiry clears the expiry.
POST storage.s3.credential.delete
{
"cmd": "storage.s3.credential.delete",
"s3CredentialId": 88
}
Zone replication
Replication copies a high-speed bucket to other regions or to an external S3 endpoint.
It is not available on archive buckets or Object Lock buckets.
A bucket can have at most 5 targets. An internal target must be a different region, and the target bucket name matches the source.
storage.s3.bucket.get includes replicationTargets. Secrets on external targets are not returned; s3BucketReplicationTargetSecretExists is set instead.
POST storage.s3.bucket.replication.getall
Requires s3BucketId. Returns replicationTargets and matches.
POST storage.s3.bucket.replication.create
{
"cmd": "storage.s3.bucket.replication.create",
"s3BucketId": 123,
"s3BucketReplicationTargetType": "INTERNAL",
"s3BucketReplicationTargetServerId": 40,
"s3BucketReplicationPriority": 1
}
External target:
{
"cmd": "storage.s3.bucket.replication.create",
"s3BucketId": 123,
"s3BucketReplicationTargetType": "EXTERNAL",
"s3BucketReplicationTargetEndpoint": "https://s3.example.com",
"s3BucketReplicationTargetBucketName": "acme-backups-copy",
"s3BucketReplicationTargetAccessKey": "AKIA...",
"s3BucketReplicationTargetSecretKey": "secret"
}
s3BucketReplicationTargetType is INTERNAL or EXTERNAL. Priority defaults to the next integer. Endpoints without a scheme are treated as https://. Returns replicationTarget.
POST storage.s3.bucket.replication.update
Requires s3BucketReplicationId.
Optional s3BucketReplicationStatus is ACTIVE or DISABLED.
External targets can rotate s3BucketReplicationTargetAccessKey and s3BucketReplicationTargetSecretKey.
s3BucketReplicationResyncRequested: true (or Y or 1) asks for a resync.
POST storage.s3.bucket.replication.delete
Requires s3BucketReplicationId. The target is removed and the source bucket returns to PENDING until the change is applied.
Pull import
A pull source copies objects into a high-speed destination bucket from another RackCorp bucket (INTERNAL) or an external S3 endpoint (EXTERNAL).
One source per destination bucket. The external secret is not returned on read.
storage.s3.bucket.get includes pullSource and pullCurrentRun.
POST storage.s3.bucket.pull.get
Requires s3BucketId (the destination). Returns pullSource and currentRun. pullSource is null when none is configured.
POST storage.s3.bucket.pull.create
{
"cmd": "storage.s3.bucket.pull.create",
"s3BucketId": 123,
"s3BucketPullSourceType": "EXTERNAL",
"s3BucketPullSourceEndpoint": "https://s3.amazonaws.com",
"s3BucketPullSourceBucketName": "source-bucket",
"s3BucketPullSourceAccessKey": "AKIA...",
"s3BucketPullSourceSecretKey": "secret",
"s3BucketPullSourceScheduleType": "DAILY",
"s3BucketPullSourceTimeOfDay": "02:30",
"s3BucketPullSourceTimezone": "Australia/Sydney",
"s3BucketPullSourceMaxRuntimeHours": 72
}
| Parameter | Required | Description |
|---|---|---|
s3BucketId | Yes | Destination high-speed bucket. |
s3BucketPullSourceType | Yes | INTERNAL or EXTERNAL. |
s3BucketPullSourceSourceBucketId | Internal | Source bucket you can access. Cannot be the destination. |
s3BucketPullSourceEndpoint | External | S3 endpoint. https:// is added if omitted. |
s3BucketPullSourceBucketName | External | Source bucket name. Same naming rules as RackCorp buckets. |
s3BucketPullSourceAccessKey | External | Source access key. |
s3BucketPullSourceSecretKey | External | Source secret. |
s3BucketPullSourceScheduleType | No | ONCE (default), INTERVAL, DAILY, WEEKLY, or MONTHLY. |
s3BucketPullSourceIntervalMinutes | Interval | 5–44640. |
s3BucketPullSourceTimeOfDay | Daily, weekly, monthly | HH:MM. |
s3BucketPullSourceWeekday | Weekly | 1 (Monday) through 7 (Sunday). |
s3BucketPullSourceMonthDay | Monthly | 1–31. |
s3BucketPullSourceTimezone | No | IANA timezone. Default UTC. |
s3BucketPullSourceMaxRuntimeHours | No | 1–168. Default 72. |
POST storage.s3.bucket.pull.update
Identify the source with s3BucketPullSourceId or destination s3BucketId.
s3BucketPullSourceStatus is ACTIVE or DISABLED.
Sending any schedule field revalidates the schedule.
External connection fields can be replaced: endpoint, bucket name, access key, secret.
POST storage.s3.bucket.pull.delete
s3BucketPullSourceId or destination s3BucketId.
POST storage.s3.bucket.pull.run
Requires destination s3BucketId and an active source. Queues a run and returns s3BucketPullRunId. If a run is already active, the response has skipped: true and skipReason: "already running".
POST storage.s3.bucket.pull.cancel
s3BucketPullRunId or destination s3BucketId for the current run. Pending runs become CANCELLED immediately. A running import is asked to stop.
POST storage.s3.bucket.pull.runs
Requires destination s3BucketId. Optional limit is 1–100 (default 25). Returns runs, pullSource, and currentRun.
Dedicated servers
A dedicated server is an S3 virtual machine in one of your VPCs, registered as an S3 server in a high-speed region.
Buckets for that customer (and, when inherit is Y, child customers) can be placed on it.
Public exposure requires a DNS hostname and is published as https:// plus that hostname. Private exposure has no public hostname. The hostname cannot be changed after create.
Status moves through PROVISIONING, REGISTERING, and ACTIVE. FAILED and INACTIVE (decommissioned) are terminal for placement.
POST storage.s3.dedicated.create
{
"cmd": "storage.s3.dedicated.create",
"name": "acme-s3-syd",
"description": "Sydney dedicated S3",
"customerId": 456,
"vpcId": 90,
"s3RegionId": 1,
"exposure": "public",
"dnsHostname": "s3.example.org",
"inherit": "N"
}
| Parameter | Required | Description |
|---|---|---|
name | Yes | Also accepted as s3ServerName. Unique among provisioning, registering, and active servers. |
vpcId | Yes | A running VPC owned by customerId. Also s3ServerVpcId. |
s3RegionId | Yes, unless derived from the VPC | Must be a high-speed region. Also regionId. |
customerId | No | Defaults to the caller. Also s3ServerCustomerId. |
exposure | No | public (default) or private. Also publicEndpoint or s3ServerAccess. |
dnsHostname | Public | Hostname such as s3.example.org. Also hostname. |
inherit | No | Y lets child customers place buckets here. Default N. Also s3ServerInherit. |
description | No | Also s3ServerDescription. |
Returns s3ServerId, applicationId, contractId, and server. Provisioning starts immediately.
POST storage.s3.dedicated.getall / storage.s3.dedicated.get
List returns dedicated servers. Optional s3RegionId and status (string or array; default is provisioning, registering, active, inactive, and failed).
Get requires s3ServerId (or id) and returns server.
POST storage.s3.dedicated.update
Requires s3ServerId. You can change name, description, inherit, and customerId. Sending a hostname or endpoint is rejected.
POST storage.s3.dedicated.redeploy
Requires s3ServerId. Reinstalls the VM operating system and keeps the data disk. The server returns to REGISTERING. Not available once the server is decommissioned, or before the VM exists.
POST storage.s3.dedicated.delete
{
"cmd": "storage.s3.dedicated.delete",
"s3ServerId": 15
}
Decommissions the server (INACTIVE), stops the application, and cancels the VM. This does not delete buckets by itself.
Command index
| Command | Purpose |
|---|---|
storage.s3.region.getall | List regions |
storage.s3.region.get | Get one region |
storage.s3.region.create | Create a region |
storage.s3.region.update | Update a region |
storage.s3.region.delete | Delete an unused region |
storage.s3.server.getall | List servers available for bucket placement |
storage.s3.bucket.getall | List buckets |
storage.s3.bucket.get | Get a bucket, including replication and pull |
storage.s3.bucket.checkavailability | Check a bucket name |
storage.s3.bucket.create | Create a bucket |
storage.s3.bucket.update | Update status or policy |
storage.s3.bucket.delete | Delete a bucket |
storage.s3.credential.getall | List credentials |
storage.s3.credential.get | Get a credential; optionally reveal the secret once |
storage.s3.credential.create | Create a credential |
storage.s3.credential.update | Update a credential, bucket grants, or rotate the secret |
storage.s3.credential.delete | Delete a credential |
storage.s3.bucket.replication.getall | List replication targets |
storage.s3.bucket.replication.create | Add a replication target |
storage.s3.bucket.replication.update | Enable, disable, rotate keys, or resync |
storage.s3.bucket.replication.delete | Remove a replication target |
storage.s3.bucket.pull.get | Get the pull source on a destination bucket |
storage.s3.bucket.pull.create | Create a pull source |
storage.s3.bucket.pull.update | Update schedule, status, or external connection |
storage.s3.bucket.pull.delete | Remove a pull source |
storage.s3.bucket.pull.run | Queue an import now |
storage.s3.bucket.pull.cancel | Cancel the current import |
storage.s3.bucket.pull.runs | List recent import runs |
storage.s3.dedicated.getall | List your dedicated servers |
storage.s3.dedicated.get | Get one dedicated server |
storage.s3.dedicated.create | Provision a dedicated server |
storage.s3.dedicated.update | Rename, reassign, or change inherit |
storage.s3.dedicated.redeploy | Reinstall the OS, keep the data disk |
storage.s3.dedicated.delete | Decommission a dedicated server |
Errors
{
"code": "FAULT",
"message": "s3BucketName: Not available"
}
Some calls return error as an object of field messages. A missing required id usually comes back as s3BucketId: Required or s3CredentialId: Required.