API docs by Redocly

Nexo Admin API (1)

Download OpenAPI specification:

Administration API of the Nexo object storage server, served on the console listener under /api/v1. JSON in, JSON out; failures are RFC 9457 application/problem+json documents with a stable snake_case code (unauthenticated, access_denied, invalid_csrf_token, invalid_argument, bucket_not_found, object_not_found, user_not_found, policy_not_found, conflict, malformed_policy, invalid_configuration, object_locked, entity_too_large, not_implemented...).

Authentication, one of:

  • the console session: the nexo_session cookie (HttpOnly, SameSite=Strict, issued by POST /auth/login). A state-changing request must also carry the X-CSRF-Token header with the csrfToken of the session (returned by login and GET /auth/session, never set in a cookie) and come from the console origin: Sec-Fetch-Site: same-origin or, from a browser that does not send it, an Origin (else Referer) of the console; otherwise 403 invalid_csrf_token. The ports of a host are same-site, so the pages of the S3 listener receive the session cookie too: the origin check refuses them;
  • AWS Signature Version 4 in the Authorization header (CLI, SDKs), with the service s3 and the region of the server in the credential scope. Presigned URLs are not accepted.

Authorization: every operation lists in x-nexo-actions the admin:* and s3:* policy actions it requires, evaluated by the policy engine (docs/04 §4.4). Operations marked x-nexo-authorized-by: service are authorized by the service object by object (resources in the body) or with the self-service rule (a user always manages its own access keys and share links).

Lists answer {items, nextCursor} and accept cursor (opaque) and limit (1-1000, default 1000).

Rate limits: every operation may answer 429 too_many_requests with a Retry-After header (seconds) when a rate limit of the node refuses the request (ratelimit.admin_ip per client address, ratelimit.admin_user per authenticated user; dynamic configuration, off by default).

This document is the source of the TypeScript types of the web console (web/src/services/http/schema.d.ts, generated with npm run gen:api); the Go transport (internal/transport/http/admin) is the reference implementation and pkg/nexoadmin its Go client.

session

Open a console session

Public endpoint. Sets the nexo_session cookie (HttpOnly); the CSRF token is in the body (csrfToken), never in a cookie. After 5 failed attempts of a client on an access key (or 20 of a client on any key) within 5 minutes, the attempts are refused for a minute (429 too_many_requests with Retry-After), even with the right secret; the client is the peer of the connection or, behind the --trusted-proxies, the address they forward. Against login CSRF the body must be application/json (415 unsupported_media_type) and a browser request must not be cross-site (Sec-Fetch-Site cross-site or same-site: 403 cross_site_request).

Request Body schema: application/json
required
accessKey
required
string
secretKey
required
string

Responses

Request samples

Content type
application/json
{
  • "accessKey": "string",
  • "secretKey": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "accessKey": "string",
  • "identity": {
    },
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "csrfToken": "string"
}

Revoke the current session and clear the cookies

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Return the current console session

Signed (SigV4) requests have no session and receive 401.

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "accessKey": "string",
  • "identity": {
    },
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "csrfToken": "string"
}

Effective permissions of the caller (or of a user)

Evaluates the catalog of console actions (admin:* and s3:*) with the policy engine, globally or on bucket (object actions on prefix*). Naming another user requires admin:GetUser.

Authorizations:
(sessioncsrf) sigv4
query Parameters
bucket
string
prefix
string
user
string

Responses

Response samples

Content type
application/json
{
  • "user": "string",
  • "isRoot": true,
  • "bucket": "string",
  • "prefix": "string",
  • "allowed": [
    ],
  • "denied": [
    ]
}

server

Server and cluster information

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "commit": "string",
  • "buildDate": "string",
  • "mode": "snsd",
  • "region": "string",
  • "deploymentId": "string",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "uptimeSeconds": 0,
  • "buckets": 0,
  • "objects": 0,
  • "usage": 0,
  • "pools": [
    ],
  • "nodes": [
    ],
  • "kms": {
    },
  • "tls": {
    },
  • "telemetry": {
    }
}

Data usage, total and per bucket

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "lastUpdate": "2019-08-24T14:15:22Z",
  • "objectsCount": 0,
  • "versionsCount": 0,
  • "totalSize": 0,
  • "bucketsCount": 0,
  • "buckets": {
    }
}

Start a healing job

Starts a background healing job and answers at once with its initial state; poll GET /heal/{id} for the progress. Without bucket the job heals the format of the drives (new or wiped drives) and every bucket; with bucket that bucket; with recursive every object below the bucket(s) or prefix too (without recursive, prefix names the one object to heal). deep verifies the bitrot hash of every shard block, dryRun only reports, remove deletes the dangling objects found (versions on too few drives to ever be read; never implied). An identical job already running is returned instead of a new one; too many running jobs answer 429. A single-drive deployment has nothing to heal: 501.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
bucket
string
prefix
string
recursive
boolean
dryRun
boolean
deep
boolean

Verify the bitrot hash of every shard block.

remove
boolean

Delete the dangling objects found.

Responses

Request samples

Content type
application/json
{
  • "bucket": "string",
  • "prefix": "string",
  • "recursive": true,
  • "dryRun": true,
  • "deep": true,
  • "remove": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "state": "running",
  • "request": {
    },
  • "finished": true,
  • "node": "string",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "current": "string",
  • "scanned": 0,
  • "healed": 0,
  • "failed": 0,
  • "dangling": 0,
  • "removed": 0,
  • "bytes": 0,
  • "drives": [
    ],
  • "items": [
    ],
  • "itemsTruncated": true,
  • "error": "string"
}

List the running and recently finished healing jobs

Newest first; a finished job stays listed for an hour.

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Query a healing job

Any node answers, the progress of a job being persisted on the drives.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "state": "running",
  • "request": {
    },
  • "finished": true,
  • "node": "string",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "finishedAt": "2019-08-24T14:15:22Z",
  • "current": "string",
  • "scanned": 0,
  • "healed": 0,
  • "failed": 0,
  • "dangling": 0,
  • "removed": 0,
  • "bytes": 0,
  • "drives": [
    ],
  • "items": [
    ],
  • "itemsTruncated": true,
  • "error": "string"
}

Restart the server

The response is sent before the process restarts (in place, within the process; SIGHUP only reloads the TLS certificates).

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "action": "restart"
}

Stop the server

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "action": "restart"
}

buckets

List the buckets visible to the caller, with usage and public flag

Every bucket with s3:ListAllMyBuckets, otherwise those the caller may list (s3:ListBucket).

Authorizations:
(sessioncsrf) sigv4
query Parameters
prefix
string
cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create a bucket with its initial settings

Versioning, object lock and quota need their own actions on top of s3:CreateBucket.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
name
required
string
region
string
versioning
boolean

Enable versioning (implied by objectLock).

objectLock
boolean
quotaBytes
integer <int64>

Hard quota in bytes (0 none).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "region": "string",
  • "versioning": true,
  • "objectLock": true,
  • "quotaBytes": 0
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "region": "string",
  • "versioning": "off",
  • "objectLockEnabled": true,
  • "objects": 0,
  • "versions": 0,
  • "deleteMarkers": 0,
  • "size": 0,
  • "quotaBytes": 0,
  • "public": true,
  • "tags": {
    },
  • "partial": true
}

Get a bucket with its usage

A caller that may list only a part of the bucket (s3:ListBucket under an s3:prefix condition, a home directory) gets its name, creation date and region only (partial).

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "region": "string",
  • "versioning": "off",
  • "objectLockEnabled": true,
  • "objects": 0,
  • "versions": 0,
  • "deleteMarkers": 0,
  • "size": 0,
  • "quotaBytes": 0,
  • "public": true,
  • "tags": {
    },
  • "partial": true
}

Delete a bucket

With force=true (and s3:ForceDeleteBucket) the bucket is emptied first through the object layer: every version, delete marker and pending upload; object lock is honored, a protected version keeps the bucket (409 bucket_not_empty).

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
force
boolean

Empty the bucket before deleting it.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

getBucketVersioning

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "off"
}

setBucketVersioning

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
status
required
string (VersioningState)
Enum: "off" "enabled" "suspended"

Responses

Request samples

Content type
application/json
{
  • "status": "off"
}

Response samples

Content type
application/json
{
  • "status": "off"
}

getBucketPolicy

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "Id": "string",
  • "Version": "string",
  • "Statement": [
    ]
}

setBucketPolicy

The body is the policy document; errors are malformed_policy problems located by line and column.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
Id
string
Version
required
string
required
Array of objects (PolicyStatement)

Responses

Request samples

Content type
application/json
{
  • "Id": "string",
  • "Version": "string",
  • "Statement": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

deleteBucketPolicy

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

getBucketQuota

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "string",
  • "size": 0
}

setBucketQuota

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
type
required
string

Enforcement type ("hard"); empty when no quota is set.

size
required
integer <int64>

Limit in bytes; 0 disables the quota.

Responses

Request samples

Content type
application/json
{
  • "type": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "size": 0
}

getBucketTags

The tags; a bucket without tags answers an empty set.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "tags": {
    }
}

setBucketTags

Replaces the tags; an empty set removes them.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "tags": {
    }
}

getBucketObjectLock

The object lock configuration; a bucket without object lock answers {"enabled":false}.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "mode": "GOVERNANCE",
  • "days": 0,
  • "years": 0
}

setBucketObjectLock

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
enabled
required
boolean
mode
string
Enum: "GOVERNANCE" "COMPLIANCE"
days
integer
years
integer

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "mode": "GOVERNANCE",
  • "days": 0,
  • "years": 0
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "mode": "GOVERNANCE",
  • "days": 0,
  • "years": 0
}

getBucketEncryption

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "algorithm": "string",
  • "kmsKeyId": "string"
}

setBucketEncryption

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
algorithm
required
string

"AES256" (SSE-S3) or "aws:kms" (SSE-KMS).

kmsKeyId
string

Responses

Request samples

Content type
application/json
{
  • "algorithm": "string",
  • "kmsKeyId": "string"
}

Response samples

Content type
application/json
{
  • "algorithm": "string",
  • "kmsKeyId": "string"
}

deleteBucketEncryption

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Anonymous access rules (presets per prefix) of the bucket policy

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "rules": [
    ],
  • "public": true,
  • "hasPolicy": true
}

Apply an anonymous access preset to a prefix

private removes the rule of the prefix; the other statements of the bucket policy are kept.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
prefix
string
preset
required
string
Enum: "private" "download" "upload" "public"

Responses

Request samples

Content type
application/json
{
  • "prefix": "string",
  • "preset": "private"
}

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "rules": [
    ],
  • "public": true,
  • "hasPolicy": true
}

Remove the anonymous access of a prefix (private)

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
prefix
string

The prefix; the whole bucket when absent.

Responses

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "rules": [
    ],
  • "public": true,
  • "hasPolicy": true
}

Lifecycle rules of the bucket

The rules of the S3 LifecycleConfiguration of the bucket in structured form (what the S3 API stores and reads). A bucket without configuration answers no rule.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ]
}

Replace the lifecycle rules of the bucket

