# Storage

# Buckets

## Create Bucket

`client.Storage.Buckets.New(ctx, body) (*Operation, error)`

**post** `/v1/storage/buckets`

Create a Bucket. The Bucket is created asynchronously: follow the returned operation until it is done.

### Parameters

- `body BucketNewParams`

  - `Name param.Field[string]`

    Name of the Bucket, used to address it over S3. It must be 3 to 63
    characters of lowercase letters, digits, dots and hyphens, start and end
    with a letter or digit, not contain two adjacent dots and not be formatted
    as an IP address. "admin" and "ops-api" are reserved. The name cannot be
    changed once the Bucket is created.

  - `ProjectID param.Field[string]`

    Project ID the Bucket belongs to.

  - `Region param.Field[RegionName]`

    Region the resource is in.

  - `Tags param.Field[[]string]`

    Tags to attach to the Bucket.

### Returns

- `type Operation struct{…}`

  Operation details.

  - `ID string`

    Unique identifier for the Operation.

  - `CreatedAt Time`

    When the Operation was created.

  - `Details OperationDetails`

    Structured details about what an operation is changing.

    - `Changes OperationChanges`

      Map of changed field names to their from/to diffs. Keys depend on the parent operation's kind+type.

      - `From OperationFieldDiffFromUnion`

        Previous value.

        - `string`

        - `float64`

        - `bool`

        - `type OperationFieldDiffFromArray []string`

      - `To OperationFieldDiffToUnion`

        New value.

        - `string`

        - `float64`

        - `bool`

        - `type OperationFieldDiffToArray []string`

  - `Kind OperationKind`

    Kind of Operation.

    - `const OperationKindVM OperationKind = "vm"`

    - `const OperationKindVolume OperationKind = "volume"`

    - `const OperationKindVPC OperationKind = "vpc"`

    - `const OperationKindFirewallRule OperationKind = "firewall_rule"`

    - `const OperationKindNKSCluster OperationKind = "nks_cluster"`

    - `const OperationKindNKSNodePool OperationKind = "nks_node_pool"`

    - `const OperationKindSandboxCluster OperationKind = "sandbox_cluster"`

    - `const OperationKindBucket OperationKind = "bucket"`

  - `ProjectID string`

    Project ID the Operation belongs to.

  - `ResourceID string`

    ID of the resource that the Operation is acting on.

  - `Status OperationStatus`

    Status of the Operation.

    - `const OperationStatusPending OperationStatus = "pending"`

    - `const OperationStatusRunning OperationStatus = "running"`

    - `const OperationStatusDone OperationStatus = "done"`

    - `const OperationStatusFailed OperationStatus = "failed"`

    - `const OperationStatusUnknown OperationStatus = "unknown"`

  - `Type OperationType`

    Type of Operation.

    - `const OperationTypeCreate OperationType = "create"`

    - `const OperationTypeUpdate OperationType = "update"`

    - `const OperationTypeDelete OperationType = "delete"`

    - `const OperationTypeRestart OperationType = "restart"`

  - `UpdatedAt Time`

    When the Operation was updated.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
  "github.com/nirvana-labs/nirvana-go/shared"
  "github.com/nirvana-labs/nirvana-go/storage"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  operation, err := client.Storage.Buckets.New(context.TODO(), storage.BucketNewParams{
    Name: "my-bucket",
    ProjectID: "123e4567-e89b-12d3-a456-426614174000",
    Region: shared.RegionNameUsSva2,
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", operation.ID)
}
```

#### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2025-01-01T00:00:00Z",
  "details": {
    "changes": {
      "foo": {
        "from": "string",
        "to": "string"
      }
    }
  },
  "kind": "vm",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "resource_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "type": "create",
  "updated_at": "2025-01-01T00:00:00Z"
}
```

## Get Bucket Details

`client.Storage.Buckets.Get(ctx, bucketID) (*Bucket, error)`

**get** `/v1/storage/buckets/{bucket_id}`

Get details about a Bucket

### Parameters

- `bucketID string`

### Returns

- `type Bucket struct{…}`

  Bucket details.

  - `ID string`

    Unique identifier for the Bucket.

  - `CreatedAt Time`

    When the Bucket was created.

  - `Endpoint string`

    S3 endpoint of the Bucket's region. Point S3 clients at it, with an Object
    Storage Key of the same project and region.

  - `Name string`

    Name of the Bucket, used to address it over S3.

  - `ObjectCount int64`

    Number of objects in the Bucket. Updated periodically, so it can lag behind
    recent writes.

  - `ProjectID string`

    Project ID the Bucket belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `SigningRegion string`

    Region S3 clients must sign their requests for (the SigV4 region). Configure
    it as the region of any S3 client or SDK used with the Bucket.

  - `SizeBytes int64`

    Total size of the objects in the Bucket, in bytes. Updated periodically,
    so it can lag behind recent writes.

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `Tags []string`

    Tags attached to the Bucket.

  - `UpdatedAt Time`

    When the Bucket was updated.

  - `URL string`

    Path-style URL of the Bucket.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  bucket, err := client.Storage.Buckets.Get(context.TODO(), "bucket_id")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", bucket.ID)
}
```

#### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2025-01-01T00:00:00Z",
  "endpoint": "https://s3.sva2.nirvanacloud.io",
  "name": "my-bucket",
  "object_count": 1024,
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "region": "us-sva-2",
  "signing_region": "us-east-1",
  "size_bytes": 1073741824,
  "status": "ready",
  "tags": [
    "production",
    "ethereum"
  ],
  "updated_at": "2025-01-01T00:00:00Z",
  "url": "https://s3.sva2.nirvanacloud.io/my-bucket"
}
```

