{
"openapi": "3.0.0",
"info": {
"title": "DeepStore API",
"version": "0.1.0",
"description": "Log storage and search database control plane API"
},
"servers": [
{
"url": "http://localhost:8787",
"description": "Development"
}
],
"tags": [
{
"name": "databases",
"description": "Database management endpoints"
},
{
"name": "drafts",
"description": "Draft management endpoints"
},
{
"name": "splits",
"description": "Split query endpoints"
},
{
"name": "jobs",
"description": "Job coordination endpoints"
},
{
"name": "tokens",
"description": "Service token lifecycle"
},
{
"name": "health",
"description": "Health check"
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT or Token",
"description": "Platform JWT (for database management), Service Token (for agent operations), or Query JWT (for search)"
}
},
"schemas": {},
"parameters": {}
},
"paths": {
"/databases": {
"post": {
"operationId": "createDatabase",
"tags": ["databases"],
"description": "Create a new database. Returns a service token (one-time only).",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": ["name"]
}
}
}
},
"responses": {
"200": {
"description": "Database created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"databaseId": {
"type": "string"
},
"name": {
"type": "string"
},
"serviceToken": {
"type": "string"
},
"createdAt": {
"type": "string"
}
},
"required": [
"databaseId",
"name",
"serviceToken",
"createdAt"
]
}
}
}
}
}
}
},
"/databases/{databaseId}": {
"get": {
"operationId": "getDatabase",
"tags": ["databases"],
"description": "Get database information",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Database information",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"databaseId": {
"type": "string"
},
"name": {
"type": "string"
},
"draftCount": {
"type": "number"
},
"splitCount": {
"type": "number"
},
"createdAt": {
"type": "string"
}
},
"required": [
"databaseId",
"name",
"draftCount",
"splitCount",
"createdAt"
]
}
}
}
},
"404": {
"description": "Database not found"
}
}
},
"delete": {
"operationId": "deleteDatabase",
"tags": ["databases"],
"description": "Delete a database and all its data",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Database deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["success"]
}
}
}
}
}
}
},
"/databases/{databaseId}/commit-draft": {
"post": {
"operationId": "commitDraft",
"tags": ["drafts"],
"description": "Commit draft metadata after uploading to object storage",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"draftId": {
"type": "string"
},
"sizeBytes": {
"type": "number"
},
"numDocs": {
"type": "number"
},
"startTimestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"endTimestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"scope": {
"type": "string"
}
},
"required": [
"draftId",
"sizeBytes",
"numDocs",
"startTimestamp",
"endTimestamp",
"scope"
]
}
}
}
},
"responses": {
"200": {
"description": "Draft committed successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
},
"required": ["success"]
}
}
}
}
}
}
},
"/databases/{databaseId}/drafts": {
"get": {
"operationId": "listDrafts",
"tags": ["drafts"],
"description": "List drafts, optionally filtered by scopes from JWT",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "List of drafts",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"drafts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"draftId": {
"type": "string"
},
"scope": {
"type": "string"
},
"sizeBytes": {
"type": "number"
},
"numDocs": {
"type": "number"
},
"startTimestamp": {
"type": "number"
},
"endTimestamp": {
"type": "number"
},
"status": {
"type": "string",
"enum": [
"committed",
"indexing",
"index_failed",
"indexed",
"cleaning_up",
"cleanup_failed"
]
},
"createdAt": {
"type": "string"
}
},
"required": [
"draftId",
"scope",
"sizeBytes",
"numDocs",
"startTimestamp",
"endTimestamp",
"status",
"createdAt"
]
}
}
},
"required": ["drafts"]
}
}
}
}
}
}
},
"/databases/{databaseId}/splits": {
"get": {
"operationId": "listSplits",
"tags": ["splits"],
"description": "List published splits within a time range",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "startTimestamp",
"in": "query"
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "endTimestamp",
"in": "query"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "limit",
"in": "query"
}
],
"responses": {
"200": {
"description": "List of splits",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"splits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"splitId": {
"type": "string"
},
"timeRangeStart": {
"type": "number"
},
"timeRangeEnd": {
"type": "number"
},
"numDocs": {
"type": "number"
},
"sizeBytes": {
"type": "number"
},
"state": {
"type": "string",
"enum": [
"staged",
"published",
"marked_for_deletion"
]
},
"footerOffsets": {
"type": "object",
"properties": {
"start": {
"type": "number"
},
"end": {
"type": "number"
}
},
"required": ["start", "end"]
},
"createdAt": {
"type": "string"
}
},
"required": [
"splitId",
"timeRangeStart",
"timeRangeEnd",
"numDocs",
"sizeBytes",
"state",
"createdAt"
]
}
}
},
"required": ["splits"]
}
}
}
}
}
}
},
"/databases/{databaseId}/indexing-jobs/lease": {
"post": {
"operationId": "leaseIndexingJob",
"tags": ["jobs"],
"description": "Lease an indexing job (lock drafts for indexing)",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"maxDrafts": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10
}
}
}
}
}
},
"responses": {
"200": {
"description": "Indexing job leased or null if no work available",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job": {
"type": "object",
"nullable": true,
"properties": {
"jobId": {
"type": "string"
},
"draftIds": {
"type": "array",
"items": {
"type": "string"
}
},
"inputNumDocs": {
"type": "number"
},
"inputSizeBytes": {
"type": "number"
}
},
"required": ["jobId", "draftIds"]
}
},
"required": ["job"]
}
}
}
}
}
}
},
"/databases/{databaseId}/indexing-jobs/{jobId}/complete": {
"post": {
"operationId": "completeIndexingJob",
"tags": ["jobs"],
"description": "Complete an indexing job",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "jobId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"splitId": {
"type": "string"
},
"sizeBytes": {
"type": "number"
},
"numDocs": {
"type": "number"
},
"timeRangeStart": {
"type": "number"
},
"timeRangeEnd": {
"type": "number"
},
"footerOffsets": {
"type": "object",
"properties": {
"start": {
"type": "number"
},
"end": {
"type": "number"
}
},
"required": ["start", "end"]
},
"indexedDraftIds": {
"type": "array",
"items": {
"type": "string"
}
},
"failedDraftIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
},
"splitMetadataJson": {
"type": "string"
}
},
"required": [
"splitId",
"sizeBytes",
"numDocs",
"timeRangeStart",
"timeRangeEnd",
"footerOffsets",
"indexedDraftIds"
]
}
}
}
},
"responses": {
"200": {
"description": "Indexing job completed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["success"]
}
}
}
}
}
}
},
"/databases/{databaseId}/cleanup-jobs/lease": {
"post": {
"operationId": "leaseCleanupJob",
"tags": ["jobs"],
"description": "Lease a draft cleanup job",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"maxDrafts": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10
}
}
}
}
}
},
"responses": {
"200": {
"description": "Cleanup job leased or null if no work available",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job": {
"type": "object",
"nullable": true,
"properties": {
"jobId": {
"type": "string"
},
"draftIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["jobId", "draftIds"]
}
},
"required": ["job"]
}
}
}
}
}
}
},
"/databases/{databaseId}/cleanup-jobs/{jobId}/complete": {
"post": {
"operationId": "completeCleanupJob",
"tags": ["jobs"],
"description": "Complete a draft cleanup job",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "jobId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cleanedDraftIds": {
"type": "array",
"items": {
"type": "string"
}
},
"failedDraftIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"required": ["cleanedDraftIds"]
}
}
}
},
"responses": {
"200": {
"description": "Cleanup job completed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["success"]
}
}
}
}
}
}
},
"/databases/{databaseId}/merge-jobs/lease": {
"post": {
"operationId": "leaseMergeJob",
"tags": ["jobs"],
"description": "Lease a merge job",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"maxSplits": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10
}
}
}
}
}
},
"responses": {
"200": {
"description": "Merge job leased or null if no work available",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job": {
"type": "object",
"nullable": true,
"properties": {
"jobId": {
"type": "string"
},
"splitIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["jobId", "splitIds"]
}
},
"required": ["job"]
}
}
}
}
}
}
},
"/databases/{databaseId}/merge-jobs/{jobId}/complete": {
"post": {
"operationId": "completeMergeJob",
"tags": ["jobs"],
"description": "Complete a merge job",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "jobId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"newSplitId": {
"type": "string"
},
"sizeBytes": {
"type": "number"
},
"numDocs": {
"type": "number"
},
"timeRangeStart": {
"type": "number"
},
"timeRangeEnd": {
"type": "number"
},
"footerOffsets": {
"type": "object",
"properties": {
"start": {
"type": "number"
},
"end": {
"type": "number"
}
},
"required": ["start", "end"]
},
"mergedSplitIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"newSplitId",
"sizeBytes",
"numDocs",
"timeRangeStart",
"timeRangeEnd",
"footerOffsets",
"mergedSplitIds"
]
}
}
}
},
"responses": {
"200": {
"description": "Merge job completed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["success"]
}
}
}
}
}
}
},
"/databases/{databaseId}/split-cleanup-jobs/lease": {
"post": {
"operationId": "leaseSplitCleanupJob",
"tags": ["jobs"],
"description": "Lease a split cleanup job",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"maxSplits": {
"type": "number",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
}
}
}
},
"responses": {
"200": {
"description": "Split cleanup job leased or null if no work available",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"job": {
"type": "object",
"nullable": true,
"properties": {
"jobId": {
"type": "string"
},
"splitIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["jobId", "splitIds"]
}
},
"required": ["job"]
}
}
}
}
}
}
},
"/databases/{databaseId}/split-cleanup-jobs/{jobId}/complete": {
"post": {
"operationId": "completeSplitCleanupJob",
"tags": ["jobs"],
"description": "Complete a split cleanup job",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
},
{
"schema": {
"type": "string"
},
"required": true,
"name": "jobId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cleanedSplitIds": {
"type": "array",
"items": {
"type": "string"
}
},
"failedSplitIds": {
"type": "array",
"items": {
"type": "string"
},
"default": []
}
},
"required": ["cleanedSplitIds"]
}
}
}
},
"responses": {
"200": {
"description": "Split cleanup job completed",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["success"]
}
}
}
}
}
}
},
"/databases/{databaseId}/tokens/rotate": {
"post": {
"operationId": "rotateServiceToken",
"tags": ["tokens"],
"description": "Rotate service token (platform auth only)",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
}
],
"responses": {
"200": {
"description": "New service token",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"serviceToken": {
"type": "string"
}
},
"required": ["serviceToken"]
}
}
}
}
}
}
},
"/databases/{databaseId}/tokens/revoke": {
"post": {
"operationId": "revokeServiceTokens",
"tags": ["tokens"],
"description": "Revoke all service tokens (platform auth only)",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"schema": {
"type": "string"
},
"required": true,
"name": "databaseId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Tokens revoked",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["success"]
}
}
}
}
}
}
}
}
}