Every rule is validated on its own with the rules of the S3 API: a rejected configuration answers 400 invalid_configuration with every invalid rule in ruleErrors (index, id, S3 code, message) and nothing is stored. Rules without id get one. No rule removes the configuration. Transitions need a remote tier (P2): without one they are refused (code NotImplemented).

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
required
Array of objects (LifecycleRule) <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "rules": [
    ]
}

Remove the lifecycle configuration

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Apply the lifecycle rules now

Applies the rules to every version and incomplete upload of the bucket at once, as the scanner does over its cycle: the expired versions are removed (those Object Lock protects only get a delete marker, counted in locked). A bucket without configuration is left as is.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "buckets": 0,
  • "versions": 0,
  • "deleted": 0,
  • "deleteMarkers": 0,
  • "uploadsAborted": 0,
  • "locked": 0
}

Event subscriptions of the bucket

The S3 NotificationConfiguration of the bucket in structured form; a bucket without configuration answers no subscription.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "subscriptions": [
    ]
}

Replace the event subscriptions of the bucket

Every subscription is validated on its own (known events, prefix/suffix filters, an ARN naming a configured target, see GET /notify/targets): a rejected configuration answers 400 invalid_configuration with every invalid subscription in ruleErrors. Subscriptions without id get one. No subscription removes them all.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
required
Array of objects (EventSubscription)

Responses

Request samples

Content type
application/json
{
  • "subscriptions": [
    ]
}

Response samples

Content type
application/json
{
  • "subscriptions": [
    ]
}

Remove every event subscription of the bucket

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

CORS rules of the bucket

The rules of the S3 CORSConfiguration, evaluated in order; a bucket without configuration answers no rule.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "rules": [
    ]
}

Replace the CORS rules of the bucket

1 to 100 rules, each validated on its own: a rejected configuration answers 400 invalid_configuration with every invalid rule in ruleErrors. No rule removes the configuration.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
required
Array of objects (CorsRule) <= 100 items

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "rules": [
    ]
}

Remove the CORS configuration

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Replication configuration (not implemented yet)

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Replication configuration (not implemented yet)

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

objects

Folder view of a bucket

Objects and common prefixes ("folders") directly under prefix, without the folder placeholder object prefix itself. delimiter defaults to "/"; an empty delimiter lists recursively. The object browser authorizes s3:ListBucket with the conditions s3:prefix, s3:delimiter (the effective one) and s3:max-keys.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
prefix
string
delimiter
string

Default "/"; empty lists recursively.

cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "objects": [
    ],
  • "prefixes": [
    ],
  • "isTruncated": true,
  • "nextCursor": "string"
}

Delete objects, versions and prefixes (recursive)

Synchronous; every object is authorized and reported (s3:DeleteObject, s3:DeleteObjectVersion with a version). Every prefix needs s3:ListBucket (s3:ListBucketVersions with allVersions) with the s3:prefix condition: otherwise the whole request is denied before deleting anything. Object Lock is honored: a version under retention or legal hold fails with object_locked; with bypassGovernance the versions under a GOVERNANCE retention are deleted where the caller has s3:BypassGovernanceRetention (on the version, with the condition values of the S3 x-amz-bypass-governance-retention header).

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
Array of objects (ObjectRef)
prefixes
Array of strings

Folders deleted recursively ("" is the whole bucket). A prefix without a trailing slash names the folder of that name, as in the CLI: "photos" is "photos/", never "photos2/" nor "photosx.txt".

allVersions
boolean

Delete every version under the prefixes permanently.

bypassGovernance
boolean

Delete the versions a GOVERNANCE retention protects, where the caller has s3:BypassGovernanceRetention.

Responses

Request samples

Content type
application/json
{
  • "objects": [
    ],
  • "prefixes": [
    ],
  • "allVersions": true,
  • "bypassGovernance": true
}

Response samples

Content type
application/json
{
  • "deleted": [
    ],
  • "errors": [
    ]
}

Metadata, tags and first versions of an object

Tags and versions are included only when the caller may read them.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "versionId": "string",
  • "size": 0,
  • "etag": "string",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "contentType": "string",
  • "isDeleteMarker": true,
  • "isLatest": true,
  • "storageClass": "string",
  • "contentEncoding": "string",
  • "contentDisposition": "string",
  • "contentLanguage": "string",
  • "cacheControl": "string",
  • "expires": "2019-08-24T14:15:22Z",
  • "userMetadata": {
    },
  • "parts": 0,
  • "checksumAlgorithm": "string",
  • "checksum": "string",
  • "encryption": {
    },
  • "tags": {
    },
  • "versions": [
    ],
  • "versionsTruncated": true
}

Versions and delete markers of one key, newest first

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create a folder (the empty object "prefix/")

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
prefix
required
string

The folder key; a trailing "/" is added when missing.

Responses

Request samples

Content type
application/json
{
  • "prefix": "string"
}

Response samples

Content type
application/json
{
  • "key": "string",
  • "versionId": "string",
  • "size": 0,
  • "etag": "string",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "contentType": "string",
  • "isDeleteMarker": true,
  • "isLatest": true,
  • "storageClass": "string"
}

Make a previous version the latest again (copy of the version onto its key)

Copies the version onto its own key with its content, metadata and tags: a new latest version is created and the history is kept. Authorized like the S3 CopyObject it stands for: s3:GetObjectVersion on the version (s3:versionid condition) and s3:PutObject on the key. A delete marker cannot be restored (405).

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string
versionId
required
string

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "versionId": "string",
  • "size": 0,
  • "etag": "string",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "contentType": "string",
  • "isDeleteMarker": true,
  • "isLatest": true,
  • "storageClass": "string"
}

Move an object, or every object under a prefix (copy then delete)

Moving a prefix needs s3:ListBucket on the source prefix (s3:prefix condition): otherwise the whole request is denied before moving anything.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
source
required
string
destination
required
string
prefix
boolean

Move every object of the folder source to the folder destination (which may not lie under it). Both name folders: a missing trailing slash is added ("photos" is "photos/", never "photos2/").

overwrite
boolean

Replace existing destination objects (otherwise conflict).

Responses

Request samples

Content type
application/json
{
  • "source": "string",
  • "destination": "string",
  • "prefix": true,
  • "overwrite": true
}

Response samples

Content type
application/json
{
  • "renamed": [
    ],
  • "errors": [
    ]
}

Replace the tags of an object (version); an empty set removes them

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
{
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "tags": {
    }
}

Download an object (Content-Disposition attachment, Range supported)

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

header Parameters
Range
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Preview an object

Inline only for types that cannot run scripts in the console origin (raster images, PDF, text/plain, JSON, audio, video), with a sandboxing Content-Security-Policy; everything else (SVG, HTML, XML...) is served as an application/octet-stream attachment.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

header Parameters
Range
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

HLS master playlist of a video

The HLS presentation of an MP4 video (H.264 or H.265, optional AAC audio), packaged on the fly without transcoding: the playlists and segments reference each other with relative URIs pinned to the ETag of the object. Fragmented MP4 and SSE-C objects are refused.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

HLS media playlist of a video

The segments of the presentation (VOD).

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

rev
required
string

The ETag the presentation is pinned to (412 once the object changed).

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

HLS init segment of a video

The fMP4 initialization segment.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

rev
required
string

The ETag the presentation is pinned to (412 once the object changed).

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

HLS media segment of a video

One fMP4 media segment, numbered from 0.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

rev
required
string

The ETag the presentation is pinned to (412 once the object changed).

n
required
integer >= 0

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Zip archive of objects and prefixes, streamed

Names are relative to base. Explicit keys are checked before streaming; every prefix needs s3:ListBucket (s3:prefix condition), otherwise the request is denied before streaming. Objects of the prefixes the caller may not read are listed in nexo-zip-errors.txt. The console submits the request as a form (application/x-www-form-urlencoded: the JSON ZipRequest in the field request, the CSRF token in the field csrfToken) so that the browser streams the archive to disk instead of holding it in memory. This is the only operation that reads the CSRF token from a form field; the request must still come from the console origin.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema:
required
keys
Array of strings
prefixes
Array of strings

Folders archived recursively. A prefix without a trailing slash names the folder of that name ("photos" is "photos/", never "photos2/").

base
string

Folder the archive names are relative to ("photos" is "photos/").

Responses

Request samples

Content type
{
  • "keys": [
    ],
  • "prefixes": [
    ],
  • "base": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Object Lock retention of a version

A version without retention answers no mode. A bucket without Object Lock answers 400.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

Responses

Response samples

Content type
application/json
{
  • "versionId": "string",
  • "mode": "GOVERNANCE",
  • "retainUntil": "2019-08-24T14:15:22Z"
}

Set or remove the retention of a version

A mode with a future retain-until date, or neither to remove the retention. A retention can always be extended; a GOVERNANCE one is shortened or removed only with bypassGovernance (s3:BypassGovernanceRetention, asked explicitly: 403 when denied), a COMPLIANCE one never, not even by root (403 object_locked). Authorized as the S3 PutObjectRetention (s3:versionid, x-amz-bypass-governance-retention).

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

Request Body schema: application/json
required
mode
string

GOVERNANCE or COMPLIANCE (case-insensitive); empty with no date removes the retention.

retainUntil
string <date-time>
bypassGovernance
boolean

Shorten or remove a GOVERNANCE retention (s3:BypassGovernanceRetention).

Responses

Request samples

Content type
application/json
{
  • "mode": "string",
  • "retainUntil": "2019-08-24T14:15:22Z",
  • "bypassGovernance": true
}

Response samples

Content type
application/json
{
  • "versionId": "string",
  • "mode": "GOVERNANCE",
  • "retainUntil": "2019-08-24T14:15:22Z"
}

Legal hold of a version

A version whose legal hold was never set answers OFF.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

Responses

Response samples

Content type
application/json
{
  • "versionId": "string",
  • "status": "string"
}

Set the legal hold of a version

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

Request Body schema: application/json
required
versionId
string
status
required
string

ON or OFF (case-insensitive in requests).

Responses

Request samples

Content type
application/json
{
  • "versionId": "string",
  • "status": "string"
}

Response samples

Content type
application/json
{
  • "versionId": "string",
  • "status": "string"
}

Checksum and parts of a version

Describes a version without reading it (S3 GetObjectAttributes): its checksum and, for a multipart object, a page of its parts with their sizes and checksums.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

versionId
string

Version of the object; the policies see it as s3:versionid, as for the S3 request with the same versionId.

maxParts
integer [ 0 .. 1000 ]

Parts per page, 1 to 1000 (default 1000).

partNumberMarker
integer >= 0

The parts after this number.

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "versionId": "string",
  • "etag": "string",
  • "size": 0,
  • "lastModified": "2019-08-24T14:15:22Z",
  • "storageClass": "string",
  • "checksum": {
    },
  • "partsCount": 0,
  • "parts": [
    ],
  • "isTruncated": true,
  • "nextPartNumberMarker": 0
}

uploads

Upload a small object in one request (raw body, streamed)

The body is the content; its Content-Type is stored. Larger files use the multipart endpoints (limit: 64 MiB by default, 413 entity_too_large beyond). The policies see the condition values of the equivalent S3 PutObject (s3:x-amz-tagging, s3:RequestObjectTag/, s3:x-amz-server-side-encryption*).

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