## Update Bucket

`client.Storage.Buckets.Update(ctx, bucketID, body) (*Bucket, error)`

**patch** `/v1/storage/buckets/{bucket_id}`

Update a Bucket's tags. A Bucket's name is its S3 name and cannot be changed.

### Parameters

- `bucketID string`

- `body BucketUpdateParams`

  - `Tags param.Field[[]string]`

    Tags to attach to the Bucket.

### Returns

- `type Bucket struct{…}`

  Bucket details.

  - `ID string`

    Unique identifier for the Bucket.

  - `CreatedAt Time`

    When the Bucket was created.

  - `Endpoint string`

    S3 endpoint of the Bucket's region. Point S3 clients at it, with an Object
    Storage Key of the same project and region.

  - `Name string`

    Name of the Bucket, used to address it over S3.

  - `ObjectCount int64`

    Number of objects in the Bucket. Updated periodically, so it can lag behind
    recent writes.

  - `ProjectID string`

    Project ID the Bucket belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `SigningRegion string`

    Region S3 clients must sign their requests for (the SigV4 region). Configure
    it as the region of any S3 client or SDK used with the Bucket.

  - `SizeBytes int64`

    Total size of the objects in the Bucket, in bytes. Updated periodically,
    so it can lag behind recent writes.

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `Tags []string`

    Tags attached to the Bucket.

  - `UpdatedAt Time`

    When the Bucket was updated.

  - `URL string`

    Path-style URL of the Bucket.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
  "github.com/nirvana-labs/nirvana-go/storage"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  bucket, err := client.Storage.Buckets.Update(
    context.TODO(),
    "bucket_id",
    storage.BucketUpdateParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", bucket.ID)
}
```

#### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2025-01-01T00:00:00Z",
  "endpoint": "https://s3.sva2.nirvanacloud.io",
  "name": "my-bucket",
  "object_count": 1024,
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "region": "us-sva-2",
  "signing_region": "us-east-1",
  "size_bytes": 1073741824,
  "status": "ready",
  "tags": [
    "production",
    "ethereum"
  ],
  "updated_at": "2025-01-01T00:00:00Z",
  "url": "https://s3.sva2.nirvanacloud.io/my-bucket"
}
```

## Delete Bucket

`client.Storage.Buckets.Delete(ctx, bucketID, body) (*Operation, error)`

**delete** `/v1/storage/buckets/{bucket_id}`

Delete a Bucket. The Bucket is deleted asynchronously: follow the returned operation until it is done. A Bucket that still holds objects is only deleted with force: without it, the request is refused with 409 BUCKET_NOT_EMPTY and no operation is started, and objects written after the request is accepted fail the operation instead.

### Parameters

- `bucketID string`

- `body BucketDeleteParams`

  - `Force param.Field[bool]`

    Permanently delete every object in the Bucket, including all versions, before deleting it. Without it, deleting a Bucket that holds objects fails.

### Returns

