{ "openapi": "3.1.0", "info": { "title": "Aetherfy Vector API", "version": "1.0.0", "summary": "Qdrant-compatible vector database API.", "description": "The Aetherfy vector data plane. Collection names are tenant-scoped server-side, so you always use your own bare collection name. This document is a deliberately thin index: paths, methods, auth and enforced limits are exact, and request/response bodies are described in summaries rather than invented schemas.", "contact": { "name": "Aetherfy support", "email": "support@aetherfy.com", "url": "https://aetherfy.com" } }, "servers": [ { "url": "https://vectors.aetherfy.com", "description": "Aetherfy vector data plane" } ], "security": [ { "bearerAuth": [] } ], "components": { "schemas": { "PointId": { "description": "An unsigned integer up to 2^53-1, or a UUID string. Arbitrary strings such as \"doc-001\" are rejected with 400 INVALID_POINT_ID. There is no coercion: an integer id returns as an integer and a UUID as a string.", "oneOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "string" } ] }, "Point": { "type": "object", "required": [ "id", "vector" ], "properties": { "id": { "$ref": "#/components/schemas/PointId" }, "vector": { "type": "array", "items": { "type": "number" } }, "payload": { "type": "object", "additionalProperties": true, "description": "Arbitrary JSON. Keys beginning `__aetherfy_` are reserved and rejected." } } }, "SearchResult": { "type": "object", "required": [ "id", "score" ], "properties": { "id": { "$ref": "#/components/schemas/PointId" }, "score": { "type": "number" }, "payload": { "type": "object", "additionalProperties": true }, "vector": { "type": "array", "items": { "type": "number" } } } }, "VectorConfig": { "type": "object", "required": [ "size", "distance" ], "properties": { "size": { "type": "integer", "description": "Vector dimension. Aetherfy enforces no maximum." }, "distance": { "type": "string", "description": "Accepted case-insensitively. Note the stored value differs for Euclidean: both \"euclid\" and \"euclidean\" are stored and returned as \"Euclid\".", "enum": [ "Cosine", "Euclid", "Dot", "Manhattan" ] } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable identifier. Full list at /errors.json" }, "message": { "type": "string" } }, "additionalProperties": true } } }, "UsageStats": { "type": "object", "required": [ "storage_bytes_used", "storage_limit_bytes", "collections_count", "collections_limit", "tier", "active_regions", "usage_percentage" ], "properties": { "storage_bytes_used": { "type": "integer", "description": "Bytes stored across every active collection." }, "storage_limit_bytes": { "type": [ "integer", "null" ], "description": "Plan storage limit in bytes. NULL means unlimited — it is not 0 and not absent." }, "collections_count": { "type": "integer", "description": "Active collections." }, "collections_limit": { "type": [ "integer", "null" ], "description": "Plan collection limit. NULL means unlimited, the SAME sentinel storage_limit_bytes uses. Before 2026-09-02 this field forwarded an internal \"unlimited\" STRING while its sibling sent null, so one response answered the same question in two vocabularies." }, "tier": { "type": "string", "description": "The account's plan tier." }, "active_regions": { "type": "array", "items": { "type": "string" }, "description": "Replication footprint: the union of every active collection's regions. Empty when the account has no active collections." }, "usage_percentage": { "type": "integer", "description": "Storage used as a percentage of the limit. 0 when there is no limit to be a percentage of." } } }, "MetricsCoverage": { "type": "object", "description": "Whether the window is ATTESTED. A producer upserts a heartbeat row on every flush, traffic or not, so a fresh heartbeat is what makes a zero a real zero rather than a silent collector.", "properties": { "fresh": { "type": "boolean", "description": "AND across regions: one dark region must not let its absent rows render as real zeros. When false, treat every number in the response as NOT ATTESTED, never as 0." }, "stale_after_seconds": { "type": "integer", "description": "Heartbeat age past which coverage is no longer attested." }, "last_flush_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_record_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last request ANY collector observed." }, "regions": { "type": "array", "description": "Per-region freshness, so a smarter client can tell which region went dark.", "items": { "type": "object", "properties": { "region": { "type": "string" }, "last_flush_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_record_at": { "type": [ "string", "null" ], "format": "date-time" }, "fresh": { "type": "boolean" } } } } } }, "Metrics": { "type": "object", "properties": { "window": { "type": "object", "description": "Echoed back from ONE server clock read, so a client never has to re-derive the boundaries.", "properties": { "name": { "type": "string", "enum": [ "24h", "7d", "30d" ] }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "bucket": { "type": "string", "enum": [ "hour", "day" ] } } }, "coverage": { "$ref": "#/components/schemas/MetricsCoverage" }, "totals": { "type": "object", "description": "EVERY field is nullable, and null NEVER means zero. With no heartbeat row at all, all seven are null and coverage.fresh is false. With a heartbeat, the counts are real measured values (0 included) and the three latency fields stay null when there were no requests — there is no p50 of nothing, and 0 ms would be a fabrication.", "properties": { "requests": { "type": [ "integer", "null" ] }, "errors_4xx": { "type": [ "integer", "null" ] }, "errors_429": { "type": [ "integer", "null" ] }, "errors_5xx": { "type": [ "integer", "null" ] }, "p50_ms": { "type": [ "integer", "null" ], "description": "HISTOGRAM UPPER BOUND, not an interpolated percentile: the smallest fixed bucket bound (5, 10, 25, 50, 100, 250, 1000 ms) whose cumulative count reaches half the requests. NULL when the rank falls past 1000 ms — there is no honest bound there, and max_ms is the exact number to use instead." }, "p95_ms": { "type": [ "integer", "null" ], "description": "Same histogram-bound semantics as p50_ms, at 95%." }, "max_ms": { "type": [ "integer", "null" ], "description": "EXACT, not a bound. Null when nothing was measured." } } }, "series": { "type": "array", "description": "One entry per bucket. Empty when coverage.fresh is false.", "items": { "type": "object", "properties": { "bucket_start": { "type": "string", "format": "date-time" }, "requests": { "type": "integer" }, "errors_4xx": { "type": "integer" }, "errors_429": { "type": "integer" }, "errors_5xx": { "type": "integer" }, "p95_ms": { "type": [ "integer", "null" ], "description": "Histogram upper bound; null past 1000 ms." } } } }, "by_op": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "search", "upsert", "retrieve", "delete", "collections", "other" ] }, "requests": { "type": "integer" }, "errors_4xx": { "type": "integer" }, "errors_5xx": { "type": "integer" }, "p50_ms": { "type": [ "integer", "null" ] }, "p95_ms": { "type": [ "integer", "null" ] } } } }, "by_collection": { "type": "array", "description": "Top 25 by requests. Requests carrying no collection are excluded.", "items": { "type": "object", "properties": { "collection": { "type": "string" }, "requests": { "type": "integer" }, "errors_4xx": { "type": "integer" }, "errors_5xx": { "type": "integer" } } } }, "by_region": { "type": "array", "description": "The AWS region that SERVED each request.", "items": { "type": "object", "properties": { "region": { "type": "string" }, "requests": { "type": "integer" } } } } } }, "FieldValidationError": { "type": "object", "description": "The 400 envelope for a rejected query parameter. `field` and `allowed` sit DIRECTLY on the error object, not nested under a detail key, so a client can branch on them.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "message": { "type": "string" }, "field": { "type": "string", "description": "The offending parameter." }, "allowed": { "type": "array", "items": { "type": "string" }, "description": "The accepted values." } }, "additionalProperties": true } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An Aetherfy API key, sent as `Authorization: Bearer `. Keys look like afy_live_… or afy_test_… and are created at https://app.aetherfy.com/dashboard/settings/api-keys" } } }, "tags": [ { "name": "collections", "description": "Collection lifecycle and points" }, { "name": "workspace-collections", "description": "The same surface, scoped to a workspace" }, { "name": "schema", "description": "Payload schema for a collection" }, { "name": "discovery", "description": "Region discovery" }, { "name": "analytics", "description": "Usage against plan limits, and measured request telemetry" } ], "x-rate-limits": { "window": "fixed 60-second bucket", "retryAfterHeader": false, "note": "No Retry-After header is sent on a 429. Exceeding the allowance returns error.code RATE_LIMIT_EXCEEDED.", "perMinuteByTier": { "free": 1000, "starter": 5000, "performance": 20000, "enterprise": 50000 } }, "x-unsupported": [ "PUT /api/v1/collections/{collection} (engine-native create) returns 405 — create with POST /api/v1/collections", "POST /api/v1/collections/{collection}/points is not an upsert; upsert is PUT", "The engine-native operational paths — snapshots, /telemetry, /metrics, /cluster, /locks and the shard endpoints — return 404. This does NOT refer to /api/v1/analytics/metrics, which is an Aetherfy endpoint documented in this index.", "payload keys beginning __aetherfy_ are rejected on write and stripped from reads" ], "paths": { "/api/v1/collections": { "parameters": [], "post": { "summary": "Create a collection. Body: {name, vectors:{size,distance}, description?, regions?}. Re-creating a collection with the SAME configuration is idempotent and returns 200; the same name with a DIFFERENT configuration returns 409 COLLECTION_NAME_TAKEN. Distance names are normalised case-insensitively, and both \"euclid\" and \"euclidean\" are stored as \"Euclid\" — so a collection created with the SDKs' EUCLIDEAN reads back as \"Euclid\", not \"Euclidean\".", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] }, "get": { "summary": "List collections.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] } }, "/api/v1/collections/{collection}": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get collection info. Returns {result, schema_version} and sets ETag, X-Collection-Source and X-Collection-Status headers.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] }, "patch": { "summary": "Update collection metadata. Only `description` is mutable — any other key returns 400.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] }, "delete": { "summary": "Delete a collection.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] } }, "/api/v1/collections/{collection}/points": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "Upsert points (streaming). Note this is PUT — POST on this path is not an upsert.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "points" ], "properties": { "points": { "type": "array", "items": { "$ref": "#/components/schemas/Point" } } } } } } }, "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ], "x-limits": { "maxPointsPerCall": 10000, "maxBodyBytes": 524288000, "idleTimeoutSeconds": 30 } } }, "/api/v1/collections/{collection}/points/search": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Similarity search. `params` is forwarded verbatim to the engine — {\"hnsw_ef\": 256} searches the index more thoroughly at slightly higher latency.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vector" ], "properties": { "vector": { "type": "array", "items": { "type": "number" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 }, "offset": { "type": "integer", "minimum": 0, "default": 0 }, "with_payload": { "type": "boolean", "default": true }, "with_vector": { "type": "boolean", "default": false }, "filter": { "type": "object", "additionalProperties": true }, "score_threshold": { "type": "number" }, "params": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Ranked matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } } } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ], "x-limits": { "maxLimit": 1000, "maxResponseBytes": 10485760 } } }, "/api/v1/collections/{collection}/points/scroll": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Paginate through points.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ], "x-limits": { "maxLimit": 1000, "maxResponseBytes": 10485760 } } }, "/api/v1/collections/{collection}/points/retrieve": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Retrieve points by id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "maxItems": 256, "items": { "$ref": "#/components/schemas/PointId" } }, "with_payload": { "type": "boolean", "default": true }, "with_vector": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "The requested points", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Point" } } } } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ], "x-limits": { "maxIds": 256, "maxResponseBytes": 10485760 } } }, "/api/v1/collections/{collection}/points/count": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Count points. A `limit` key is stripped server-side.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "type": "object", "additionalProperties": true }, "exact": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The count", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "count": { "type": "integer" } } }, "status": { "type": "string" } } } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] } }, "/api/v1/collections/{collection}/points/delete": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Delete points by id list {points:[...]} or by {filter:{...}}.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ], "x-limits": { "maxPoints": 512 } } }, "/api/v1/collections/{collection}/points/payload": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Merge payload fields into points (additive).", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ], "x-limits": { "maxPoints": 512 } }, "put": { "summary": "Overwrite payload on points (replaces absent keys).", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ], "x-limits": { "maxPoints": 512 } } }, "/api/v1/collections/{collection}/points/payload/delete": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Delete payload keys from points. Body: {keys, points}.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ], "x-limits": { "maxPoints": 512 } } }, "/api/v1/collections/{collection}/points/{id}": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": [ "string", "integer" ] } } ], "get": { "summary": "Retrieve a single point by id.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] } }, "/api/v1/collections/{collection}/index": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "Create a payload field index.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] }, "post": { "summary": "Create a payload field index.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] } }, "/api/v1/workspaces/{workspace}/collections": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Create a collection. Body: {name, vectors:{size,distance}, description?, regions?}. Re-creating a collection with the SAME configuration is idempotent and returns 200; the same name with a DIFFERENT configuration returns 409 COLLECTION_NAME_TAKEN. Distance names are normalised case-insensitively, and both \"euclid\" and \"euclidean\" are stored as \"Euclid\" — so a collection created with the SDKs' EUCLIDEAN reads back as \"Euclid\", not \"Euclidean\".", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ] }, "get": { "summary": "List collections.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ] } }, "/api/v1/workspaces/{workspace}/collections/{collection}": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get collection info. Returns {result, schema_version} and sets ETag, X-Collection-Source and X-Collection-Status headers.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ] }, "patch": { "summary": "Update collection metadata. Only `description` is mutable — any other key returns 400.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ] }, "delete": { "summary": "Delete a collection.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ] } }, "/api/v1/workspaces/{workspace}/collections/{collection}/points": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "Upsert points (streaming). Note this is PUT — POST on this path is not an upsert.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "points" ], "properties": { "points": { "type": "array", "items": { "$ref": "#/components/schemas/Point" } } } } } } }, "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ], "x-limits": { "maxPointsPerCall": 10000, "maxBodyBytes": 524288000, "idleTimeoutSeconds": 30 } } }, "/api/v1/workspaces/{workspace}/collections/{collection}/points/search": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Similarity search. `params` is forwarded verbatim to the engine — {\"hnsw_ef\": 256} searches the index more thoroughly at slightly higher latency.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vector" ], "properties": { "vector": { "type": "array", "items": { "type": "number" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 }, "offset": { "type": "integer", "minimum": 0, "default": 0 }, "with_payload": { "type": "boolean", "default": true }, "with_vector": { "type": "boolean", "default": false }, "filter": { "type": "object", "additionalProperties": true }, "score_threshold": { "type": "number" }, "params": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Ranked matches", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } } } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ], "x-limits": { "maxLimit": 1000, "maxResponseBytes": 10485760 } } }, "/api/v1/workspaces/{workspace}/collections/{collection}/points/scroll": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Paginate through points.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ], "x-limits": { "maxLimit": 1000, "maxResponseBytes": 10485760 } } }, "/api/v1/workspaces/{workspace}/collections/{collection}/points/retrieve": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Retrieve points by id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "maxItems": 256, "items": { "$ref": "#/components/schemas/PointId" } }, "with_payload": { "type": "boolean", "default": true }, "with_vector": { "type": "boolean", "default": false } } } } } }, "responses": { "200": { "description": "The requested points", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Point" } } } } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ], "x-limits": { "maxIds": 256, "maxResponseBytes": 10485760 } } }, "/api/v1/workspaces/{workspace}/collections/{collection}/points/count": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Count points. A `limit` key is stripped server-side.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filter": { "type": "object", "additionalProperties": true }, "exact": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The count", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "count": { "type": "integer" } } }, "status": { "type": "string" } } } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ] } }, "/api/v1/workspaces/{workspace}/collections/{collection}/points/delete": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Delete points by id list {points:[...]} or by {filter:{...}}.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ], "x-limits": { "maxPoints": 512 } } }, "/api/v1/workspaces/{workspace}/collections/{collection}/points/payload": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Merge payload fields into points (additive).", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ], "x-limits": { "maxPoints": 512 } }, "put": { "summary": "Overwrite payload on points (replaces absent keys).", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ], "x-limits": { "maxPoints": 512 } } }, "/api/v1/workspaces/{workspace}/collections/{collection}/points/payload/delete": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Delete payload keys from points. Body: {keys, points}.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ], "x-limits": { "maxPoints": 512 } } }, "/api/v1/workspaces/{workspace}/collections/{collection}/points/{id}": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": [ "string", "integer" ] } } ], "get": { "summary": "Retrieve a single point by id.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ] } }, "/api/v1/workspaces/{workspace}/collections/{collection}/index": { "parameters": [ { "name": "workspace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "put": { "summary": "Create a payload field index.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ] }, "post": { "summary": "Create a payload field index.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "workspace-collections" ] } }, "/api/v1/collections/{collection}/index/{field}": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "field", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete a payload field index.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "collections" ] } }, "/api/v1/schema/{collection}": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get the payload schema. Sets an ETag header.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "schema" ] }, "put": { "summary": "Create or replace the payload schema. Body: {schema, enforcement_mode: off|warn|strict, description?}. Supports If-Match for optimistic concurrency.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "schema" ] }, "delete": { "summary": "Remove the payload schema.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "schema" ] } }, "/api/v1/schema/{collection}/analyze": { "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Infer a payload schema by sampling the collection. Body: {sample_size?}.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "schema" ], "x-limits": { "minSampleSize": 100, "maxSampleSize": 10000 } } }, "/api/v1/regions": { "get": { "summary": "Map region codes to their regional URLs. Used by the SDKs for region pinning.", "responses": { "200": { "description": "Success" }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "discovery" ] } }, "/api/v1/analytics/usage": { "get": { "summary": "Current storage and collection usage against the plan. Both limit fields are null on an unlimited tier — null is the only \"no limit\" sentinel this response uses.", "responses": { "200": { "description": "Usage against plan limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageStats" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "analytics" ] } }, "/api/v1/analytics/metrics": { "parameters": [ { "name": "window", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ], "default": "24h" }, "description": "24h and 7d bucket by hour; 30d buckets by UTC day. Any other value is a 400." } ], "get": { "summary": "Durable request telemetry for the calling account, summed over counter rows a producer wrote after observing real responses. Read `coverage.fresh` FIRST: when it is false, every number is unattested and must be rendered as no-data rather than zero. Latency percentiles are histogram upper bounds, not interpolations.", "responses": { "200": { "description": "Measured request telemetry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metrics" } } } }, "400": { "description": "`window` is not one of the accepted values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldValidationError" } } } }, "500": { "description": "The read failed. The endpoint returns an error rather than a well-formed body of zeros, which would be indistinguishable from a quiet week.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "4XX": { "description": "Client error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "5XX": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "tags": [ "analytics" ] } } } }