header Parameters
x-amz-tagging
string

Tags of the new object, URL-encoded (k1=v1&k2=v2) as the S3 header of the same name; authorized with s3:RequestObjectTag/.

x-amz-server-side-encryption
string
Enum: "AES256" "aws:kms"

Server-side encryption of the new object, as the S3 header of the same name: AES256 (SSE-S3) or aws:kms (SSE-KMS). Without it the default encryption of the bucket applies. Authorized with s3:x-amz-server-side-encryption; without a KMS configured the upload is refused (501 not_implemented).

x-amz-server-side-encryption-aws-kms-key-id
string

The KMS key of an SSE-KMS upload (the default key of the KMS when absent); authorized with s3:x-amz-server-side-encryption-aws-kms-key-id.

Request Body schema: */*
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "versionId": "string",
  • "size": 0,
  • "etag": "string",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "contentType": "string",
  • "isDeleteMarker": true,
  • "isLatest": true,
  • "storageClass": "string"
}

Pending multipart uploads

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
prefix
string
cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Start a multipart upload proxied by the console

The encryption of the object is asked for here, as in the S3 CreateMultipartUpload.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
query Parameters
key
required
string

Object key.

header Parameters
x-amz-tagging
string

Tags of the new object, URL-encoded (k1=v1&k2=v2) as the S3 header of the same name; authorized with s3:RequestObjectTag/.

x-amz-server-side-encryption
string
Enum: "AES256" "aws:kms"

Server-side encryption of the new object, as the S3 header of the same name: AES256 (SSE-S3) or aws:kms (SSE-KMS). Without it the default encryption of the bucket applies. Authorized with s3:x-amz-server-side-encryption; without a KMS configured the upload is refused (501 not_implemented).

x-amz-server-side-encryption-aws-kms-key-id
string

The KMS key of an SSE-KMS upload (the default key of the KMS when absent); authorized with s3:x-amz-server-side-encryption-aws-kms-key-id.

Request Body schema: application/json
contentType
string
object

Responses

Request samples

Content type
application/json
{
  • "contentType": "string",
  • "userMetadata": {
    }
}

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "key": "string",
  • "uploadId": "string",
  • "initiated": "2019-08-24T14:15:22Z",
  • "partSize": 0,
  • "minPartSize": 0,
  • "maxPartSize": 0,
  • "maxParts": 0
}

Abort a multipart upload

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
uploadId
required
string
query Parameters
key
required
string

Object key.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Uploaded parts (to resume an upload)

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
uploadId
required
string
query Parameters
key
required
string

Object key.

cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Upload one part (raw body, streamed; Content-Length required)

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
uploadId
required
string
partNumber
required
integer [ 1 .. 10000 ]
query Parameters
key
required
string

Object key.

Request Body schema: */*
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "partNumber": 0,
  • "etag": "string",
  • "size": 0,
  • "lastModified": "2019-08-24T14:15:22Z"
}

Complete a multipart upload

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
uploadId
required
string
query Parameters
key
required
string

Object key.

Request Body schema: application/json
required
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "parts": [
    ]
}

Response samples

Content type
application/json
{
  • "key": "string",
  • "versionId": "string",
  • "size": 0,
  • "etag": "string",
  • "lastModified": "2019-08-24T14:15:22Z",
  • "contentType": "string",
  • "isDeleteMarker": true,
  • "isLatest": true,
  • "storageClass": "string"
}

shares

Create a managed share link in the bucket of the path (see POST /shares)

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
bucket
string

Required by POST /shares; taken from the path by POST /buckets/{bucket}/objects/share.

key
required
string
prefix
boolean
permission
string (SharePermission)
Enum: "download" "upload"
expiresIn
integer <int64> [ 0 .. 604800 ]

Validity in seconds (default and maximum 7 days).

contentType
string
contentDisposition
string
versionId
string
stream
boolean

Share a video (MP4, H.264 or H.265 with AAC) as an HLS stream: the URL of the share is the master playlist on the S3 listener (/nexo/media/v1/{bucket}/master.m3u8), whose playlists are signed by the share until it expires. Object download shares only, without contentType and contentDisposition.

Responses

Request samples

Content type
application/json
{
  • "bucket": "string",
  • "key": "string",
  • "prefix": true,
  • "permission": "download",
  • "expiresIn": 0,
  • "contentType": "string",
  • "contentDisposition": "string",
  • "versionId": "string",
  • "stream": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "owner": "string",
  • "bucket": "string",
  • "key": "string",
  • "prefix": true,
  • "permission": "download",
  • "versionId": "string",
  • "contentType": "string",
  • "contentDisposition": "string",
  • "stream": true,
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "accessKey": "string"
}

Active share links

The caller's own links; every link (filtered by owner/bucket) with admin:ManageShares.

Authorizations:
(sessioncsrf) sigv4
query Parameters
owner
string
bucket
string
cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create a managed, revocable share link

Signed by a dedicated service account (docs/09 §9.1); the caller needs the shared action (s3:GetObject or s3:PutObject).

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
bucket
string

Required by POST /shares; taken from the path by POST /buckets/{bucket}/objects/share.

key
required
string
prefix
boolean
permission
string (SharePermission)
Enum: "download" "upload"
expiresIn
integer <int64> [ 0 .. 604800 ]

Validity in seconds (default and maximum 7 days).

contentType
string
contentDisposition
string
versionId
string
stream
boolean

Share a video (MP4, H.264 or H.265 with AAC) as an HLS stream: the URL of the share is the master playlist on the S3 listener (/nexo/media/v1/{bucket}/master.m3u8), whose playlists are signed by the share until it expires. Object download shares only, without contentType and contentDisposition.

Responses

Request samples

Content type
application/json
{
  • "bucket": "string",
  • "key": "string",
  • "prefix": true,
  • "permission": "download",
  • "expiresIn": 0,
  • "contentType": "string",
  • "contentDisposition": "string",
  • "versionId": "string",
  • "stream": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "owner": "string",
  • "bucket": "string",
  • "key": "string",
  • "prefix": true,
  • "permission": "download",
  • "versionId": "string",
  • "contentType": "string",
  • "contentDisposition": "string",
  • "stream": true,
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "accessKey": "string"
}

Revoke every share link of an owner (the caller by default)

Authorizations:
(sessioncsrf) sigv4
query Parameters
owner
string

Responses

Response samples

Content type
application/json
{
  • "revoked": 0
}

getShare

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "owner": "string",
  • "bucket": "string",
  • "key": "string",
  • "prefix": true,
  • "permission": "download",
  • "versionId": "string",
  • "contentType": "string",
  • "contentDisposition": "string",
  • "stream": true,
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "accessKey": "string"
}

Revoke a share link (immediate)

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Raw presigned URL (not revocable), signed on the server with the caller's credentials

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
method
string
Enum: "GET" "PUT" "HEAD" "DELETE"
bucket
required
string
key
required
string
versionId
string
expiresIn
integer <int64> [ 0 .. 604800 ]

Validity in seconds (default and maximum 7 days), capped at the expiration of the credentials.

contentType
string

Signed Content-Type of PUT URLs, response-content-type of GET URLs.

contentDisposition
string

response-content-disposition of GET URLs.

object

Additional signed headers (x-amz-meta-*...).

Responses

Request samples

Content type
application/json
{
  • "method": "GET",
  • "bucket": "string",
  • "key": "string",
  • "versionId": "string",
  • "expiresIn": 0,
  • "contentType": "string",
  • "contentDisposition": "string",
  • "headers": {
    }
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "method": "string",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "headers": {
    }
}

Signed POST policy form for browser uploads

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
bucket
required
string
key
string

Exact key ("${filename}" is replaced by the file name).

keyPrefix
string

Any key under this prefix.

expiresIn
integer <int64> [ 0 .. 604800 ]

Validity in seconds (default 1 hour).

minSize
integer <int64>
maxSize
integer <int64>

content-length-range upper bound when positive.

contentType
string
contentTypePrefix
string
successActionStatus
integer
Enum: 200 201 204
successActionRedirect
string
object

Responses

Request samples

Content type
application/json
{
  • "bucket": "string",
  • "key": "string",
  • "keyPrefix": "string",
  • "expiresIn": 0,
  • "minSize": 0,
  • "maxSize": 0,
  • "contentType": "string",
  • "contentTypePrefix": "string",
  • "successActionStatus": 200,
  • "successActionRedirect": "string",
  • "fields": {
    }
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "fields": {
    },
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "conditions": [
    ]
}

users

listUsers

Authorizations:
(sessioncsrf) sigv4
query Parameters
cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

createUser

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
accessKey
required
string
secretKey
required
string
policyNames
Array of strings
groups
Array of strings

Existing groups the user joins.

status
string (CredentialStatus)
Enum: "enabled" "disabled"

Responses

Request samples

Content type
application/json
{
  • "accessKey": "string",
  • "secretKey": "string",
  • "policyNames": [
    ],
  • "groups": [
    ],
  • "status": "enabled"
}

Response samples