- `type Operation struct{…}`

  Operation details.

  - `ID string`

    Unique identifier for the Operation.

  - `CreatedAt Time`

    When the Operation was created.

  - `Details OperationDetails`

    Structured details about what an operation is changing.

    - `Changes OperationChanges`

      Map of changed field names to their from/to diffs. Keys depend on the parent operation's kind+type.

      - `From OperationFieldDiffFromUnion`

        Previous value.

        - `string`

        - `float64`

        - `bool`

        - `type OperationFieldDiffFromArray []string`

      - `To OperationFieldDiffToUnion`

        New value.

        - `string`

        - `float64`

        - `bool`

        - `type OperationFieldDiffToArray []string`

  - `Kind OperationKind`

    Kind of Operation.

    - `const OperationKindVM OperationKind = "vm"`

    - `const OperationKindVolume OperationKind = "volume"`

    - `const OperationKindVPC OperationKind = "vpc"`

    - `const OperationKindFirewallRule OperationKind = "firewall_rule"`

    - `const OperationKindNKSCluster OperationKind = "nks_cluster"`

    - `const OperationKindNKSNodePool OperationKind = "nks_node_pool"`

    - `const OperationKindSandboxCluster OperationKind = "sandbox_cluster"`

    - `const OperationKindBucket OperationKind = "bucket"`

  - `ProjectID string`

    Project ID the Operation belongs to.

  - `ResourceID string`

    ID of the resource that the Operation is acting on.

  - `Status OperationStatus`

    Status of the Operation.

    - `const OperationStatusPending OperationStatus = "pending"`

    - `const OperationStatusRunning OperationStatus = "running"`

    - `const OperationStatusDone OperationStatus = "done"`

    - `const OperationStatusFailed OperationStatus = "failed"`

    - `const OperationStatusUnknown OperationStatus = "unknown"`

  - `Type OperationType`

    Type of Operation.

    - `const OperationTypeCreate OperationType = "create"`

    - `const OperationTypeUpdate OperationType = "update"`

    - `const OperationTypeDelete OperationType = "delete"`

    - `const OperationTypeRestart OperationType = "restart"`

  - `UpdatedAt Time`

    When the Operation was updated.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
  "github.com/nirvana-labs/nirvana-go/storage"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  operation, err := client.Storage.Buckets.Delete(
    context.TODO(),
    "bucket_id",
    storage.BucketDeleteParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", operation.ID)
}
```

#### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2025-01-01T00:00:00Z",
  "details": {
    "changes": {
      "foo": {
        "from": "string",
        "to": "string"
      }
    }
  },
  "kind": "vm",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "resource_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "type": "create",
  "updated_at": "2025-01-01T00:00:00Z"
}
```

## List Buckets

`client.Storage.Buckets.List(ctx, query) (*Cursor[Bucket], error)`

**get** `/v1/storage/buckets`

List all Buckets

### Parameters

- `query BucketListParams`

  - `ProjectID param.Field[string]`

    Project ID of resources to request

  - `Cursor param.Field[string]`

    Pagination cursor returned by a previous request. Only valid for the same filters and sort order.

  - `Limit param.Field[int64]`

    Maximum number of items to return

  - `Name param.Field[string]`

    Filter by a case-insensitive substring of the Bucket name

  - `Region param.Field[string]`

    Filter by region

  - `Sort param.Field[string]`

    Comma-separated sort terms in precedence order, each field:asc or field:desc. Fields: created_at, updated_at, name, status, size_bytes, object_count

  - `Status param.Field[BucketListParamsStatus]`

    Filter by Bucket status

    - `const BucketListParamsStatusPending BucketListParamsStatus = "pending"`

    - `const BucketListParamsStatusCreating BucketListParamsStatus = "creating"`

    - `const BucketListParamsStatusUpdating BucketListParamsStatus = "updating"`

    - `const BucketListParamsStatusReady BucketListParamsStatus = "ready"`

    - `const BucketListParamsStatusDeleting BucketListParamsStatus = "deleting"`

    - `const BucketListParamsStatusError BucketListParamsStatus = "error"`

  - `Tags param.Field[[]string]`

    Filter by tags. Repeat the parameter to require several tags; a Bucket must carry all of them.

### Returns

