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 from https://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
}
ParameterRequiredDescription
s3RegionNameNoSubstring filter on the region name. A string or an array of strings.
highSpeedOnlyNoOnly regions with high-speed storage.
activeServerOnlyNoOnly regions that have an active S3 server.
resStart, resWindowNoPagination.

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
}
ParameterRequiredDescription
s3BucketNameNoSubstring filter. String or array.
stdnameNoSubstring filter on the customer trading name.
s3BucketCustomerIdNoLimit to one customer.
s3BucketRegionIdNoLimit to one region.
s3BucketServerIdNoLimit 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
}
ParameterRequiredDescription
s3BucketNameYesBucket name. Stored lowercase.
s3BucketCustomerIdNoDefaults to the caller.
s3BucketRegionIdOne of region id or codeRegion id.
s3BucketRegionCodeOne of region id or codeRegion code. Defaults to au-nsw when both are omitted.
s3BucketStorageTypeNoHIGHSPEED or ARCHIVE. The region must offer that class. Omitted means archive.
s3BucketServerIdWhen several servers matchHigh-speed placement. Ignored for archive. If one server matches, it is selected for you.
s3BucketPolicyNoPUBLICREAD_DISABLED (default), PUBLICREAD_ENABLED, or CUSTOM.
s3BucketPolicyCustomWith CUSTOMCustom bucket policy document.
s3BucketVersioningEnabledNotrue, 1, Y, YES, or ON. Can only be turned on at create.
s3BucketObjectLockEnabledNoHigh-speed only, create only. Forces versioning on.
s3BucketObjectLockRetentionDaysNoDefault 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" }
  ]
}
ParameterRequiredDescription
s3CredentialNameYesUnique among your active and inactive credentials.
s3CredentialCustomerIdNoDefaults to the caller.
s3CredentialPermissionNoNOACCESS, READONLY, or FULLACCESS.
s3CredentialStorageTypeNoHIGHSPEED or ARCHIVE. If omitted, taken from the first high-speed bucket in buckets, otherwise archive.
s3CredentialExpiresNoUnix timestamp. Omit for no expiry.
bucketsNoArray 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
}
ParameterRequiredDescription
s3BucketIdYesDestination high-speed bucket.
s3BucketPullSourceTypeYesINTERNAL or EXTERNAL.
s3BucketPullSourceSourceBucketIdInternalSource bucket you can access. Cannot be the destination.
s3BucketPullSourceEndpointExternalS3 endpoint. https:// is added if omitted.
s3BucketPullSourceBucketNameExternalSource bucket name. Same naming rules as RackCorp buckets.
s3BucketPullSourceAccessKeyExternalSource access key.
s3BucketPullSourceSecretKeyExternalSource secret.
s3BucketPullSourceScheduleTypeNoONCE (default), INTERVAL, DAILY, WEEKLY, or MONTHLY.
s3BucketPullSourceIntervalMinutesInterval5–44640.
s3BucketPullSourceTimeOfDayDaily, weekly, monthlyHH:MM.
s3BucketPullSourceWeekdayWeekly1 (Monday) through 7 (Sunday).
s3BucketPullSourceMonthDayMonthly1–31.
s3BucketPullSourceTimezoneNoIANA timezone. Default UTC.
s3BucketPullSourceMaxRuntimeHoursNo1–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"
}
ParameterRequiredDescription
nameYesAlso accepted as s3ServerName. Unique among provisioning, registering, and active servers.
vpcIdYesA running VPC owned by customerId. Also s3ServerVpcId.
s3RegionIdYes, unless derived from the VPCMust be a high-speed region. Also regionId.
customerIdNoDefaults to the caller. Also s3ServerCustomerId.
exposureNopublic (default) or private. Also publicEndpoint or s3ServerAccess.
dnsHostnamePublicHostname such as s3.example.org. Also hostname.
inheritNoY lets child customers place buckets here. Default N. Also s3ServerInherit.
descriptionNoAlso 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

CommandPurpose
storage.s3.region.getallList regions
storage.s3.region.getGet one region
storage.s3.region.createCreate a region
storage.s3.region.updateUpdate a region
storage.s3.region.deleteDelete an unused region
storage.s3.server.getallList servers available for bucket placement
storage.s3.bucket.getallList buckets
storage.s3.bucket.getGet a bucket, including replication and pull
storage.s3.bucket.checkavailabilityCheck a bucket name
storage.s3.bucket.createCreate a bucket
storage.s3.bucket.updateUpdate status or policy
storage.s3.bucket.deleteDelete a bucket
storage.s3.credential.getallList credentials
storage.s3.credential.getGet a credential; optionally reveal the secret once
storage.s3.credential.createCreate a credential
storage.s3.credential.updateUpdate a credential, bucket grants, or rotate the secret
storage.s3.credential.deleteDelete a credential
storage.s3.bucket.replication.getallList replication targets
storage.s3.bucket.replication.createAdd a replication target
storage.s3.bucket.replication.updateEnable, disable, rotate keys, or resync
storage.s3.bucket.replication.deleteRemove a replication target
storage.s3.bucket.pull.getGet the pull source on a destination bucket
storage.s3.bucket.pull.createCreate a pull source
storage.s3.bucket.pull.updateUpdate schedule, status, or external connection
storage.s3.bucket.pull.deleteRemove a pull source
storage.s3.bucket.pull.runQueue an import now
storage.s3.bucket.pull.cancelCancel the current import
storage.s3.bucket.pull.runsList recent import runs
storage.s3.dedicated.getallList your dedicated servers
storage.s3.dedicated.getGet one dedicated server
storage.s3.dedicated.createProvision a dedicated server
storage.s3.dedicated.updateRename, reassign, or change inherit
storage.s3.dedicated.redeployReinstall the OS, keep the data disk
storage.s3.dedicated.deleteDecommission 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.