Content type
application/json
{
  • "accessKey": "string",
  • "status": "enabled",
  • "policyNames": [
    ],
  • "groups": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

getUser

Authorizations:
(sessioncsrf) sigv4
path Parameters
user
required
string

Responses

Response samples

Content type
application/json
{
  • "accessKey": "string",
  • "status": "enabled",
  • "policyNames": [
    ],
  • "groups": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

updateUser

Each change needs its action: secretKey admin:CreateUser, status admin:EnableUser/admin:DisableUser, policyNames admin:AttachUserOrGroupPolicy, groups admin:GetUser plus admin:AddUserToGroup/admin:RemoveUserFromGroup. A new secretKey, or status disabled, revokes for good the console sessions of the user (and of its access keys) and its managed share links.

Authorizations:
(sessioncsrf) sigv4
path Parameters
user
required
string
Request Body schema: application/json
required
secretKey
string
status
string (CredentialStatus)
Enum: "enabled" "disabled"
policyNames
Array of strings
groups
Array of strings

Replaces the group memberships.

Responses

Request samples

Content type
application/json
{
  • "secretKey": "string",
  • "status": "enabled",
  • "policyNames": [
    ],
  • "groups": [
    ]
}

Response samples

Content type
application/json
{
  • "accessKey": "string",
  • "status": "enabled",
  • "policyNames": [
    ],
  • "groups": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

deleteUser

Deletes the user with its access keys and STS credentials, then removes the records of its managed share links (their service accounts went with the user).

Authorizations:
(sessioncsrf) sigv4
path Parameters
user
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

groups

listGroups

Authorizations:
(sessioncsrf) sigv4
query Parameters
cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

createGroup

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
name
required
string
members
Array of strings
policyNames
Array of strings

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "members": [
    ],
  • "policyNames": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "status": "enabled",
  • "members": [
    ],
  • "policyNames": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

getGroup

Authorizations:
(sessioncsrf) sigv4
path Parameters
group
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "status": "enabled",
  • "members": [
    ],
  • "policyNames": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

updateGroup

Authorizations:
(sessioncsrf) sigv4
path Parameters
group
required
string
Request Body schema: application/json
required
status
string (CredentialStatus)
Enum: "enabled" "disabled"
policyNames
Array of strings
addMembers
Array of strings
removeMembers
Array of strings

Responses

Request samples

Content type
application/json
{
  • "status": "enabled",
  • "policyNames": [
    ],
  • "addMembers": [
    ],
  • "removeMembers": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "status": "enabled",
  • "members": [
    ],
  • "policyNames": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

deleteGroup

Authorizations:
(sessioncsrf) sigv4
path Parameters
group
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

access-keys

Access keys of a user (the caller by default)

The caller's own keys always; those of other users (or every key, without user) with admin:ListServiceAccounts.

Authorizations:
(sessioncsrf) sigv4
query Parameters
user
string
cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create an access key; the secret is returned only here

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
parentUser
string

Owner of the key; defaults to the caller. Naming another user requires admin:CreateServiceAccount.

accessKey
string

Generated when empty.

secretKey
string

Generated when empty.

name
string
description
string
expiration
string <date-time>
object (PolicyDocument)

An IAM or bucket policy in the AWS JSON format.

Responses

Request samples

Content type
application/json
{
  • "parentUser": "string",
  • "accessKey": "string",
  • "secretKey": "string",
  • "name": "string",
  • "description": "string",
  • "expiration": "2019-08-24T14:15:22Z",
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "accessKey": "string",
  • "parentUser": "string",
  • "name": "string",
  • "description": "string",
  • "status": "enabled",
  • "expiration": "2019-08-24T14:15:22Z",
  • "policy": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "secretKey": "string"
}

getAccessKey

Authorizations:
(sessioncsrf) sigv4
path Parameters
key
required
string

Responses

Response samples

Content type
application/json
{
  • "accessKey": "string",
  • "parentUser": "string",
  • "name": "string",
  • "description": "string",
  • "status": "enabled",
  • "expiration": "2019-08-24T14:15:22Z",
  • "policy": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

updateAccessKey

Status disabled revokes for good the console sessions of the key and the managed share links created with it; enabling it again restores neither.

Authorizations:
(sessioncsrf) sigv4
path Parameters
key
required
string
Request Body schema: application/json
required
secretKey
string
name
string
description
string
status
string (CredentialStatus)
Enum: "enabled" "disabled"
expiration
string <date-time>
clearExpiration
boolean

Remove the expiration.

object (PolicyDocument)

An IAM or bucket policy in the AWS JSON format.

clearPolicy
boolean

Remove the inline policy.

Responses

Request samples

Content type
application/json
{
  • "secretKey": "string",
  • "name": "string",
  • "description": "string",
  • "status": "enabled",
  • "expiration": "2019-08-24T14:15:22Z",
  • "clearExpiration": true,
  • "policy": {
    },
  • "clearPolicy": true
}

Response samples

Content type
application/json
{
  • "accessKey": "string",
  • "parentUser": "string",
  • "name": "string",
  • "description": "string",
  • "status": "enabled",
  • "expiration": "2019-08-24T14:15:22Z",
  • "policy": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

deleteAccessKey

Authorizations:
(sessioncsrf) sigv4
path Parameters
key
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

policies

Built-in and stored policies

Authorizations:
(sessioncsrf) sigv4
query Parameters
cursor
string

Opaque cursor of the next page (nextCursor of the previous one).

limit
integer [ 1 .. 1000 ]

Page size, 1 to 1000 (default 1000).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

createPolicy

409 conflict when the name exists; malformed documents are malformed_policy problems with their position.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
name
required
string
required
object or string (PolicyDocumentOrText)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "document": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "document": {
    },
  • "builtIn": true,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

attachPolicy

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
policyNames
required
Array of strings
user
string
group
string

Responses

Request samples

Content type
application/json
{
  • "policyNames": [
    ],
  • "user": "string",
  • "group": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

detachPolicy

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
policyNames
required
Array of strings
user
string
group
string

Responses

Request samples

Content type
application/json
{
  • "policyNames": [
    ],
  • "user": "string",
  • "group": "string"
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Evaluate a request with the enforcement engine

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
user
string

Access key to simulate (user or service account); the caller by default.

action
required
string
bucket
string
object
string
sourceIp
string
secureTransport
boolean
time
string <date-time>
object

Other condition values (aws:Referer, s3:prefix...).

Responses

Request samples

Content type
application/json
{
  • "user": "string",
  • "action": "string",
  • "bucket": "string",
  • "object": "string",
  • "sourceIp": "string",
  • "secureTransport": true,
  • "time": "2019-08-24T14:15:22Z",
  • "conditions": {
    }
}

Response samples

Content type
application/json
{
  • "user": "string",
  • "action": "string",
  • "bucket": "string",
  • "object": "string",
  • "allowed": true,
  • "decision": "allow",
  • "reason": "string",
  • "source": "root",
  • "policyName": "string",
  • "group": "string",
  • "statement": {
    },
  • "evaluated": [
    ]
}

Validate an IAM policy, or a bucket policy of `bucket`, without storing it

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
required
object or string (PolicyDocumentOrText)
bucket
string

Validate a bucket policy of this bucket.

Responses

Request samples

Content type
application/json
{
  • "document": {
    },
  • "bucket": "string"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "errors": [
    ]
}

getPolicy

Authorizations:
(sessioncsrf) sigv4
path Parameters
policy
required
string

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "document": {
    },
  • "builtIn": true,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

savePolicy

Authorizations:
(sessioncsrf) sigv4
path Parameters
policy
required
string
Request Body schema: application/json
required
required
object or string (PolicyDocumentOrText)

Responses

Request samples

Content type
application/json
{
  • "document": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "document": {
    },
  • "builtIn": true,
  • "updatedAt": "2019-08-24T14:15:22Z"
}

deletePolicy

Authorizations:
(sessioncsrf) sigv4
path Parameters
policy
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Users and groups a policy is attached to

Authorizations:
(sessioncsrf) sigv4
path Parameters
policy
required
string

Responses

Response samples

Content type
application/json
{
  • "policy": "string",
  • "users": [
    ],
  • "groups": [
    ]
}

config

Every known subsystem with its settings (sensitive values masked)

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Merge the settings of several subsystems (validated first)

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
additional property
object (ConfigSettings)

Responses

Request samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Known subsystems and keys

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Export the whole configuration (secrets included)

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Replace the whole configuration (validated first)

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
additional property
object (ConfigSettings)

Responses

Request samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

getConfigSubsystem

Authorizations:
(sessioncsrf) sigv4
path Parameters
subsys
required
string

A subsystem of GET /config/schema (api, browser, logger, notify_webhook, region, scanner).

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    }
}

setConfigSubsystem

Merges the settings; a masked sensitive value keeps the stored secret.

Authorizations:
(sessioncsrf) sigv4
path Parameters
subsys
required
string

A subsystem of GET /config/schema (api, browser, logger, notify_webhook, region, scanner).

Request Body schema: application/json
required
required
object (ConfigSettings)

Responses

Request samples

Content type
application/json
{
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    }
}

deleteConfigSubsystem

Authorizations:
(sessioncsrf) sigv4
path Parameters
subsys
required
string

A subsystem of GET /config/schema (api, browser, logger, notify_webhook, region, scanner).

query Parameters
keys
string

Comma separated keys to remove; absent removes the whole subsystem.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

cluster

Export the state of the deployment besides its objects

A versioned zip archive (manifest.json, iam.bin, policies.json, config.json, buckets/.json) holding the IAM state (users, groups, access keys, STS credentials and their policy attachments, encrypted with a key derived from the root secret key), the named policies, the dynamic configuration (secrets included) and the settings of every bucket (versioning, object lock, policy, lifecycle, encryption, quota, tags, CORS, notifications). With nexoctl mirror for the objects it migrates a deployment to another mode.

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Import an archive of GET /cluster/export

The whole archive is validated first (format, version, policies, configuration, bucket names); with dryRun the import stops there and reports what it would do. It then applies the configuration, the named policies, the IAM state (the target must share the root credentials of the source) and the bucket settings, creating the missing buckets. merge (default) keeps what the archive does not hold; replace also replaces the whole configuration and removes the users, groups and named policies the archive does not hold and the settings of the archived buckets it does not set (buckets are never removed).

Authorizations:
(sessioncsrf) sigv4
query Parameters
mode
string
Enum: "merge" "replace"
dryRun
boolean
Request Body schema: application/zip
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "mode": "merge",
  • "dryRun": true,
  • "users": 0,
  • "groups": 0,
  • "policies": 0,
  • "configSubsystems": 0,
  • "buckets": 0,
  • "bucketsCreated": [
    ],
  • "removed": [
    ]
}

List the namespace locks held across the lock servers

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Release namespace locks on every lock server, whoever holds them

Diagnostics of stuck locks (admin lock clear). An operation holding a released lock loses it at its next lease renewal and stops before its commit.

Authorizations:
(sessioncsrf) sigv4
query Parameters
resource
required
Array of strings

A resource to release ("bucket/key"); repeatable.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

notify

Notification targets with their delivery state

The targets of the notify_* subsystems of the configuration (disabled ones included), with the state the answering node sees: online (no failed delivery since the last success) and the events pending in its persistent queue. The ARN is what the event subscriptions name.

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Send a test event to a target

Delivers an s3:TestEvent at once, outside of the queue of the target, and reports the outcome (a failed delivery is a 200 with delivered: false), which also updates the state of the target. A namespace target (Redis, PostgreSQL) gets no entry.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

":" of the target ("_" is the id of the default target of a subsystem) or its ARN.

Responses

Response samples

Content type
application/json
{
  • "target": "string",
  • "delivered": true,
  • "error": "string"
}

kms

Status of the KMS of the server-side encryption

The KMS that seals the keys of the SSE-S3 and SSE-KMS objects: the builtin KMS (master key NEXO_KMS_SECRET_KEY) or the external KES servers (NEXO_KMS_ENDPOINT). Without KMS configured is false and SSE-S3/SSE-KMS are refused (SSE-C still works).

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "configured": true,
  • "backend": "builtin",
  • "defaultKeyId": "string",
  • "endpoints": [
    ],
  • "online": true,
  • "error": "string",
  • "version": "string"
}

Keys of the KMS

Authorizations:
(sessioncsrf) sigv4
query Parameters
prefix
string

Only the keys whose name starts with the prefix.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a KMS key (SSE-KMS)

Creates a key usable as SSE-KMS key id (x-amz-server-side-encryption-aws-kms-key-id) and as default key of a bucket encryption; 409 when it exists, 501 without KMS.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
id
required
string

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "default": true
}

Re-seal the data keys of the objects under the current master key

After a rotation of the master key of the KMS (the previous key in NEXO_KMS_SECRET_KEY_PREVIOUS), re-seals the data key of every SSE-S3 and SSE-KMS version of the bucket (every bucket without one) under the current master key; the data is not rewritten. Once every bucket is re-sealed the previous master keys can be removed. The versions that cannot be re-sealed are counted. 501 without KMS.

Authorizations:
(sessioncsrf) sigv4
query Parameters
bucket
string

Only the objects of this bucket.

Responses

Response samples

Content type
application/json
{
  • "buckets": 0,
  • "versions": 0,
  • "uploads": 0,
  • "resealed": 0,
  • "failed": 0,
  • "firstError": "string"
}

access-rules

Access rules of the bucket

The access rules of the bucket (docs/10 §10.1): prefix, glob and RE2 regex patterns of the keys, principals, actions, conditions and priorities, evaluated by the policy engine next to the bucket policy. The ETag header (and etag) identify the version of the rules for the If-Match of PUT. A bucket without rules answers an empty list.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "rules": [
    ],
  • "etag": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "public": true,
  • "blockPublic": true,
  • "warnings": [
    ]
}

Replace the access rules of the bucket atomically

Validates every rule (pattern compiled at once, at most --access-rules-max rules per bucket, 200 by default) and replaces the rules of the bucket in one change, propagated to every node. With If-Match the change applies only to the version of the rules with that ETag (412 precondition_failed otherwise). An invalid rule answers 400 invalid_access_rule (too many: too_many_access_rules) with the rule, the field and the position of the problem in the pattern in accessRuleErrors; an allow rule for everyone while the block public access is on in the reject mode answers 403 public_access_blocked. Every change is audited.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
header Parameters
If-Match
string

The ETag of the version the change applies to (quoted or not); a different current version answers 412 precondition_failed. Absent or *, the change applies unconditionally.

Request Body schema: application/json
required
required
Array of objects (BucketAccessRule)

Every rule of the bucket; an empty list removes them.

Responses

Request samples

Content type
application/json
{
  • "rules": [
    ]
}

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "rules": [
    ],
  • "etag": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "public": true,
  • "blockPublic": true,
  • "warnings": [
    ]
}