- `type Bucket struct{…}`

  Bucket details.

  - `ID string`

    Unique identifier for the Bucket.

  - `CreatedAt Time`

    When the Bucket was created.

  - `Endpoint string`

    S3 endpoint of the Bucket's region. Point S3 clients at it, with an Object
    Storage Key of the same project and region.

  - `Name string`

    Name of the Bucket, used to address it over S3.

  - `ObjectCount int64`

    Number of objects in the Bucket. Updated periodically, so it can lag behind
    recent writes.

  - `ProjectID string`

    Project ID the Bucket belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `SigningRegion string`

    Region S3 clients must sign their requests for (the SigV4 region). Configure
    it as the region of any S3 client or SDK used with the Bucket.

  - `SizeBytes int64`

    Total size of the objects in the Bucket, in bytes. Updated periodically,
    so it can lag behind recent writes.

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `Tags []string`

    Tags attached to the Bucket.

  - `UpdatedAt Time`

    When the Bucket was updated.

  - `URL string`

    Path-style URL of the Bucket.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
  "github.com/nirvana-labs/nirvana-go/storage"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.Storage.Buckets.List(context.TODO(), storage.BucketListParams{
    ProjectID: "project_id",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

#### Response

```json
{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2025-01-01T00:00:00Z",
      "endpoint": "https://s3.sva2.nirvanacloud.io",
      "name": "my-bucket",
      "object_count": 1024,
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "region": "us-sva-2",
      "signing_region": "us-east-1",
      "size_bytes": 1073741824,
      "status": "ready",
      "tags": [
        "production",
        "ethereum"
      ],
      "updated_at": "2025-01-01T00:00:00Z",
      "url": "https://s3.sva2.nirvanacloud.io/my-bucket"
    }
  ],
  "pagination": {
    "next_cursor": "RhwniMT4B74siYZcPF8TnCdGI1l9rpPvg",
    "previous_cursor": "ARhwnmi1hA7wEbHbMjdYQlOB_ZusP4fYvw",
    "total_count": 125
  }
}
```

## Domain Types

### Bucket

- `type Bucket struct{…}`

  Bucket details.

  - `ID string`

    Unique identifier for the Bucket.

  - `CreatedAt Time`

    When the Bucket was created.

  - `Endpoint string`

    S3 endpoint of the Bucket's region. Point S3 clients at it, with an Object
    Storage Key of the same project and region.

  - `Name string`

    Name of the Bucket, used to address it over S3.

  - `ObjectCount int64`

    Number of objects in the Bucket. Updated periodically, so it can lag behind
    recent writes.

  - `ProjectID string`

    Project ID the Bucket belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `SigningRegion string`

    Region S3 clients must sign their requests for (the SigV4 region). Configure
    it as the region of any S3 client or SDK used with the Bucket.

  - `SizeBytes int64`

    Total size of the objects in the Bucket, in bytes. Updated periodically,
    so it can lag behind recent writes.

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `Tags []string`

    Tags attached to the Bucket.

  - `UpdatedAt Time`

    When the Bucket was updated.

  - `URL string`

    Path-style URL of the Bucket.

### Bucket List

- `type BucketList struct{…}`

  - `Items []Bucket`

    - `ID string`

      Unique identifier for the Bucket.

    - `CreatedAt Time`

      When the Bucket was created.

    - `Endpoint string`

      S3 endpoint of the Bucket's region. Point S3 clients at it, with an Object
      Storage Key of the same project and region.

    - `Name string`

      Name of the Bucket, used to address it over S3.

    - `ObjectCount int64`

      Number of objects in the Bucket. Updated periodically, so it can lag behind
      recent writes.

    - `ProjectID string`

      Project ID the Bucket belongs to.

    - `Region RegionName`

      Region the resource is in.

      - `const RegionNameUsSva2 RegionName = "us-sva-2"`

      - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

    - `SigningRegion string`

      Region S3 clients must sign their requests for (the SigV4 region). Configure
      it as the region of any S3 client or SDK used with the Bucket.

    - `SizeBytes int64`

      Total size of the objects in the Bucket, in bytes. Updated periodically,
      so it can lag behind recent writes.

    - `Status ResourceStatus`

      Status of the resource.

      - `const ResourceStatusPending ResourceStatus = "pending"`

      - `const ResourceStatusCreating ResourceStatus = "creating"`

      - `const ResourceStatusUpdating ResourceStatus = "updating"`

      - `const ResourceStatusReady ResourceStatus = "ready"`

      - `const ResourceStatusDeleting ResourceStatus = "deleting"`

      - `const ResourceStatusDeleted ResourceStatus = "deleted"`

      - `const ResourceStatusError ResourceStatus = "error"`

      - `const ResourceStatusSuspended ResourceStatus = "suspended"`

    - `Tags []string`

      Tags attached to the Bucket.

    - `UpdatedAt Time`

      When the Bucket was updated.

    - `URL string`

      Path-style URL of the Bucket.

  - `Pagination Pagination`

    Pagination response details.

    - `NextCursor string`

    - `PreviousCursor string`

    - `TotalCount int64`

# Availability

## Check Create Bucket Availability

`client.Storage.Buckets.Availability.New(ctx, body) error`

**post** `/v1/storage/buckets/availability`

Check if a Bucket can be created

### Parameters

- `body BucketAvailabilityNewParams`

  - `Name param.Field[string]`

    Name of the Bucket, used to address it over S3. It must be 3 to 63
    characters of lowercase letters, digits, dots and hyphens, start and end
    with a letter or digit, not contain two adjacent dots and not be formatted
    as an IP address. "admin" and "ops-api" are reserved. The name cannot be
    changed once the Bucket is created.

  - `ProjectID param.Field[string]`

    Project ID the Bucket belongs to.

  - `Region param.Field[RegionName]`

    Region the resource is in.

  - `Tags param.Field[[]string]`

    Tags to attach to the Bucket.

### Example

```go
package main

import (
  "context"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
  "github.com/nirvana-labs/nirvana-go/shared"
  "github.com/nirvana-labs/nirvana-go/storage"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  err := client.Storage.Buckets.Availability.New(context.TODO(), storage.BucketAvailabilityNewParams{
    Name: "my-bucket",
    ProjectID: "123e4567-e89b-12d3-a456-426614174000",
    Region: shared.RegionNameUsSva2,
  })
  if err != nil {
    panic(err.Error())
  }
}
```

# Cost

## Estimate Bucket Create Cost

`client.Storage.Buckets.Cost.New(ctx, body) (*CostQuote, error)`

**post** `/v1/storage/buckets/cost`

Return a priced monthly cost quote for the proposed Bucket storing size_gb of data. A Bucket is charged per GB it stores, prorated by the hour.

### Parameters

- `body BucketCostNewParams`

  - `Name param.Field[string]`

    Name of the Bucket, used to address it over S3. It must be 3 to 63
    characters of lowercase letters, digits, dots and hyphens, start and end
    with a letter or digit, not contain two adjacent dots and not be formatted
    as an IP address. "admin" and "ops-api" are reserved. The name cannot be
    changed once the Bucket is created.

  - `ProjectID param.Field[string]`

    Project ID the Bucket belongs to.

  - `Region param.Field[RegionName]`

    Region the resource is in.

  - `SizeGB param.Field[int64]`

    Amount of data to price the Bucket at storing, in GB (1 GB = 10^9 bytes).
    A Bucket is charged for what it stores, so a quote without it is empty.

  - `Tags param.Field[[]string]`

    Tags to attach to the Bucket.

### Returns

- `type CostQuote struct{…}`

  Cost quote returned by POST /cost. current_summary and updated_summary hold the org billing summary now and with this resource; omitted when the caller cannot view billing.

  - `Currency string`

    Currency the quote is denominated in. Always "USD" in v1.

  - `MonthlyTotal string`

    Arbitrary-precision decimal serialized as a string (e.g. "58.40").

  - `PricedAt Time`

    Timestamp the quote was priced at.

  - `UsageDimensions []CostQuoteUsageDimension`

    Priced rows, one per usage dimension emitted by the resource.

    - `Dimension string`

      Usage dimension being priced (e.g. compute_vcpu, storage_abs_gb).

    - `DimensionDisplayName string`

      User-facing label for the dimension (e.g. "vCPU (hours)").

    - `MonthlyAmount string`

      Arbitrary-precision decimal serialized as a string (e.g. "58.40").

    - `Quantity int64`

      Quantity of the dimension being priced.

    - `UnitPrice string`

      Arbitrary-precision decimal serialized as a string (e.g. "58.40").

  - `CurrentSummary OrganizationBillingSummary`

    Forward-looking billing summary for an organization. All costs are run-rate projections from the organization's current active usage ("≈ $X/mo at current usage").

    - `DailyCost string`

      Arbitrary-precision decimal serialized as a string (e.g. "58.40").

    - `EffectiveBalance string`

      Arbitrary-precision decimal serialized as a string (e.g. "58.40").

    - `MonthlyCost string`

      Arbitrary-precision decimal serialized as a string (e.g. "58.40").

    - `RechargeThresholdDays string`

      Arbitrary-precision decimal serialized as a string (e.g. "58.40").

    - `EstimatedNextChargeAt Time`

      Projected date the balance reaches the recharge threshold at the current run-rate. Null when there is no active usage (never charges).

    - `RunwayMonths string`

      Arbitrary-precision decimal serialized as a string (e.g. "58.40").

  - `UpdatedSummary OrganizationBillingSummary`

    Forward-looking billing summary for an organization. All costs are run-rate projections from the organization's current active usage ("≈ $X/mo at current usage").

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
  "github.com/nirvana-labs/nirvana-go/shared"
  "github.com/nirvana-labs/nirvana-go/storage"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  costQuote, err := client.Storage.Buckets.Cost.New(context.TODO(), storage.BucketCostNewParams{
    Name: "my-bucket",
    ProjectID: "123e4567-e89b-12d3-a456-426614174000",
    Region: shared.RegionNameUsSva2,
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", costQuote.Currency)
}
```

#### Response

```json
{
  "currency": "USD",
  "monthly_total": "-69125",
  "priced_at": "2025-01-01T00:00:00Z",
  "usage_dimensions": [
    {
      "dimension": "compute_vcpu",
      "dimension_display_name": "vCPU (hours)",
      "monthly_amount": "-69125",
      "quantity": 4,
      "unit_price": "-69125"
    }
  ],
  "current_summary": {
    "daily_cost": "-69125",
    "effective_balance": "-69125",
    "monthly_cost": "-69125",
    "recharge_threshold_days": "-69125",
    "estimated_next_charge_at": "2025-01-01T00:00:00Z",
    "runway_months": "-69125"
  },
  "updated_summary": {
    "daily_cost": "-69125",
    "effective_balance": "-69125",
    "monthly_cost": "-69125",
    "recharge_threshold_days": "-69125",
    "estimated_next_charge_at": "2025-01-01T00:00:00Z",
    "runway_months": "-69125"
  }
}
```

# Keys

## Create Object Storage Key

`client.Storage.Keys.New(ctx, body) (*ObjectStorageKeyWithSecret, error)`

**post** `/v1/storage/keys`

Create an S3 access key for a project's Buckets in a region. The response is the only one that includes the secret access key.

### Parameters

- `body KeyNewParams`

  - `Name param.Field[string]`

    Name of the Object Storage Key.

  - `ProjectID param.Field[string]`

    Project ID the Object Storage Key belongs to. The key can access the
    project's Buckets in its region.

  - `Region param.Field[RegionName]`

    Region the resource is in.

### Returns

- `type ObjectStorageKeyWithSecret struct{…}`

  Object Storage Key details, including the secret access key. Returned only when the key is created.

  - `ID string`

    Unique identifier for the Object Storage Key.

  - `AccessKey string`

    S3 access key ID.

  - `CreatedAt Time`

    When the Object Storage Key was created.

  - `Name string`

    Name of the Object Storage Key.

  - `ProjectID string`

    Project ID the Object Storage Key belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `Secret string`

    S3 secret access key. It is only returned here and cannot be retrieved
    again: store it securely, or delete the key and create a new one if it is
    lost.

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `UpdatedAt Time`

    When the Object Storage Key was updated.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
  "github.com/nirvana-labs/nirvana-go/shared"
  "github.com/nirvana-labs/nirvana-go/storage"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  objectStorageKeyWithSecret, err := client.Storage.Keys.New(context.TODO(), storage.KeyNewParams{
    Name: "ci-uploads",
    ProjectID: "123e4567-e89b-12d3-a456-426614174000",
    Region: shared.RegionNameUsSva2,
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", objectStorageKeyWithSecret.ID)
}
```

#### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "access_key": "0555B35654AD1656D804",
  "created_at": "2025-01-01T00:00:00Z",
  "name": "ci-uploads",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "region": "us-sva-2",
  "secret": "h7GhxuBLTrlhVUyxSPUKUV8r/2EI4ngqJxD7iBdBYLhwluN30JaT3Q==",
  "status": "ready",
  "updated_at": "2025-01-01T00:00:00Z"
}
```

## Get Object Storage Key Details

`client.Storage.Keys.Get(ctx, keyID) (*ObjectStorageKey, error)`

**get** `/v1/storage/keys/{key_id}`

Get details about an Object Storage Key. The secret access key is not included.

### Parameters

- `keyID string`

### Returns

- `type ObjectStorageKey struct{…}`

  Object Storage Key details. The secret access key is only returned when the key is created.

  - `ID string`

    Unique identifier for the Object Storage Key.

  - `AccessKey string`

    S3 access key ID.

  - `CreatedAt Time`

    When the Object Storage Key was created.

  - `Name string`

    Name of the Object Storage Key.

  - `ProjectID string`

    Project ID the Object Storage Key belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `UpdatedAt Time`

    When the Object Storage Key was updated.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  objectStorageKey, err := client.Storage.Keys.Get(context.TODO(), "key_id")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", objectStorageKey.ID)
}
```

#### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "access_key": "0555B35654AD1656D804",
  "created_at": "2025-01-01T00:00:00Z",
  "name": "ci-uploads",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "region": "us-sva-2",
  "status": "ready",
  "updated_at": "2025-01-01T00:00:00Z"
}
```

## Update Object Storage Key

`client.Storage.Keys.Update(ctx, keyID, body) (*ObjectStorageKey, error)`

**patch** `/v1/storage/keys/{key_id}`

Rename an Object Storage Key. Its access key and secret do not change.

### Parameters

- `keyID string`

- `body KeyUpdateParams`

  - `Name param.Field[string]`

    Name of the Object Storage Key.

### Returns

- `type ObjectStorageKey struct{…}`

  Object Storage Key details. The secret access key is only returned when the key is created.

  - `ID string`

    Unique identifier for the Object Storage Key.

  - `AccessKey string`

    S3 access key ID.

  - `CreatedAt Time`

    When the Object Storage Key was created.

  - `Name string`

    Name of the Object Storage Key.

  - `ProjectID string`

    Project ID the Object Storage Key belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `UpdatedAt Time`

    When the Object Storage Key was updated.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
  "github.com/nirvana-labs/nirvana-go/storage"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  objectStorageKey, err := client.Storage.Keys.Update(
    context.TODO(),
    "key_id",
    storage.KeyUpdateParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", objectStorageKey.ID)
}
```

#### Response

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "access_key": "0555B35654AD1656D804",
  "created_at": "2025-01-01T00:00:00Z",
  "name": "ci-uploads",
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "region": "us-sva-2",
  "status": "ready",
  "updated_at": "2025-01-01T00:00:00Z"
}
```

## Delete Object Storage Key

`client.Storage.Keys.Delete(ctx, keyID) error`

**delete** `/v1/storage/keys/{key_id}`

Delete an Object Storage Key. It stops working immediately.

### Parameters

- `keyID string`

### Example

```go
package main

