Data Store

The ThreatWinds Data Store provides multi-tenant, structured data storage for AI workflows. It supports multiple data organization structures (key-value, documents, graphs, blobs) behind a consistent API surface.

Overview

The store API provides:

• Multi-tenant isolation — data is scoped to your customer account
• Consistent response envelopes — every response includes ok, data, meta, and (for list endpoints) pagination
• Optimistic locking — concurrent write safety via If-Match headers and version tracking
• Cursor-based pagination — efficient, stable list traversal

Authentication

Store endpoints use the same authentication as the AI API. See Authentication for details.

All store operations are scoped to your customer account (resolved from your user-id). Multiple users within the same account share the same data namespace.

Base URL

https://apis.threatwinds.com/api/ai/v1/store

Endpoints

Method	Path	Description
GET	/store	Discover available store features

Response Envelope

All successful store responses follow this envelope:

{
  "ok": true,
  "data": { ... },
  "meta": {
    "version": 1,
    "size": 256,
    "created_at": "2026-05-04T12:00:00Z",
    "updated_at": "2026-05-04T12:00:00Z",
    "tenant_id": "cust-abc123",
    "request_id": "req-def456"
  }
}

Meta Fields

Field	Type	Description
version	integer	Resource version for optimistic locking
size	integer	Byte size of the response payload
created_at	string (ISO 8601)	Resource creation time
updated_at	string (ISO 8601)	Last modification time
tenant_id	string	Customer account ID
request_id	string	Unique request identifier for tracing

Pagination

List endpoints include a top-level pagination object:

{
  "ok": true,
  "data": { ... },
  "pagination": {
    "limit": 20,
    "next_cursor": "eyJpZCI6InZsIn0",
    "has_more": true
  },
  "meta": { ... }
}

Field	Type	Description
limit	integer	Number of items returned (default 20, max 100)
next_cursor	string	Opaque cursor for fetching the next page
has_more	boolean	Whether more items are available

Error Format

Store errors follow the OpenAI-compatible error format. Common store-specific error codes:

Code	HTTP Status	Description
not_found	404	Resource doesn’t exist
conflict	409	Version mismatch (optimistic lock failure)
invalid_request	422	Validation failure
tenant_not_found	404	Customer ID resolution failed
rate_limited	429	Rate limit exceeded
namespace_taken	409	Caller-provided ID already exists

Discovery

List available store features:

curl -X GET 'https://apis.threatwinds.com/api/ai/v1/store' \
  -H 'Authorization: Bearer <token>'

Response:

{
  "ok": true,
  "data": {
    "features": []
  },
  "meta": {
    "tenant_id": "cust-abc123",
    "request_id": "req-def456"
  }
}

Best Practices

1. Use If-Match for updates — always include the current version when updating resources to avoid accidental overwrites
2. Paginate efficiently — use next_cursor rather than trying to compute offsets
3. Caller IDs are flexible — you can provide your own resource IDs or let the system generate ULIDs