Test the access rules on keys (pattern tester, simulator)

Evaluates the requests of a principal on keys of the bucket with every source of the policy engine (IAM, bucket policy, access rules), without performing them: for each key the rules that match, the outcome of the rules alone, the final decision and the rule that determined it (docs/10 D-ACC-02, nexoctl access test). The keys are matched after their normalization (normalizedKey). Authorized by the service: admin:ManageAccessRules on the bucket and, to test the requests of another identity than the caller's, admin:SimulatePolicy.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
optional
keys
Array of strings

Keys to test (the listing prefixes of a listing action); none tests the bucket.

action
string

An action class (read, list, write, delete, tag) or an S3 action; default read.

principal
string

anonymous (default), user:<name>, accesskey:<key> (or a bare access key), distribution:<id>.

ip
string

Client address.

host
string

Host the request is addressed to.

method
string

HTTP method (default derived from the action).

secure
boolean

HTTPS (absent - unknown).

referer
string
object
distribution
string

Distribution serving the request.

time
string <date-time>

Time of the request (default now).

Responses

Request samples

Content type
application/json
{
  • "keys": [
    ],
  • "action": "string",
  • "principal": "string",
  • "ip": "string",
  • "host": "string",
  • "method": "string",
  • "secure": true,
  • "referer": "string",
  • "headers": {
    },
  • "distribution": "string",
  • "time": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "action": "string",
  • "blockPublic": {
    },
  • "results": [
    ]
}

Public status of the bucket through its access rules

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "public": true,
  • "preset": "private",
  • "rules": [
    ],
  • "blocked": true
}

Apply a public access preset

Replaces the rules generated by the presets (ids starting with preset-) with those of the preset: private (also removes every allow rule for everyone), public-read, public-read-list, public-prefix (with match) and public-write (with confirm: 400 confirmation_required otherwise). The other rules are kept. If-Match as for PUT /buckets/{bucket}/access-rules.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
header Parameters
If-Match
string

The ETag of the version the change applies to (quoted or not); a different current version answers 412 precondition_failed. Absent or *, the change applies unconditionally.

Request Body schema: application/json
required
preset
required
string (AccessRulesPreset)
Enum: "private" "public-read" "public-read-list" "public-prefix" "public-write" "custom"
object

The keys of public-prefix (required) and public-write (optional).

confirm
boolean

Acknowledges public-write.

Responses

Request samples

Content type
application/json
{
  • "preset": "private",
  • "match": {
    },
  • "confirm": true
}

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "rules": [
    ],
  • "etag": "string",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "updatedBy": "string",
  • "public": true,
  • "blockPublic": true,
  • "warnings": [
    ]
}

Block public access of the bucket

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string

Responses

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "enabled": true,
  • "mode": "reject",
  • "cluster": true,
  • "effective": true
}

Turn the block public access of the bucket on or off

The mode is a setting of the cluster (PUT /access/block-public); a mode here is 400.

Authorizations:
(sessioncsrf) sigv4
path Parameters
bucket
required
string
Request Body schema: application/json
required
enabled
required
boolean
mode
string
Enum: "reject" "ignore"

Cluster level only; absent keeps it.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "mode": "reject"
}

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "enabled": true,
  • "mode": "reject",
  • "cluster": true,
  • "effective": true
}

Block public access of the cluster

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "enabled": true,
  • "mode": "reject",
  • "cluster": true,
  • "effective": true
}

Turn the block public access of the cluster on or off

While on, the principal * of the allow rules of every bucket is ignored and, in the reject mode, such a rule is refused when saved (the stored ones are ignored); in the ignore mode they are accepted and ignored. Deny rules for everyone are never affected. Stored in the dynamic configuration (subsystem access), it applies to every node without restart.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
enabled
required
boolean
mode
string
Enum: "reject" "ignore"

Cluster level only; absent keeps it.

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "mode": "reject"
}

Response samples

Content type
application/json
{
  • "bucket": "string",
  • "enabled": true,
  • "mode": "reject",
  • "cluster": true,
  • "effective": true
}

distributions

Distributions (custom domains of the buckets)

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a distribution

Validates and stores the distribution (docs/10 §10.2); the routing table of every node is updated without restart. An alias used by another distribution (or the S3 and console domains) answers 409 alias_conflict, an invalid distribution 400 invalid_distribution. admin:ManageDistributions is also evaluated on the origin bucket: an explicit Deny on a bucket keeps it from being exposed. Origin secrets given in clear are stored hashed.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
id
required
string

Lowercase letters, digits, '.', '_' and '-' (at most 64).

enabled
boolean
comment
string
aliases
required
Array of strings

Host names, exact or wildcard (*.preview.example.com), unique across the distributions.

required
object
mode
string (DistributionMode)
Enum: "website" "s3"

website (static sites, downloads; never S3 XML) or s3 (the domain is an S3 endpoint of the bucket).

object (DistributionBehavior)

How the requests of a path are served; an unset field inherits from the default behavior.

Array of objects (DistributionBehavior)

Evaluated in order, the first match wins.

Array of objects
Array of objects
object
object
object
object
createdAt
string <date-time>
updatedAt
string <date-time>
etag
string

The stored version (If-Match of PUT); ignored in requests.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "enabled": true,
  • "comment": "string",
  • "aliases": [
    ],
  • "origin": {
    },
  • "mode": "website",
  • "defaultBehavior": {
    },
  • "behaviors": [
    ],
  • "errorPages": [
    ],
  • "redirects": [
    ],
  • "headers": {
    },
  • "restrictions": {
    },
  • "tls": {
    },
  • "logging": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "enabled": true,
  • "comment": "string",
  • "aliases": [
    ],
  • "origin": {
    },
  • "mode": "website",
  • "defaultBehavior": {
    },
  • "behaviors": [
    ],
  • "errorPages": [
    ],
  • "redirects": [
    ],
  • "headers": {
    },
  • "restrictions": {
    },
  • "tls": {
    },
  • "logging": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

A distribution

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "enabled": true,
  • "comment": "string",
  • "aliases": [
    ],
  • "origin": {
    },
  • "mode": "website",
  • "defaultBehavior": {
    },
  • "behaviors": [
    ],
  • "errorPages": [
    ],
  • "redirects": [
    ],
  • "headers": {
    },
  • "restrictions": {
    },
  • "tls": {
    },
  • "logging": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Replace a distribution

Replaces the whole document (its id is the one of the path). With If-Match the change applies only to the version with that ETag (412 otherwise). admin:ManageDistributions is also evaluated on the current and the new origin buckets.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

header Parameters
If-Match
string

The ETag of the version the change applies to (quoted or not); a different current version answers 412 precondition_failed. Absent or *, the change applies unconditionally.

Request Body schema: application/json
required
id
required
string

Lowercase letters, digits, '.', '_' and '-' (at most 64).

enabled
boolean
comment
string
aliases
required
Array of strings

Host names, exact or wildcard (*.preview.example.com), unique across the distributions.

required
object
mode
string (DistributionMode)
Enum: "website" "s3"

website (static sites, downloads; never S3 XML) or s3 (the domain is an S3 endpoint of the bucket).

object (DistributionBehavior)

How the requests of a path are served; an unset field inherits from the default behavior.

Array of objects (DistributionBehavior)

Evaluated in order, the first match wins.

Array of objects
Array of objects
object
object
object
object
createdAt
string <date-time>
updatedAt
string <date-time>
etag
string

The stored version (If-Match of PUT); ignored in requests.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "enabled": true,
  • "comment": "string",
  • "aliases": [
    ],
  • "origin": {
    },
  • "mode": "website",
  • "defaultBehavior": {
    },
  • "behaviors": [
    ],
  • "errorPages": [
    ],
  • "redirects": [
    ],
  • "headers": {
    },
  • "restrictions": {
    },
  • "tls": {
    },
  • "logging": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "enabled": true,
  • "comment": "string",
  • "aliases": [
    ],
  • "origin": {
    },
  • "mode": "website",
  • "defaultBehavior": {
    },
  • "behaviors": [
    ],
  • "errorPages": [
    ],
  • "redirects": [
    ],
  • "headers": {
    },
  • "restrictions": {
    },
  • "tls": {
    },
  • "logging": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Remove a distribution

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

How the distribution serves a URL

Without reading the object: the route of the host, the behavior that matches the path (-1 for the default one) with its inherited fields resolved (access, methods, cache), the object of the path, the redirection or the refusal, and the headers of the response (docs/10 D-DST-03, nexoctl dist test). A path is completed with https and the first exact alias; a URL whose host is not an alias of the distribution is 400.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Request Body schema: application/json
required
url
required
string

An absolute URL on an alias of the distribution, or a path.

method
string

Default GET.

clientIp
string

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "method": "string",
  • "clientIp": "string"
}

Response samples

Content type
application/json
{
  • "route": {
    },
  • "behaviorIndex": 0,
  • "behavior": {
    },
  • "bucket": "string",
  • "key": "string",
  • "redirectStatus": 0,
  • "redirectLocation": "string",
  • "refusalStatus": 0,
  • "refusal": "string",
  • "responseHeaders": {
    }
}

Rotate the origin secret of the proxies

Generates a new origin secret, returned in clear once (stored hashed), and keeps the most recent previous ones active (keep, default 1) so that the proxies are updated without downtime; the requests without one of the active secrets in the header are refused.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Request Body schema: application/json
optional
header
string

Default the current header, or X-Origin-Secret.

keep
integer >= 0

Previous secrets kept active (default 1).

dropPrevious
boolean

Responses

Request samples

Content type
application/json
{
  • "header": "string",
  • "keep": 0,
  • "dropPrevious": true
}