import (
  "context"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  err := client.Storage.Keys.Delete(context.TODO(), "key_id")
  if err != nil {
    panic(err.Error())
  }
}
```

## List Object Storage Keys

`client.Storage.Keys.List(ctx, query) (*Cursor[ObjectStorageKey], error)`

**get** `/v1/storage/keys`

List all Object Storage Keys. Secret access keys are not included.

### Parameters

- `query KeyListParams`

  - `ProjectID param.Field[string]`

    Project ID of resources to request

  - `Cursor param.Field[string]`

    Pagination cursor returned by a previous request. Only valid for the same filters and sort order.

  - `Limit param.Field[int64]`

    Maximum number of items to return

  - `Name param.Field[string]`

    Filter by a case-insensitive substring of the Object Storage Key name

  - `Region param.Field[string]`

    Filter by region

  - `Sort param.Field[string]`

    Comma-separated sort terms in precedence order, each field:asc or field:desc. Fields: created_at, updated_at, name

### Returns

- `type ObjectStorageKey struct{…}`

  Object Storage Key details. The secret access key is only returned when the key is created.

  - `ID string`

    Unique identifier for the Object Storage Key.

  - `AccessKey string`

    S3 access key ID.

  - `CreatedAt Time`

    When the Object Storage Key was created.

  - `Name string`

    Name of the Object Storage Key.

  - `ProjectID string`

    Project ID the Object Storage Key belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `UpdatedAt Time`

    When the Object Storage Key was updated.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/nirvana-labs/nirvana-go"
  "github.com/nirvana-labs/nirvana-go/option"
  "github.com/nirvana-labs/nirvana-go/storage"
)

func main() {
  client := nirvana.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.Storage.Keys.List(context.TODO(), storage.KeyListParams{
    ProjectID: "project_id",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

#### Response

```json
{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "access_key": "0555B35654AD1656D804",
      "created_at": "2025-01-01T00:00:00Z",
      "name": "ci-uploads",
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "region": "us-sva-2",
      "status": "ready",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "RhwniMT4B74siYZcPF8TnCdGI1l9rpPvg",
    "previous_cursor": "ARhwnmi1hA7wEbHbMjdYQlOB_ZusP4fYvw",
    "total_count": 125
  }
}
```

## Domain Types

### Object Storage Key

- `type ObjectStorageKey struct{…}`

  Object Storage Key details. The secret access key is only returned when the key is created.

  - `ID string`

    Unique identifier for the Object Storage Key.

  - `AccessKey string`

    S3 access key ID.

  - `CreatedAt Time`

    When the Object Storage Key was created.

  - `Name string`

    Name of the Object Storage Key.

  - `ProjectID string`

    Project ID the Object Storage Key belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `UpdatedAt Time`

    When the Object Storage Key was updated.

### Object Storage Key List

- `type ObjectStorageKeyList struct{…}`

  - `Items []ObjectStorageKey`

    - `ID string`

      Unique identifier for the Object Storage Key.

    - `AccessKey string`

      S3 access key ID.

    - `CreatedAt Time`

      When the Object Storage Key was created.

    - `Name string`

      Name of the Object Storage Key.

    - `ProjectID string`

      Project ID the Object Storage Key belongs to.

    - `Region RegionName`

      Region the resource is in.

      - `const RegionNameUsSva2 RegionName = "us-sva-2"`

      - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

    - `Status ResourceStatus`

      Status of the resource.

      - `const ResourceStatusPending ResourceStatus = "pending"`

      - `const ResourceStatusCreating ResourceStatus = "creating"`

      - `const ResourceStatusUpdating ResourceStatus = "updating"`

      - `const ResourceStatusReady ResourceStatus = "ready"`

      - `const ResourceStatusDeleting ResourceStatus = "deleting"`

      - `const ResourceStatusDeleted ResourceStatus = "deleted"`

      - `const ResourceStatusError ResourceStatus = "error"`

      - `const ResourceStatusSuspended ResourceStatus = "suspended"`

    - `UpdatedAt Time`

      When the Object Storage Key was updated.

  - `Pagination Pagination`

    Pagination response details.

    - `NextCursor string`

    - `PreviousCursor string`

    - `TotalCount int64`

### Object Storage Key With Secret

- `type ObjectStorageKeyWithSecret struct{…}`

  Object Storage Key details, including the secret access key. Returned only when the key is created.

  - `ID string`

    Unique identifier for the Object Storage Key.

  - `AccessKey string`

    S3 access key ID.

  - `CreatedAt Time`

    When the Object Storage Key was created.

  - `Name string`

    Name of the Object Storage Key.

  - `ProjectID string`

    Project ID the Object Storage Key belongs to.

  - `Region RegionName`

    Region the resource is in.

    - `const RegionNameUsSva2 RegionName = "us-sva-2"`

    - `const RegionNameUsWdc1 RegionName = "us-wdc-1"`

  - `Secret string`

    S3 secret access key. It is only returned here and cannot be retrieved
    again: store it securely, or delete the key and create a new one if it is
    lost.

  - `Status ResourceStatus`

    Status of the resource.

    - `const ResourceStatusPending ResourceStatus = "pending"`

    - `const ResourceStatusCreating ResourceStatus = "creating"`

    - `const ResourceStatusUpdating ResourceStatus = "updating"`

    - `const ResourceStatusReady ResourceStatus = "ready"`

    - `const ResourceStatusDeleting ResourceStatus = "deleting"`

    - `const ResourceStatusDeleted ResourceStatus = "deleted"`

    - `const ResourceStatusError ResourceStatus = "error"`

    - `const ResourceStatusSuspended ResourceStatus = "suspended"`

  - `UpdatedAt Time`

    When the Object Storage Key was updated.
