API Reference - LaserData Docs

Endpoints

REST endpoints use https://api.laserdatahq.com/v1. Send the API key in the Authorization header.

POST /namespaces/{namespace}/objects

Write an object to a namespace, creating or replacing the value at its key. The JSON body requires a string key and object data. An optional integer ttl_seconds sets TTL from the last write.

{
  "key": "session:abc123",
  "data": { "step": 1, "task": "research" },
  "ttl_seconds": 86400
}

GET /namespaces/{namespace}/objects/{key}

Retrieve an object by key. Returns 404 when the key is absent or its TTL has expired. The response includes key, data, created_at, and updated_at.

POST /namespaces/{namespace}/query

Run a query on a namespace with a filter, optional order_by string, and optional limit. Prefix order_by with - to sort descending. limit allows 1000 maximum and defaults to 100. Returns items and total.

{
  "filter": { "step__gte": 2, "task__in": ["research", "draft"] },
  "order_by": "-step",
  "limit": 50
}

DELETE /namespaces/{namespace}/objects/{key}

Delete one object. Returns 204 on success or 404 if the key is absent.

DELETE /namespaces/{namespace}

Delete a namespace and all its objects. The operation is immediate and irreversible. Returns 204 on success.

Query filter syntax

Use field__operator for filters. Access nested fields with dot notation, such as metadata.tag__eq.

Operator	Meaning	Example
`__eq`	Exact match by default	`"status__eq": "active"`
`__neq`	Not equal	`"status__neq": "archived"`
`__gt`	Greater than	`"step__gt": 0`
`__gte`	Greater than or equal	`"step__gte": 2`
`__lt`	Less than	`"score__lt": 0.5`
`__lte`	Less than or equal	`"score__lte": 1.0`
`__in`	Value in list, up to 2,048 items	`"task__in": ["a", "b"]`
`__nin`	Value not in list	`"tag__nin": ["draft"]`
`__exists`	Field exists; boolean value	`"metadata__exists": true`

Data model

Objects use this API shape. The data field is free-form JSON with no required schema.

interface LaserDataObject {
  key:        string;       // namespace-scoped, max 512 chars
  data:       Record<string, unknown>;
  created_at: string;       // ISO-8601 UTC
  updated_at: string;       // ISO-8601 UTC, refreshed on each write
  ttl_expires: string | null; // null if no TTL set
}

Vector embeddings: Store embeddings as float arrays in data under any key. Configure the embedding field and dimensions for vector similarity queries. Maximum: 4,096 dimensions.

Streaming API

Subscriptions use HTTP server-sent events (SSE). Connect to the stream endpoint for one newline-delimited event per namespace write or delete.

GET /namespaces/{namespace}/stream

Returns an SSE stream. The optional URL-encoded filter parameter uses the query endpoint's JSON filter syntax. Events arrive in under 1ms after the originating write completes.

Each event uses this shape:

{
  "type":      "write",           // "write" | "delete"
  "namespace": "my-agent",
  "key":       "session:abc123",
  "data":      { "step": 2 },    // omitted on delete events
  "ts":        "2026-08-01T10:00:00.012Z"
}

Error codes

Errors return JSON with code, message, and request_id.

HTTP status	Code	Meaning
400	`invalid_filter`	The filter contains an unsupported operator or malformed value.
401	`unauthorized`	Missing or invalid API key in the `Authorization` header.
403	`forbidden`	The API key cannot access this namespace.
404	`not_found`	The object key is absent or expired.
413	`payload_too_large`	The request exceeds the 4MB per-object limit.
429	`rate_limited`	Daily query quota exceeded. Retry after the time in `X-RateLimit-Reset`.
500	`internal_error`	Unexpected server error. Provide the `request_id` to support.

Back to Quickstart