Storage API

The Lineserve Storage API provides S3-compatible object storage and block storage management for your applications.

Base URL

https://api.lineserve.com/v1

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Object Storage

Buckets

List Buckets

Get a list of all storage buckets in your account.

Endpoint: GET /storage/buckets

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/buckets

Example Response:

{
  "buckets": [
    {
      "name": "my-app-storage",
      "region": "nairobi",
      "created_at": "2024-01-15T10:30:00Z",
      "size": 1073741824,
      "object_count": 150,
      "public": false,
      "versioning": true,
      "encryption": "AES256"
    }
  ]
}

Create Bucket

Create a new storage bucket.

Endpoint: POST /storage/buckets

Parameters:

name (required): Bucket name (must be globally unique)
region (required): Storage region
public (optional): Make bucket publicly readable
versioning (optional): Enable object versioning
encryption (optional): Encryption type (AES256, KMS)

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-bucket",
    "region": "nairobi",
    "public": false,
    "versioning": true,
    "encryption": "AES256"
  }' \
  https://api.lineserve.com/v1/storage/buckets

Get Bucket Details

Get detailed information about a specific bucket.

Endpoint: GET /storage/buckets/{bucket_name}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage

Delete Bucket

Delete an empty storage bucket.

Endpoint: DELETE /storage/buckets/{bucket_name}

Example Request:

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/buckets/my-old-bucket

Objects

List Objects

List objects in a bucket with optional filtering.

Endpoint: GET /storage/buckets/{bucket_name}/objects

Parameters:

prefix (optional): Filter by object key prefix
delimiter (optional): Delimiter for grouping
max_keys (optional): Maximum number of keys to return
marker (optional): Start listing after this key

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/storage/buckets/my-app-storage/objects?prefix=images/&max_keys=100"

Example Response:

{
  "objects": [
    {
      "key": "images/photo1.jpg",
      "size": 2048576,
      "last_modified": "2024-01-15T10:30:00Z",
      "etag": "d41d8cd98f00b204e9800998ecf8427e",
      "storage_class": "STANDARD",
      "content_type": "image/jpeg"
    }
  ],
  "is_truncated": false,
  "next_marker": null
}

Upload Object

Upload a file to object storage.

Endpoint: PUT /storage/buckets/{bucket_name}/objects/{object_key}

Headers:

Content-Type: MIME type of the object
Content-Length: Size of the object
x-amz-acl (optional): Access control list

Example Request:

curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/objects/images/photo.jpg

Download Object

Download an object from storage.

Endpoint: GET /storage/buckets/{bucket_name}/objects/{object_key}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/objects/images/photo.jpg \
  -o downloaded-photo.jpg

Get Object Metadata

Get metadata for an object without downloading it.

Endpoint: HEAD /storage/buckets/{bucket_name}/objects/{object_key}

Example Request:

curl -I -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/objects/images/photo.jpg

Delete Object

Delete an object from storage.

Endpoint: DELETE /storage/buckets/{bucket_name}/objects/{object_key}

Example Request:

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/objects/images/old-photo.jpg

Multipart Upload

For large files, use multipart upload for better performance and reliability.

Initiate Multipart Upload

Endpoint: POST /storage/buckets/{bucket_name}/objects/{object_key}?uploads

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: video/mp4" \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/objects/videos/large-video.mp4?uploads

Example Response:

{
  "upload_id": "upload_123456789",
  "bucket": "my-app-storage",
  "key": "videos/large-video.mp4"
}

Upload Part

Endpoint: PUT /storage/buckets/{bucket_name}/objects/{object_key}?partNumber={part_number}&uploadId={upload_id}

Example Request:

curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
  --data-binary @part1.bin \
  "https://api.lineserve.com/v1/storage/buckets/my-app-storage/objects/videos/large-video.mp4?partNumber=1&uploadId=upload_123456789"

Complete Multipart Upload

Endpoint: POST /storage/buckets/{bucket_name}/objects/{object_key}?uploadId={upload_id}

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  -d '<CompleteMultipartUpload>
    <Part>
      <PartNumber>1</PartNumber>
      <ETag>"etag1"</ETag>
    </Part>
    <Part>
      <PartNumber>2</PartNumber>
      <ETag>"etag2"</ETag>
    </Part>
  </CompleteMultipartUpload>' \
  "https://api.lineserve.com/v1/storage/buckets/my-app-storage/objects/videos/large-video.mp4?uploadId=upload_123456789"

Presigned URLs

Generate temporary URLs for direct client access to objects.

Generate Presigned URL

Endpoint: POST /storage/buckets/{bucket_name}/objects/{object_key}/presigned-url

Parameters:

method (required): HTTP method (GET, PUT, DELETE)
expires_in (optional): Expiration time in seconds (default: 3600)

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "PUT",
    "expires_in": 7200
  }' \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/objects/uploads/file.pdf/presigned-url

Example Response:

{
  "url": "https://storage.lineserve.com/my-app-storage/uploads/file.pdf?signature=...",
  "expires_at": "2024-01-15T12:30:00Z",
  "method": "PUT"
}

Block Storage

Volumes

List Volumes

Get a list of all block storage volumes.

Endpoint: GET /storage/volumes

Parameters:

region (optional): Filter by region
status (optional): Filter by status
attached (optional): Filter by attachment status

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/storage/volumes?region=nairobi"

Example Response:

{
  "volumes": [
    {
      "id": "vol_123456",
      "name": "database-storage",
      "size": 100,
      "region": "nairobi",
      "status": "available",
      "attached_to": null,
      "filesystem": "ext4",
      "created_at": "2024-01-15T10:30:00Z",
      "tags": ["database", "production"]
    }
  ]
}

Create Volume

Create a new block storage volume.

Endpoint: POST /storage/volumes

Parameters:

name (required): Volume name
size (required): Size in GB (minimum 1GB)
region (required): Storage region
filesystem (optional): Filesystem type (ext4, xfs)
snapshot_id (optional): Create from snapshot
tags (optional): Array of tags

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "app-data-volume",
    "size": 50,
    "region": "nairobi",
    "filesystem": "ext4",
    "tags": ["application", "data"]
  }' \
  https://api.lineserve.com/v1/storage/volumes

Get Volume Details

Get detailed information about a specific volume.

Endpoint: GET /storage/volumes/{volume_id}

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/volumes/vol_123456

Resize Volume

Increase the size of a volume.

Endpoint: POST /storage/volumes/{volume_id}/resize

Parameters:

size (required): New size in GB (must be larger than current)

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 200
  }' \
  https://api.lineserve.com/v1/storage/volumes/vol_123456/resize

Attach Volume

Attach a volume to a VPS instance.

Endpoint: POST /storage/volumes/{volume_id}/attach

Parameters:

vps_id (required): VPS instance ID

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vps_id": "vps_789012"
  }' \
  https://api.lineserve.com/v1/storage/volumes/vol_123456/attach

Detach Volume

Detach a volume from a VPS instance.

Endpoint: POST /storage/volumes/{volume_id}/detach

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/volumes/vol_123456/detach

Delete Volume

Delete a volume permanently.

Endpoint: DELETE /storage/volumes/{volume_id}

Example Request:

curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/volumes/vol_123456

Snapshots

List Snapshots

Get a list of volume snapshots.

Endpoint: GET /storage/snapshots

Parameters:

volume_id (optional): Filter by volume
region (optional): Filter by region

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/snapshots

Create Snapshot

Create a snapshot of a volume.

Endpoint: POST /storage/snapshots

Parameters:

volume_id (required): Volume to snapshot
name (required): Snapshot name
description (optional): Snapshot description

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "volume_id": "vol_123456",
    "name": "backup-2024-01-15",
    "description": "Daily backup before maintenance"
  }' \
  https://api.lineserve.com/v1/storage/snapshots

Restore from Snapshot

Create a new volume from a snapshot.

Endpoint: POST /storage/volumes/restore

Parameters:

snapshot_id (required): Snapshot to restore from
name (required): New volume name
size (optional): New volume size (must be >= snapshot size)

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "snap_123456",
    "name": "restored-volume",
    "size": 100
  }' \
  https://api.lineserve.com/v1/storage/volumes/restore

CDN Integration

Enable CDN

Enable CDN for a bucket to improve global content delivery.

Endpoint: POST /storage/buckets/{bucket_name}/cdn

Parameters:

custom_domain (optional): Custom domain for CDN
cache_ttl (optional): Cache TTL in seconds

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_domain": "cdn.myapp.com",
    "cache_ttl": 86400
  }' \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/cdn

Purge CDN Cache

Purge cached content from CDN.

Endpoint: POST /storage/buckets/{bucket_name}/cdn/purge

Parameters:

paths (optional): Array of paths to purge (purges all if empty)

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": ["/images/photo.jpg", "/css/style.css"]
  }' \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/cdn/purge

Access Control

Bucket Policies

Get Bucket Policy

Get the access policy for a bucket.

Endpoint: GET /storage/buckets/{bucket_name}/policy

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/policy

Set Bucket Policy

Set an access policy for a bucket.

Endpoint: PUT /storage/buckets/{bucket_name}/policy

Example Request:

curl -X PUT -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Version": "2012-10-17",
    "Statement": [
      {
        "Effect": "Allow",
        "Principal": "*",
        "Action": "s3:GetObject",
        "Resource": "arn:aws:s3:::my-app-storage/public/*"
      }
    ]
  }' \
  https://api.lineserve.com/v1/storage/buckets/my-app-storage/policy

Access Keys

List Access Keys

Get a list of storage access keys.

Endpoint: GET /storage/access-keys

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.lineserve.com/v1/storage/access-keys

Create Access Key

Create a new access key for S3-compatible access.