Response samples

Content type
application/json
{
  • "secret": "string",
  • "header": "string",
  • "distribution": {
    }
}

Sign a URL, or cookies, of a signed behavior

CloudFront-style signed URL (?Expires=&Signature=&Key-Pair-Id=, or ?Policy= for a custom policy with resource, notBefore or ipRange) or signed cookies (cookies: true) for the URL, which a signed behavior of the distribution must serve. The server never stores the private keys: the caller sends the private key of a key of the key group of the behavior (its key pair id is found from the key when not given). Exactly one of expiresIn and expiresAt.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Request Body schema: application/json
required
url
required
string

An absolute URL on an alias, or a path completed with scheme and host.

scheme
string
Enum: "http" "https"
host
string

Default the first exact alias.

privateKeyPem
required
string

PKCS 8 (or PKCS 1 RSA) private key of a key of the key group.

keyPairId
string
expiresIn
integer >= 1

Seconds from now.

expiresAt
string <date-time>
notBefore
string <date-time>
ipRange
string

IP or CIDR of the viewers.

resource
string

URL with * and ? wildcards (default the URL).

cookies
boolean

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "scheme": "http",
  • "host": "string",
  • "privateKeyPem": "string",
  • "keyPairId": "string",
  • "expiresIn": 1,
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "notBefore": "2019-08-24T14:15:22Z",
  • "ipRange": "string",
  • "resource": "string",
  • "cookies": true
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "cookies": [
    ],
  • "keyGroup": "string",
  • "keyPairId": "string",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Key groups of the signed behaviors

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a key group

With generateKey, its first key pair is generated: the private key is in the answer once and never stored (docs/10: "downloadable only once").

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
id
required
string
comment
string
object (GenerateKeyRequest)

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "comment": "string",
  • "generateKey": {
    }
}

Response samples

Content type
application/json
{
  • "keyGroup": {
    },
  • "key": {
    }
}

A key group

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the key group.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "comment": "string",
  • "keys": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Remove a key group no distribution references (409 otherwise)

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the key group.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Public keys of a key group

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the key group.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add a key to a key group

A public key provided by the user (publicKeyPem, PKIX, Ed25519 or RSA of 2048 to 4096 bits), or a key pair generated by the server whose private key is in the answer once. Several keys sign at once: a new key is added before the old one is removed (rotation without downtime).

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the key group.

Request Body schema: application/json
optional
publicKeyPem
string

A PKIX public key; absent generates a key pair.

algorithm
string
Enum: "ed25519" "rsa"
bits
integer
comment
string

Responses

Request samples

Content type
application/json
{
  • "publicKeyPem": "string",
  • "algorithm": "ed25519",
  • "bits": 0,
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "publicKey": {
    },
  • "privateKeyPem": "string"
}

Remove a key from its key group

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the key group.

key
required
string

Key pair id (Key-Pair-Id of the signed URLs).

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

What serves a host (routing diagnostics)

The resolution of the routing table of the answering node: an exact alias, then the most specific wildcard alias of a distribution, <bucket>.<domain> (virtual-host), the S3 and console domains (main), otherwise the path-style S3 API (or 421, misdirected, when the deployment asks for it).

Authorizations:
(sessioncsrf) sigv4
query Parameters
host
required
string

The host, with or without port.

Responses

Response samples

Content type
application/json
{
  • "kind": "distribution",
  • "host": "string",
  • "alias": "string",
  • "distribution": "string",
  • "mode": "website",
  • "enabled": true,
  • "bucket": "string"
}

certificates

TLS certificates of the domains of the distributions

The uploaded and ACME certificates (never their keys) with their status (expiring within 21 days), the distributions using them, and the ACME certificates of the distributions with tls.certificate: auto, obtained or pending (the leader orders and renews them).

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "acme": {
    }
}

Upload a PEM certificate

The leaf certificate followed by its intermediates and its private key, validated (chain linkage, key matching the leaf, DNS names, validity: 400 invalid_certificate), stored sealed and served by SNI on every node. A certificate of the same id is replaced. Distributions use it with tls.certificate: upload:<id>.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
id
string

Default derived from the first DNS name.

certificatePem
required
string

Leaf certificate followed by its intermediates.

privateKeyPem
required
string

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "certificatePem": "string",
  • "privateKeyPem": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "source": "upload",
  • "domains": [
    ],
  • "subject": "string",
  • "issuer": "string",
  • "serial": "string",
  • "notBefore": "2019-08-24T14:15:22Z",
  • "notAfter": "2019-08-24T14:15:22Z",
  • "fingerprint": "string",
  • "status": "valid",
  • "lastError": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "usedBy": [
    ]
}

A certificate

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "source": "upload",
  • "domains": [
    ],
  • "subject": "string",
  • "issuer": "string",
  • "serial": "string",
  • "notBefore": "2019-08-24T14:15:22Z",
  • "notAfter": "2019-08-24T14:15:22Z",
  • "fingerprint": "string",
  • "status": "valid",
  • "lastError": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "usedBy": [
    ]
}

Remove a certificate no distribution names (409 otherwise)

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

DNS providers of the ACME DNS-01 challenge

The DNS providers (Cloudflare, AWS Route 53, RFC 2136) that publish the TXT records of the DNS-01 challenge, required by the wildcard aliases. Their credentials are sealed in the system store and never returned (hasCredentials reports them).

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a DNS provider

Validated (400 invalid_dns_provider; 409 dns_provider_exists for a name taken). Only the settings and credentials of its type are kept.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
type
required
string (DnsProviderType)
Enum: "cloudflare" "route53" "rfc2136"
comment
string
object
object
object
ttl
integer

TTL of the records in seconds (default 60).

propagationTimeout
integer

Wait of the propagation in seconds (default 120, at most 1800).

pollingInterval
integer

Delay between two checks in seconds (default 4).

name
string

Required to create; the one of the path to update.

object

Write-only, sealed in the system store, never returned nor logged. On an update an empty field keeps the stored value.

Responses

Request samples

Content type
application/json
{
  • "type": "cloudflare",
  • "comment": "string",
  • "cloudflare": {
    },
  • "route53": {
    },
  • "rfc2136": {
    },
  • "ttl": 0,
  • "propagationTimeout": 0,
  • "pollingInterval": 0,
  • "name": "string",
  • "credentials": {
    }
}

Response samples

