Ainoflow LogoAinoflow
← Back to API Documentation

Storage API Documentation

Schema-free JSON storage API for workflow state, configuration data, and document metadata.

Quick Reference
Base URL:
https://api.ainoflow.io
Authentication:
Authorization: Bearer your_api_key_here

Main Endpoints

POST
Create JSON Document (Auto-generated Key)
/api/v1/storage/json/{category}
Create a JSON document with auto-generated UUID key (without dashes)

Path Parameters:

category
required
- Logical grouping (namespace), max 100 chars

Query Parameters:

expiresAt
optional
- Absolute expiration date (ISO 8601)
expiresMs
optional
- Expiration time in milliseconds from now

Request Body (Raw JSON):

{
  "event_type": "user_login",
  "timestamp": "2024-01-15T10:30:00Z",
  "user_id": "user-456"
}

Response (201 Created):

{
  "category": "events",
  "key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "version": 1,
  "etag": "7f8e9d0c1b2a3f4e5d6c7b8a9f0e1d2c",
  "expiresAt": null
}

Note: The key is auto-generated as a UUID without dashes (32 hex characters)

POST
Create JSON Document (Specified Key)
/api/v1/storage/json/{category}/{key}
Create a JSON document with specified key. Fails with 409 Conflict if item already exists.

Path Parameters:

category
required
- Logical grouping (namespace), max 100 chars
key
required
- Unique identifier, max 200 chars

Query Parameters:

expiresAt
optional
- Absolute expiration date (ISO 8601)
expiresMs
optional
- Expiration time in milliseconds from now

Request Body (Raw JSON):

{
  "locked_by": "user-123",
  "locked_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-01-15T11:30:00Z"
}

Response (201 Created):

{
  "category": "user-locks",
  "key": "document-789",
  "version": 1,
  "etag": "7f8e9d0c1b2a3f4e5d6c7b8a9f0e1d2c",
  "expiresAt": null
}

Error Response (409 Conflict):

{
  "error": {
    "message": "Item with category 'user-locks' and key 'document-789' already exists"
  }
}

Use this for lock creation, unique records, or idempotent create operations

PUT
Store JSON Document (Upsert)
/api/v1/storage/json/{category}/{key}
Insert or update a JSON object for a given category and key

Path Parameters:

category
required
- Logical grouping (namespace), max 100 chars
key
required
- Unique identifier, max 200 chars

Query Parameters:

expiresAt
optional
- Absolute expiration date (ISO 8601)
expiresMs
optional
- Expiration time in milliseconds from now

Request Body (Raw JSON):

{
  "invoice_number": "INV-12345",
  "date": "2024-01-15",
  "total": 1250.00,
  "customer": {
    "name": "Acme Corp",
    "email": "billing@acme.com"
  }
}

Response (200 OK):

{
  "category": "invoices",
  "key": "inv-12345",
  "version": 1,
  "etag": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "expiresAt": null
}
PATCH
Partially Update JSON Document
/api/v1/storage/json/{category}/{key}
Partially update (patch) JSON object fields using JSON Merge Patch (RFC 7386)

Path Parameters:

category
required
- Logical grouping (namespace), max 100 chars
key
required
- Unique identifier, max 200 chars

Request Body (Patch JSON):

{
  "theme": "light",
  "notifications": {
    "email": false
  }
}

Only specified fields are updated. Null values remove fields. Objects are recursively merged.

Response (200 OK):

{
  "category": "config",
  "key": "app-settings",
  "version": 2,
  "etag": "xyz789",
  "expiresAt": null
}
GET
Retrieve JSON Document
/api/v1/storage/json/{category}/{key}
Get a specific JSON document by category and key

Query Parameters:

allowEmpty
optional
- If true, returns empty object {} instead of 404 when not found (default: false)

Response (200 OK) - Raw JSON:

{
  "invoice_number": "INV-12345",
  "date": "2024-01-15",
  "total": 1250.00,
  "customer": {
    "name": "Acme Corp",
    "email": "billing@acme.com"
  }
}

Returns the stored JSON document directly (not wrapped)

GET
List All Categories
/api/v1/storage/json
Get all distinct categories in JSON storage with item counts

Response (200 OK):

[
  {
    "category": "invoices",
    "count": 142
  },
  {
    "category": "customers",
    "count": 58
  },
  {
    "category": "settings",
    "count": 5
  }
]