Endpoint: POST /storage/access-keys

Parameters:

name (required): Access key name
permissions (required): Array of permissions
bucket_access (optional): Restrict to specific buckets

Example Request:

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "App Storage Key",
    "permissions": ["read", "write"],
    "bucket_access": ["my-app-storage"]
  }' \
  https://api.lineserve.com/v1/storage/access-keys

Usage Analytics

Storage Usage

Get storage usage statistics.

Endpoint: GET /storage/usage

Parameters:

from_date (optional): Start date
to_date (optional): End date
bucket (optional): Filter by bucket

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.lineserve.com/v1/storage/usage?from_date=2024-01-01&to_date=2024-01-31"

Example Response:

{
  "usage": [
    {
      "date": "2024-01-15",
      "storage_used": 10737418240,
      "bandwidth_used": 1073741824,
      "requests": 1500,
      "cost": 5.25
    }
  ],
  "summary": {
    "total_storage": 10737418240,
    "total_bandwidth": 31457280000,
    "total_requests": 45000,
    "total_cost": 157.50
  }
}

S3 Compatibility

Lineserve Storage is fully compatible with Amazon S3 APIs. You can use existing S3 tools and SDKs.

S3 Endpoint

https://s3.lineserve.com

AWS CLI Configuration

aws configure set aws_access_key_id YOUR_ACCESS_KEY
aws configure set aws_secret_access_key YOUR_SECRET_KEY
aws configure set default.region nairobi
aws configure set default.s3.endpoint_url https://s3.lineserve.com

SDK Configuration

Node.js (AWS SDK)

const AWS = require('aws-sdk');

const s3 = new AWS.S3({
  accessKeyId: 'YOUR_ACCESS_KEY',
  secretAccessKey: 'YOUR_SECRET_KEY',
  endpoint: 'https://s3.lineserve.com',
  region: 'nairobi',
  s3ForcePathStyle: true
});

Python (Boto3)

import boto3

s3 = boto3.client(
    's3',
    aws_access_key_id='YOUR_ACCESS_KEY',
    aws_secret_access_key='YOUR_SECRET_KEY',
    endpoint_url='https://s3.lineserve.com',
    region_name='nairobi'
)

Error Handling

HTTP Status Codes

200 - Success
201 - Created
204 - No Content
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
409 - Conflict
422 - Unprocessable Entity
500 - Internal Server Error

Error Response Format

{
  "error": {
    "code": "bucket_already_exists",
    "message": "A bucket with this name already exists",
    "resource": "my-bucket-name"
  }
}

Rate Limiting

API Requests: 1000 requests per hour per API key
Upload Bandwidth: 100 MB/s per account
Download Bandwidth: 1 GB/s per account

Base URL​

Authentication​

Object Storage​

Buckets​

List Buckets​

Create Bucket​

Get Bucket Details​

Delete Bucket​

Objects​

List Objects​

Upload Object​

Download Object​

Get Object Metadata​

Delete Object​

Multipart Upload​

Initiate Multipart Upload​

Upload Part​

Complete Multipart Upload​

Presigned URLs​

Generate Presigned URL​

Block Storage​

Volumes​

List Volumes​

Create Volume​

Get Volume Details​

Resize Volume​

Attach Volume​

Detach Volume​

Delete Volume​

Snapshots​

List Snapshots​

Create Snapshot​

Restore from Snapshot​

CDN Integration​

Enable CDN​

Purge CDN Cache​

Access Control​

Bucket Policies​

Get Bucket Policy​

Set Bucket Policy​

Access Keys​

List Access Keys​

Create Access Key​

Usage Analytics​

Storage Usage​

S3 Compatibility​

S3 Endpoint​

AWS CLI Configuration​

SDK Configuration​

Node.js (AWS SDK)​

Python (Boto3)​

Error Handling​

HTTP Status Codes​

Error Response Format​

Rate Limiting​

Next Steps​

Base URL

Authentication

Object Storage

Buckets

List Buckets

Create Bucket

Get Bucket Details

Delete Bucket

Objects

List Objects

Upload Object

Download Object

Get Object Metadata

Delete Object

Multipart Upload

Initiate Multipart Upload

Upload Part

Complete Multipart Upload

Presigned URLs

Generate Presigned URL

Block Storage

Volumes

List Volumes

Create Volume

Get Volume Details

Resize Volume

Attach Volume

Detach Volume

Delete Volume

Snapshots

List Snapshots

Create Snapshot

Restore from Snapshot

CDN Integration

Enable CDN

Purge CDN Cache

Access Control

Bucket Policies

Get Bucket Policy

Set Bucket Policy

Access Keys

List Access Keys

Create Access Key

Usage Analytics

Storage Usage

S3 Compatibility

S3 Endpoint

AWS CLI Configuration

SDK Configuration

Node.js (AWS SDK)

Python (Boto3)

Error Handling

HTTP Status Codes

Error Response Format

Rate Limiting

Next Steps