Content type
application/json
{
  • "type": "cloudflare",
  • "comment": "string",
  • "cloudflare": {
    },
  • "route53": {
    },
  • "rfc2136": {
    },
  • "ttl": 0,
  • "propagationTimeout": 0,
  • "pollingInterval": 0,
  • "name": "string",
  • "hasCredentials": true,
  • "usedBy": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

A DNS provider (404 `dns_provider_not_found`)

Authorizations:
(sessioncsrf) sigv4
path Parameters
name
required
string

Responses

Response samples

Content type
application/json
{
  • "type": "cloudflare",
  • "comment": "string",
  • "cloudflare": {
    },
  • "route53": {
    },
  • "rfc2136": {
    },
  • "ttl": 0,
  • "propagationTimeout": 0,
  • "pollingInterval": 0,
  • "name": "string",
  • "hasCredentials": true,
  • "usedBy": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Replace the settings of a DNS provider

The empty credentials keep the stored ones when the type does not change (a Route 53 provider without accessKeyId drops them: ambient credentials). The leader retries at once the pending certificates of the distributions using the provider.

Authorizations:
(sessioncsrf) sigv4
path Parameters
name
required
string
Request Body schema: application/json
required
type
required
string (DnsProviderType)
Enum: "cloudflare" "route53" "rfc2136"
comment
string
object
object
object
ttl
integer

TTL of the records in seconds (default 60).

propagationTimeout
integer

Wait of the propagation in seconds (default 120, at most 1800).

pollingInterval
integer

Delay between two checks in seconds (default 4).

name
string

Required to create; the one of the path to update.

object

Write-only, sealed in the system store, never returned nor logged. On an update an empty field keeps the stored value.

Responses

Request samples

Content type
application/json
{
  • "type": "cloudflare",
  • "comment": "string",
  • "cloudflare": {
    },
  • "route53": {
    },
  • "rfc2136": {
    },
  • "ttl": 0,
  • "propagationTimeout": 0,
  • "pollingInterval": 0,
  • "name": "string",
  • "credentials": {
    }
}

Response samples

Content type
application/json
{
  • "type": "cloudflare",
  • "comment": "string",
  • "cloudflare": {
    },
  • "route53": {
    },
  • "rfc2136": {
    },
  • "ttl": 0,
  • "propagationTimeout": 0,
  • "pollingInterval": 0,
  • "name": "string",
  • "hasCredentials": true,
  • "usedBy": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Remove a DNS provider no distribution names (409 `dns_provider_in_use` otherwise)

Authorizations:
(sessioncsrf) sigv4
path Parameters
name
required
string

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Test a DNS provider

Publishes a TXT record _acme-challenge.<domain> with a random value, waits for it on the authoritative nameservers of the zone (up to the propagation timeout of the provider) and removes it. A failure of the provider is a result (ok: false, the failed step), not an error.

Authorizations:
(sessioncsrf) sigv4
path Parameters
name
required
string
Request Body schema: application/json
required
domain
required
string

Domain of the test record (a wildcard counts as its domain).

Responses

Request samples

Content type
application/json
{
  • "domain": "string"
}

Response samples

Content type
application/json
{
  • "ok": true,
  • "record": "string",
  • "step": "present",
  • "error": "string",
  • "durationMs": 0
}

cache

Cache policies (built-in and defined)

The reusable cache policies (docs/11 §11.2), by name: the built-in ones (disabled, standard, aggressive, immutable-assets, respect-origin, read-only, builtin: true) and those defined by the administrators. Every policy is complete: its unset fields take the values of standard.

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Define a cache policy

Validates (TTL min ≤ default ≤ max, durations, sizes, media types...) and stores the policy; every node applies it at once. A name already taken answers 409 already_exists, a built-in name 409 builtin_cache_policy, an invalid policy 400 invalid_cache_request.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
object

Lifetime in cache when the object states none (default), and bounds of every lifetime (min, max).

respectObjectCacheControl
boolean

Use the Cache-Control and Expires stored with the objects.

browserCacheControl
string

Cache-Control sent to the clients; empty keeps the one of the object.

object
string or number (CacheDuration)
string or number (CacheDuration)
string or number (CacheDuration)
object
object
string or integer (CacheSize)
string or integer (CacheSize)
object
object
name
required
string

Lowercase letters, digits, '.', '_' and '-' (at most 64).

comment
string
builtin
boolean

A predefined, read-only policy; ignored in requests.

updatedAt
string <date-time>
etag
string

The stored version; ignored in requests.

Responses

Request samples

Content type
application/json
{
  • "ttl": {
    },
  • "respectObjectCacheControl": true,
  • "browserCacheControl": "string",
  • "cacheKey": {
    },
  • "staleWhileRevalidate": "string",
  • "staleIfError": "string",
  • "negativeCaching": "string",
  • "bypass": {
    },
  • "compression": {
    },
  • "minSize": "string",
  • "maxObjectSize": "string",
  • "rangeCaching": {
    },
  • "contentTypes": {
    },
  • "name": "string",
  • "comment": "string",
  • "builtin": true,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Response samples

Content type
application/json
{
  • "ttl": {
    },
  • "respectObjectCacheControl": true,
  • "browserCacheControl": "string",
  • "cacheKey": {
    },
  • "staleWhileRevalidate": "string",
  • "staleIfError": "string",
  • "negativeCaching": "string",
  • "bypass": {
    },
  • "compression": {
    },
  • "minSize": "string",
  • "maxObjectSize": "string",
  • "rangeCaching": {
    },
  • "contentTypes": {
    },
  • "name": "string",
  • "comment": "string",
  • "builtin": true,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

A cache policy

Authorizations:
(sessioncsrf) sigv4
path Parameters
name
required
string

Name of the cache policy.

Responses

Response samples

Content type
application/json
{
  • "ttl": {
    },
  • "respectObjectCacheControl": true,
  • "browserCacheControl": "string",
  • "cacheKey": {
    },
  • "staleWhileRevalidate": "string",
  • "staleIfError": "string",
  • "negativeCaching": "string",
  • "bypass": {
    },
  • "compression": {
    },
  • "minSize": "string",
  • "maxObjectSize": "string",
  • "rangeCaching": {
    },
  • "contentTypes": {
    },
  • "name": "string",
  • "comment": "string",
  • "builtin": true,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Replace a defined cache policy

Replaces the whole policy (its name is the one of the path); with If-Match only the version with that ETag (412 otherwise). The entries cached under the policy are dropped. A built-in policy answers 409 builtin_cache_policy.

Authorizations:
(sessioncsrf) sigv4
path Parameters
name
required
string

Name of the cache policy.

header Parameters
If-Match
string

The ETag of the version the change applies to (quoted or not); a different current version answers 412 precondition_failed. Absent or *, the change applies unconditionally.

Request Body schema: application/json
required
object

Lifetime in cache when the object states none (default), and bounds of every lifetime (min, max).

respectObjectCacheControl
boolean

Use the Cache-Control and Expires stored with the objects.

browserCacheControl
string

Cache-Control sent to the clients; empty keeps the one of the object.

object
string or number (CacheDuration)
string or number (CacheDuration)
string or number (CacheDuration)
object
object
string or integer (CacheSize)
string or integer (CacheSize)
object
object
name
required
string

Lowercase letters, digits, '.', '_' and '-' (at most 64).

comment
string
builtin
boolean

A predefined, read-only policy; ignored in requests.

updatedAt
string <date-time>
etag
string

The stored version; ignored in requests.

Responses

Request samples

Content type
application/json
{
  • "ttl": {
    },
  • "respectObjectCacheControl": true,
  • "browserCacheControl": "string",
  • "cacheKey": {
    },
  • "staleWhileRevalidate": "string",
  • "staleIfError": "string",
  • "negativeCaching": "string",
  • "bypass": {
    },
  • "compression": {
    },
  • "minSize": "string",
  • "maxObjectSize": "string",
  • "rangeCaching": {
    },
  • "contentTypes": {
    },
  • "name": "string",
  • "comment": "string",
  • "builtin": true,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Response samples

Content type
application/json
{
  • "ttl": {
    },
  • "respectObjectCacheControl": true,
  • "browserCacheControl": "string",
  • "cacheKey": {
    },
  • "staleWhileRevalidate": "string",
  • "staleIfError": "string",
  • "negativeCaching": "string",
  • "bypass": {
    },
  • "compression": {
    },
  • "minSize": "string",
  • "maxObjectSize": "string",
  • "rangeCaching": {
    },
  • "contentTypes": {
    },
  • "name": "string",
  • "comment": "string",
  • "builtin": true,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Remove a defined cache policy

A policy named by the settings of the cluster or of a distribution answers 409 cache_policy_in_use.

Authorizations:
(sessioncsrf) sigv4
path Parameters
name
required
string

Name of the cache policy.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Validate a policy and preview its Cache-Control

Without storing it: the policy completed with the defaults, the Cache-Control it sends to the clients (inherited when it is the one of the objects) and a one-line summary (the editor of the console, D-CCH-03). An invalid policy answers 400 invalid_cache_request with the field at fault in detail.

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
object

Lifetime in cache when the object states none (default), and bounds of every lifetime (min, max).

respectObjectCacheControl
boolean

Use the Cache-Control and Expires stored with the objects.

browserCacheControl
string

Cache-Control sent to the clients; empty keeps the one of the object.

object
string or number (CacheDuration)
string or number (CacheDuration)
string or number (CacheDuration)
object
object
string or integer (CacheSize)
string or integer (CacheSize)
object
object
name
required
string

Lowercase letters, digits, '.', '_' and '-' (at most 64).

comment
string
builtin
boolean

A predefined, read-only policy; ignored in requests.

updatedAt
string <date-time>
etag
string

The stored version; ignored in requests.

Responses

Request samples

Content type
application/json
{
  • "ttl": {
    },
  • "respectObjectCacheControl": true,
  • "browserCacheControl": "string",
  • "cacheKey": {
    },
  • "staleWhileRevalidate": "string",
  • "staleIfError": "string",
  • "negativeCaching": "string",
  • "bypass": {
    },
  • "compression": {
    },
  • "minSize": "string",
  • "maxObjectSize": "string",
  • "rangeCaching": {
    },
  • "contentTypes": {
    },
  • "name": "string",
  • "comment": "string",
  • "builtin": true,
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Response samples

Content type
application/json
{
  • "policy": {
    },
  • "cacheControl": "string",
  • "inherited": true,
  • "summary": "string"
}

Cache settings of the cluster

The global level of the inheritance (docs/11 §11.1); the debug secret is masked.

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "cache": {
    },
  • "nodeHeader": true,
  • "debug": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Replace the cache settings of the cluster

No quota (the size of the cache is --cache-size) nor webhooks at this level. A masked debug secret keeps the stored one.

Authorizations:
(sessioncsrf) sigv4
header Parameters
If-Match
string

The ETag of the version the change applies to (quoted or not); a different current version answers 412 precondition_failed. Absent or *, the change applies unconditionally.

Request Body schema: application/json
required
required
object (CacheSettings)

The cache settings of a level: whether the cache is on, the policy it starts from (naming one replaces what the more general levels set) and the fields of the policy it overrides.

nodeHeader
boolean

Add X-Cache-Node to every answer.

object

The request header unlocking X-Cache-Key, X-Cache-Policy and X-Cache-Node.

updatedAt
string <date-time>
etag
string

Responses

Request samples

Content type
application/json
{
  • "cache": {
    },
  • "nodeHeader": true,
  • "debug": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Response samples

Content type
application/json
{
  • "cache": {
    },
  • "nodeHeader": true,
  • "debug": {
    },
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

How the cache serves a URL

The cache key computed for the URL, the effective policy with the level each setting comes from (fields), why the cache would be bypassed, and the entry of the key on every node: tier, age, freshness, size, compressed variants (docs/11 §11.7, D-CCH-05). Nothing is read from the origin.

Authorizations:
(sessioncsrf) sigv4
query Parameters
url
required
string

An absolute http(s) URL on a domain of a distribution, or a path of distribution.

distribution
string

The distribution the URL must be served by (a path is completed with https and its first exact alias).

header
Array of strings

A request header of the key ("Accept-Encoding: br"), repeatable.

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "distribution": "string",
  • "host": "string",
  • "path": "string",
  • "bucket": "string",
  • "key": "string",
  • "cacheKey": "string",
  • "bypass": true,
  • "reason": "string",
  • "policy": {
    },
  • "mode": "local",
  • "nodes": [
    ]
}

Statistics of the cache

The answers by X-Cache value, the bytes served from the cache and from the origin, the hit ratio, the entries and the sizes per tier, of the cluster (summed) and of every node, per domain, with the most requested objects and those missed the most (docs/11 §11.8). distribution and host narrow them; a host alone selects the distribution serving it.

Authorizations:
(sessioncsrf) sigv4
query Parameters
distribution
string
host
string
top
integer >= 0

Size of the lists of top objects (default 10, at most 100).

Responses

Response samples

Content type
application/json
{
  • "requests": {
    },
  • "bytesCache": 0,
  • "bytesOrigin": 0,
  • "hitRatio": 0,
  • "entries": 0,
  • "memoryBytes": 0,
  • "diskBytes": 0,
  • "hosts": [
    ],
  • "topObjects": [
    ],
  • "topMisses": [
    ],
  • "nodes": [
    ]
}

History of the global purges

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Purge the cache of every distribution

The global purge (all is required; soft marks the entries expired instead of dropping them).

Authorizations:
(sessioncsrf) sigv4
Request Body schema: application/json
required
domain
string

A domain of the distribution; alone, it purges the whole domain.

paths
Array of strings

Exact paths ("/docs/" also drops its index document), or absolute URLs of a domain (their host sets the domain).

Array of objects (KeyPattern)
tags
Array of strings

Cache tags (x-amz-meta-cache-tag, surrogate keys).

all
boolean
soft
boolean

Mark the entries expired instead of dropping them.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "paths": [
    ],
  • "patterns": [
    ],
  • "tags": [
    ],
  • "all": true,
  • "soft": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "request": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "state": "in-progress",
  • "nodes": [
    ]
}

An invalidation, by its id alone

A global purge or an invalidation of any distribution (nexoctl cache purge status).

Authorizations:
(sessioncsrf) sigv4
path Parameters
inv
required
string

Id of the invalidation.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "request": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "state": "in-progress",
  • "nodes": [
    ]
}

Cache settings of a distribution

The defaults of the distribution, the overrides of its domains (an alias, exact or wildcard, or a host a wildcard alias matches) and of its paths (behaviors, the first match wins), its purge webhooks (secrets masked) and the objects warmed on write (docs/11 §11.1). A distribution without settings answers an empty document without ETag.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Responses

Response samples

Content type
application/json
{
  • "distribution": "string",
  • "cache": {
    },
  • "domains": [
    ],
  • "behaviors": [
    ],
  • "webhooks": [
    ],
  • "warmOnWrite": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Replace the cache settings of a distribution

Replaces the whole document (distribution is the id of the path); with If-Match only the version with that ETag (412 otherwise). Every node applies the settings at once and drops the entries whose settings changed. The webhooks sent with masked secrets keep the stored ones.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

header Parameters
If-Match
string

The ETag of the version the change applies to (quoted or not); a different current version answers 412 precondition_failed. Absent or *, the change applies unconditionally.

Request Body schema: application/json
required
distribution
string

The id of the distribution (the one of the path; may be omitted in requests).

required
object (CacheSettings)

The cache settings of a level: whether the cache is on, the policy it starts from (naming one replaces what the more general levels set) and the fields of the policy it overrides.

Array of objects
Array of objects

Overrides per path, the first match wins (no quota, webhooks nor autoInvalidate).

Array of objects (CacheWebhook)
Array of objects (KeyPattern)

The objects written whose path matches one of these patterns are cached at once.

updatedAt
string <date-time>
etag
string

Responses

Request samples

Content type
application/json
{
  • "distribution": "string",
  • "cache": {
    },
  • "domains": [
    ],
  • "behaviors": [
    ],
  • "webhooks": [
    ],
  • "warmOnWrite": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Response samples

Content type
application/json
{
  • "distribution": "string",
  • "cache": {
    },
  • "domains": [
    ],
  • "behaviors": [
    ],
  • "webhooks": [
    ],
  • "warmOnWrite": [
    ],
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "etag": "string"
}

Effective cache policy of a path of a domain

The policy that applies after the inheritance global → distribution → domain → behavior, with the level of each setting (TCC-01).

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

query Parameters
host
string

A domain of the distribution (none for the level of the distribution).

path
string

A path of the distribution (default /).

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "enabledLevel": "default",
  • "policyName": "string",
  • "policyLevel": "default",
  • "policy": {
    },
  • "fields": {
    },
  • "domain": "string",
  • "behavior": 0,
  • "distributionQuota": "string",
  • "domainQuota": "string",
  • "cacheControl": "string",
  • "autoInvalidate": true
}

Warm the cache of a domain

Caches objects before they are requested (docs/11 §11.6): paths, absolute URLs of the domain, every object below a prefix or matching a pattern, with bounded concurrency and bandwidth. In the local mode every node warms its own cache. Returns at once; GET .../warm/{job} follows the progress.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Request Body schema: application/json
required
domain
string

The domain the entries are keyed by (default the first exact alias).

paths
Array of strings
urls
Array of strings

Absolute URLs of the domain.

prefix
string

Every object below this path prefix.

object (KeyPattern)

A pattern of keys or paths: prefix (literal, an empty prefix matches everything), glob (* one segment, ** any number, ?, [abc], {a,b}) or regex (RE2: linear time, no backreference nor lookaround, at most 1024 characters). Keys are matched decoded and normalized (., .., // resolved, Unicode NFC).

concurrency
integer >= 0

Parallel reads (default 4).

string or integer (CacheSize)

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "paths": [
    ],
  • "urls": [
    ],
  • "prefix": "string",
  • "pattern": {
    },
  • "concurrency": 0,
  • "bandwidth": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "request": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "state": "running",
  • "nodes": [
    ]
}

Progress of a warm-up

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

job
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "request": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "state": "running",
  • "nodes": [
    ]
}

Purge webhooks of a distribution

The CDNs and proxies in front of the cluster purged on the invalidations of the distribution, automatic and manual (secrets masked).

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add a purge webhook

An id already used answers 409 already_exists.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Request Body schema: application/json
required
id
required
string
type
required
string
Enum: "cloudflare" "fastly" "akamai" "nginx" "varnish" "generic"
domains
Array of strings

The domains whose invalidations call it (none for every domain not bound to another webhook).

url
string

API base, address of the proxy, or URL template of a generic webhook.

zone
string

Cloudflare zone id, Fastly service id.

token
string
clientToken
string
clientSecret
string
network
string
Enum: "production" "staging"
cpCode
string
method
string
object
body
string

Body template of a generic webhook (Go text/template).

scheme
string
Enum: "http" "https"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "cloudflare",
  • "domains": [
    ],
  • "url": "string",
  • "zone": "string",
  • "token": "string",
  • "clientToken": "string",
  • "clientSecret": "string",
  • "network": "production",
  • "cpCode": "string",
  • "method": "string",
  • "headers": {
    },
  • "body": "string",
  • "scheme": "http"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "type": "cloudflare",
  • "domains": [
    ],
  • "url": "string",
  • "zone": "string",
  • "token": "string",
  • "clientToken": "string",
  • "clientSecret": "string",
  • "network": "production",
  • "cpCode": "string",
  • "method": "string",
  • "headers": {
    },
  • "body": "string",
  • "scheme": "http"
}

Remove a purge webhook

The domains bound to it are unbound.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

webhook
required
string

Id of the purge webhook.

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Call a purge webhook once

A test purge, outside of the queue (the connection test of D-CCH-07); a failed call is reported in the body, not as an error.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

webhook
required
string

Id of the purge webhook.

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "status": 0,
  • "error": "string",
  • "durationMs": 0
}

History of the invalidations of a distribution

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Invalidate cached content of a distribution

Exact paths (or absolute URLs of a domain, which set the domain), prefix, glob or regex patterns of paths, cache tags (surrogate keys), a whole domain (domain alone) or everything (all); soft marks the entries expired (served stale while revalidated) instead of dropping them (docs/11 §11.5). Applied on every node and sent to the purge webhooks of the domains; a node not reached is retried and the state stays in-progress until it applies it.

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

Request Body schema: application/json
required
domain
string

A domain of the distribution; alone, it purges the whole domain.

paths
Array of strings

Exact paths ("/docs/" also drops its index document), or absolute URLs of a domain (their host sets the domain).

Array of objects (KeyPattern)
tags
Array of strings

Cache tags (x-amz-meta-cache-tag, surrogate keys).

all
boolean
soft
boolean

Mark the entries expired instead of dropping them.

Responses

Request samples

Content type
application/json
{
  • "domain": "string",
  • "paths": [
    ],
  • "patterns": [
    ],
  • "tags": [
    ],
  • "all": true,
  • "soft": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "request": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "state": "in-progress",
  • "nodes": [
    ]
}

An invalidation of a distribution

Authorizations:
(sessioncsrf) sigv4
path Parameters
id
required
string

Id of the distribution.

inv
required
string

Id of the invalidation.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "request": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "state": "in-progress",
  • "nodes": [
    ]
}

diagnostics

Runtime profile of the node (pprof)

Collects a profile of the node that serves the request, in the pprof format (gzipped protocol buffer, go tool pprof): cpu, mutex and block sample for seconds (1-120, default 10), heap and goroutine are snapshots. One profile at a time per node (409 conflict). Allowed to root and to the identities with admin:Profiling (the diagnostics policy). A POST: with the console session it needs the CSRF token, like every request with side effects (sampling, sampling rates, the profile slot of the node).

Authorizations:
(sessioncsrf) sigv4
query Parameters
type
string
Default: "cpu"
Enum: "cpu" "heap" "goroutine" "mutex" "block"
seconds
integer [ 1 .. 120 ]

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Speed test of the drives, of the object layer or of the network

Runs on the node that serves the request and removes what it wrote: drive writes then reads files on every local drive; object uploads then downloads objects through the object layer in a temporary bucket (nexo-speedtest-*); net uploads files to a drive of every other node of a cluster over the internode RPC then reads one back (501 out of a cluster). Each phase lasts durationSeconds (at most 60) and writes at most 1 GiB per target; objects and files are at most 64 MiB, the concurrency at most 64. One test at a time per node (409 conflict).

Authorizations:
(sessioncsrf) sigv4
path Parameters
kind
required
string
Enum: "drive" "object" "net"
Request Body schema: application/json
optional
size
integer [ 1 .. 67108864 ]

Size of each file or object (default 4 MiB).

durationSeconds
number [ 0.1 .. 60 ]

Duration of each phase (default 5).

concurrency
integer [ 1 .. 64 ]

Concurrency of the object test and of the reads of the net test (default 8).

Responses

Request samples

Content type
application/json
{
  • "size": 1,
  • "durationSeconds": 0.1,
  • "concurrency": 1
}

Response samples

Content type
application/json
{
  • "kind": "drive",
  • "node": "string",
  • "size": 0,
  • "durationSeconds": 0,
  • "concurrency": 0,
  • "targets": [
    ]
}

monitoring

Live trace of the requests (Server-Sent Events)

Streams one event per S3, Admin API, website or internode request served by the deployment, the nodes of a cluster included (node restricts them), as text/event-stream: event: trace with a TraceEvent, event: dropped with a StreamDropped when the client did not keep up (the server never waits for a slow stream: it drops events and counts them), a : heartbeat comment while idle. The query strings are redacted (signatures, credentials, tokens); headers and bodies are never part of an event. Without type, every type but rpc. A node serves at most 256 live trace streams at once (the streams the peers open for their own subscribers included): beyond them a new one answers 429 too_many_requests.

Authorizations:
(sessioncsrf) sigv4
query Parameters
node
string

Nodes to trace (comma-separated or repeated)

type
string

Request types: s3, admin, web, rpc (comma-separated)

api
string

API names (PutObject, GET /buckets...), comma-separated

bucket
string

Buckets (comma-separated)

status
string

Status codes (404) or classes (5xx), comma-separated

errors
boolean

Only the failed requests (status >= 400)

threshold
string

Only the requests slower than this duration (500ms, 2s)

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Live server logs (Server-Sent Events)

Streams the log entries of the deployment, the nodes of a cluster included, as text/event-stream: event: log with a LogEntry, event: dropped with a StreamDropped, a : heartbeat comment while idle. last first replays up to that many recent entries of each node (at most 10000). Secrets (credentials, signatures, tokens, passwords) are redacted from the entries. A node serves at most 256 live log streams at once (the streams the peers open for their own subscribers included): beyond them a new one answers 429 too_many_requests.

Authorizations:
(sessioncsrf) sigv4
query Parameters
node
string

Nodes (comma-separated or repeated)

level
string
Enum: "debug" "info" "warn" "error" "DEBUG" "INFO" "WARN" "ERROR"

Minimum level

last
integer [ 0 .. 10000 ]

Recent entries to replay first

Responses

Response samples

Content type
application/problem+json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "requestId": "string",
  • "errors": [
    ],
  • "ruleErrors": [
    ],
  • "accessRuleErrors": [
    ]
}

Search the recent audit log

Searches the audit records kept in memory by every node (the most recent ones; the complete log goes to the JSON log and to the audit targets audit_webhook and audit_kafka), newest first. An audit record is produced for every authenticated S3 and Admin API request.

Authorizations:
(sessioncsrf) sigv4
query Parameters
node
string

Nodes (comma-separated or repeated)

api
string

API name (PutObject, GET /buckets...)

bucket
string
user
string

Access key or parent user

type
string
Enum: "s3" "admin"

Request type

status
string

Status codes (404) or classes (5xx), comma-separated

errors
boolean

Only the failed requests (status >= 400)

since
string <date-time>
until
string <date-time>
requestId
string
limit
integer [ 0 .. 1000 ]

At most this many records (default 100, at most 1000)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

The series of the metrics of the console

The series kept by every node in memory (one point every 10 seconds for 24 hours) for the charts of the console. Allowed with admin:Prometheus or admin:ServerInfo (either one).

Authorizations:
(sessioncsrf) sigv4

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

The points of a series, per node and for the cluster

The points of metric from end - range to end every step, for every node (or those of node) and aggregated for the cluster; a point without sample (node down, older than the buffer) is null. Allowed with admin:Prometheus or admin:ServerInfo (either one).

Authorizations:
(sessioncsrf) sigv4
query Parameters
metric
required
string

Name of the series (GET /metrics)

range
string

Span of the points (default 1h, at most 24h)

step
string

Distance between two points (multiple of 10s; default keeps at most 360 points)

end
string <date-time>

End of the range (default now)

node
string

Nodes (comma-separated or repeated)

Responses

Response samples

Content type
application/json
{
  • "metric": {
    },
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "stepSeconds": 0,
  • "nodes": [
    ],
  • "cluster": [
    ]
}