Response header X-Total-Count contains total number of categories

GET
List Items in Category
/api/v1/storage/json/{category}
Get all items in a specific category with pagination and sorting

Query Parameters:

page
optional
- Page number (1-based, default: 1)
limit
optional
- Items per page (1-1000, default: 50)
sortBy
optional
- Sort field: key, createdAt, updatedAt, size (default: createdAt)
sortOrder
optional
- Sort order: asc, desc (default: asc)
aggregate
optional
- If true, returns full object with pagination metadata (default: false)

Response (200 OK) - Array (default):

[
  {
    "category": "invoices",
    "key": "inv-12345",
    "value": { "invoice_number": "INV-12345", "total": 1250.00 },
    "size": 1024,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T14:20:00Z",
    "expiresAt": null
  }
]

Pagination info in headers: X-Total-Count, X-Page, X-Limit, X-Total-Pages

Response (aggregate=true):

{
  "category": "invoices",
  "items": [...],
  "totalCount": 1520,
  "page": 2,
  "pageSize": 10,
  "totalPages": 152
}
GET
Get Document Metadata
/api/v1/storage/json/{category}/{key}/meta
Get metadata about a JSON document without retrieving the content itself

Response (200 OK):

{
  "category": "invoices",
  "key": "inv-12345",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:20:00Z",
  "expiresAt": null,
  "version": 3,
  "etag": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "size": 256,
  "createdBy": "api_key_123",
  "updatedBy": "api_key_123"
}

Metadata Fields:

  • • category - The document's category
  • • key - The document's key
  • • createdAt - When the document was first created (ISO 8601)
  • • updatedAt - When the document was last modified (ISO 8601)
  • • expiresAt - When the document expires, null if no expiration (ISO 8601)
  • • version - Version number for optimistic concurrency control
  • • etag - MD5 hash of the JSON content for change detection
  • • size - Size of JSON payload in bytes
  • • createdBy - API key identifier of the creator
  • • updatedBy - API key identifier of the last updater
DELETE
Delete JSON Document
/api/v1/storage/json/{category}/{key}
Remove a specific document from storage

Response (200 OK):

{
  "category": "invoices",
  "key": "inv-12345"
}

Example Usage

cURL Examples

Create document with auto-generated key

curl -X POST https://api.ainoflow.io/api/v1/storage/json/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type": "user_login", "timestamp": "2024-01-15T10:30:00Z"}'

Create document with specified key (fails if exists)

curl -X POST https://api.ainoflow.io/api/v1/storage/json/user-locks/document-789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locked_by": "user-123", "locked_at": "2024-01-15T10:30:00Z"}'

Store a JSON document (upsert)

curl -X PUT https://api.ainoflow.io/api/v1/storage/json/config/app-settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"theme": "dark", "language": "en"}'

Partially update a document (patch)

curl -X PATCH https://api.ainoflow.io/api/v1/storage/json/config/app-settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"theme": "light", "notifications": {"email": false}}'

Store with TTL (expires in 1 hour = 3600000 ms)

curl -X PUT "https://api.ainoflow.io/api/v1/storage/json/sessions/temp-session?expiresMs=3600000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user-456", "login_time": "2024-01-15T10:00:00Z"}'

Retrieve a document

curl https://api.ainoflow.io/api/v1/storage/json/config/app-settings \
  -H "Authorization: Bearer YOUR_API_KEY"

List all categories

curl https://api.ainoflow.io/api/v1/storage/json \
  -H "Authorization: Bearer YOUR_API_KEY"

List items in category (sorted by size, descending)

curl "https://api.ainoflow.io/api/v1/storage/json/invoices?sortBy=size&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get document metadata

curl https://api.ainoflow.io/api/v1/storage/json/config/app-settings/meta \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete a document

curl -X DELETE https://api.ainoflow.io/api/v1/storage/json/config/app-settings \
  -H "Authorization: Bearer YOUR_API_KEY"

Common Error Codes

400
Bad Request - Invalid JSON or parameter validation failed
401
Unauthorized - Missing or invalid API key
404
Not Found - Document or category not found
409
Conflict - Item already exists (POST with specified key)
429
Too Many Requests - Rate limit or storage limit exceeded
500
Internal Server Error - Storage operation failed

Ready to Get Started?

Create your free account and get your API key in minutes.

Get API KeyLearn More