{"openapi":"3.1.0","info":{"title":"Blerbz NUCLEUZ API","version":"0.1.0","summary":"Ranked news, trending stories, BLERBZ100, documents, and sync.","description":"The Blerbz NUCLEUZ API is a News & Intelligence API that provides developer access to AI-powered news aggregation, ranked feeds, trending stories, BLERBZ100 daily rankings, documents, aliases, and incremental sync.","x-category":"News & Intelligence","x-ora-category":"News & Intelligence","termsOfService":"https://www.blerbz.com/legal/api-terms","contact":{"name":"Blerbz","email":"hello@blerbz.com","url":"https://www.blerbz.com"},"license":{"name":"MIT SDK License","url":"https://github.com/BLERBZ/blerbz/tree/main/packages/blerbz-sdk/LICENSE"}},"servers":[{"url":"https://api.blerbz.com","description":"Production NUCLEUZ API"},{"url":"https://www.blerbz.com","description":"Blerbz web proxy and public discovery routes"}],"tags":[{"name":"Feeds","description":"Ranked and filtered news feeds."},{"name":"Documents","description":"Article/document lookup and aliases."},{"name":"Sync","description":"Cursor-based incremental sync."},{"name":"Search","description":"News search and related-story discovery."},{"name":"Agent Integration","description":"Public agent discovery, question-answering, and MCP-style tool access."},{"name":"Batch","description":"Read-only batch helpers for agent and developer integration tests."},{"name":"Sandbox","description":"Non-mutating public test-environment status endpoints."}],"paths":{"/api/v2/feeds/latest":{"get":{"tags":["Feeds"],"summary":"Latest news feed","description":"Returns the latest Blerbz news items sorted chronologically.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Since"},{"$ref":"#/components/parameters/Until"}],"responses":{"200":{"description":"Latest feed page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2FeedsLatest"}},"/api/v2/feeds/trending":{"get":{"tags":["Feeds"],"summary":"Trending stories","description":"Returns velocity-based trending stories for a selected time window.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"window","in":"query","schema":{"type":"string","enum":["1h","6h","24h"],"default":"6h"},"description":"Trending calculation window."}],"responses":{"200":{"description":"Trending feed page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2FeedsTrending"}},"/api/v2/feeds/blerbz100":{"get":{"tags":["Feeds"],"summary":"BLERBZ100 daily rankings","description":"Returns the BLERBZ100 ranked news list with score context where available.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"name":"date","in":"query","schema":{"type":"string","format":"date"},"description":"Ranking date in YYYY-MM-DD format."}],"responses":{"200":{"description":"BLERBZ100 feed page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2FeedsBlerbz100"}},"/api/v2/feeds/topic/{slug}":{"get":{"tags":["Feeds"],"summary":"Topic feed","description":"Returns news items filtered by an AI-extracted topic slug.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Slug"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Topic feed page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2FeedsTopicBySlug"}},"/api/v2/feeds/source/{slug}":{"get":{"tags":["Feeds"],"summary":"Source feed","description":"Returns news items filtered by source slug.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Slug"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Source feed page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2FeedsSourceBySlug"}},"/api/v2/documents":{"get":{"tags":["Documents"],"summary":"List documents","description":"Returns paginated Blerbz documents with optional date and source filters.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Since"},{"$ref":"#/components/parameters/Until"},{"name":"sources","in":"query","schema":{"type":"string"},"description":"Comma-separated source slugs."},{"name":"minCompleteness","in":"query","schema":{"type":"number","minimum":0,"maximum":1},"description":"Minimum document completeness score."}],"responses":{"200":{"description":"Document page.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"meta":{"$ref":"#/components/schemas/PageMeta"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2Documents"}},"/api/v2/documents/{id}":{"get":{"tags":["Documents"],"summary":"Get document","description":"Returns a single Blerbz document by ID. Supports ETag conditional requests.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/DocumentId"},{"name":"If-None-Match","in":"header","schema":{"type":"string"},"description":"Optional ETag for conditional requests."}],"responses":{"200":{"description":"Document found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"304":{"description":"Document has not changed."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2DocumentsById"}},"/api/v2/documents/{id}/aliases":{"get":{"tags":["Documents"],"summary":"Document aliases","description":"Returns cross-source versions or aliases for a document.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/DocumentId"}],"responses":{"200":{"description":"Aliases found.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2DocumentsByIdAliases"}},"/api/v2/sync":{"get":{"tags":["Sync"],"summary":"Incremental sync","description":"Returns document changes since a cursor.","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Sync response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2Sync"}},"/api/v2/sync/status":{"get":{"tags":["Sync"],"summary":"Sync status","description":"Returns sync capability and status information.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Sync status.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2SyncStatus"}},"/api/v2/search":{"get":{"tags":["Search"],"summary":"Search news","description":"Searches Blerbz news documents and stories.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query."},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Search results.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeedItem"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2Search"}},"/ask":{"get":{"tags":["Agent Integration"],"summary":"Describe the Blerbz ask endpoint","description":"Returns endpoint metadata and example payloads for the public NLWeb-style Blerbz ask endpoint.","responses":{"200":{"description":"Ask endpoint description.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getAsk"},"post":{"tags":["Agent Integration"],"summary":"Ask Blerbz","description":"Returns an NLWeb-style answer grounded in Blerbz product, pricing, developer, or news-search context. Supports SSE when the request accepts text/event-stream.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}}},"responses":{"200":{"description":"NLWeb-style answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NlwebAnswer"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"postAsk","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/mcp":{"get":{"tags":["Agent Integration"],"summary":"Get MCP server card","description":"Returns the Blerbz MCP-style server card and tool/resource descriptions.","responses":{"200":{"description":"MCP server card.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getMcp"},"post":{"tags":["Agent Integration"],"summary":"Call Blerbz MCP JSON-RPC","description":"Supports initialize, tools/list, tools/call, resources/list, resources/read, and ping over JSON-RPC.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"postMcp","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v2/batch":{"get":{"tags":["Batch"],"summary":"Describe read-only batch endpoint","description":"Returns the read-only batch endpoint contract, allowed prefixes, and an example request.","responses":{"200":{"description":"Batch endpoint description.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2Batch"},"post":{"tags":["Batch"],"summary":"Execute read-only batch","description":"Executes up to 10 allowed GET requests in one read-only batch call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}}},"responses":{"200":{"description":"Batch response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"postApiV2Batch","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v2/sandbox/status":{"get":{"tags":["Sandbox"],"summary":"Sandbox and public test status","description":"Returns non-mutating public test-environment status for agent and integration smoke tests.","responses":{"200":{"description":"Sandbox status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxStatus"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV2SandboxStatus"}},"/api/v1/jobs":{"get":{"tags":["Agent Integration"],"summary":"Describe async job pattern","description":"Returns the BLERBZ async job endpoint contract, statuses, idempotency behavior, and related links.","responses":{"200":{"description":"Async job endpoint description.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV1Jobs"},"post":{"tags":["Agent Integration"],"summary":"Create async job","description":"Creates a retry-safe async job envelope for long-running BLERBZ search, analysis, or media operations.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobCreateRequest"}}}},"responses":{"202":{"description":"Async job accepted.","headers":{"Location":{"schema":{"type":"string"},"description":"URL for polling the job."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"postApiV1Jobs"}},"/api/v1/jobs/{job_id}":{"get":{"tags":["Agent Integration"],"summary":"Get async job","description":"Returns queued, running, succeeded, failed, or canceled job state.","parameters":[{"$ref":"#/components/parameters/JobId"}],"responses":{"200":{"description":"Async job state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"getApiV1JobsByJobid"},"delete":{"tags":["Agent Integration"],"summary":"Cancel async job","description":"Cancels a queued or running async job when cancellation is supported.","parameters":[{"$ref":"#/components/parameters/JobId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Async job canceled or already terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"deleteApiV1JobsByJobid"}},"/api/v1/search/jobs":{"post":{"tags":["Search"],"summary":"Create async search job","description":"Creates an async search job envelope for long-running or agent-scheduled search workflows.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobCreateRequest"}}}},"responses":{"202":{"description":"Search job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"postApiV1SearchJobs"}},"/api/v1/analysis/jobs":{"post":{"tags":["Agent Integration"],"summary":"Create async analysis job","description":"Creates an async analysis job envelope for longer AI story analysis workflows.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobCreateRequest"}}}},"responses":{"202":{"description":"Analysis job accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"},"default":{"$ref":"#/components/responses/Error"}},"operationId":"postApiV1AnalysisJobs"}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"parameters":{"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Maximum number of items to return."},"Cursor":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination or sync cursor."},"Since":{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Start timestamp filter."},"Until":{"name":"until","in":"query","schema":{"type":"string","format":"date-time"},"description":"End timestamp filter."},"Slug":{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Topic or source slug."},"DocumentId":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Blerbz document ID."},"JobId":{"name":"job_id","in":"path","required":true,"schema":{"type":"string"},"description":"BLERBZ async job ID."},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":255},"description":"Unique key for retrying the same mutation request safely. Reusing a key for a different request returns 409."}},"schemas":{"PageMeta":{"type":"object","properties":{"cursor":{"type":"string"},"hasMore":{"type":"boolean"},"count":{"type":"integer"},"generatedAt":{"type":"string","format":"date-time"}}},"FeedItem":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","example":"story"},"attributes":{"type":"object","properties":{"headline":{"type":"string"},"summary":{"type":"string"},"originalUrl":{"type":"string","format":"uri"},"sourceName":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"}}},"scoring":{"type":"object","additionalProperties":true}}},"Document":{"type":"object","properties":{"id":{"type":"string"},"attributes":{"type":"object","additionalProperties":true},"meta":{"type":"object","additionalProperties":true}}},"SyncResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string","enum":["created","updated","deleted"]},"updatedAt":{"type":"string","format":"date-time"}}}},"meta":{"$ref":"#/components/schemas/PageMeta"}}},"AskRequest":{"type":"object","properties":{"query":{"oneOf":[{"type":"string"},{"type":"object","properties":{"text":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":20}},"required":["text"]}]},"text":{"type":"string"},"q":{"type":"string"},"prefer":{"type":"object","properties":{"streaming":{"type":"boolean"},"limit":{"type":"integer","minimum":1,"maximum":20}}}}},"NlwebAnswer":{"type":"object","required":["_meta","results"],"properties":{"_meta":{"type":"object","properties":{"response_type":{"type":"string","enum":["answer"]},"response_format":{"type":"string"},"version":{"type":"string"},"grounding":{"type":"object","additionalProperties":true}}},"results":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"method":{"type":"string","examples":["initialize","tools/list","tools/call","resources/list","resources/read","ping"]},"params":{"type":"object","additionalProperties":true}}},"JsonRpcResponse":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"result":{"type":"object","additionalProperties":true},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}},"BatchRequest":{"type":"object","required":["requests"],"properties":{"requests":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"object","required":["path"],"properties":{"id":{"type":"string"},"method":{"type":"string","enum":["GET"],"default":"GET"},"path":{"type":"string","examples":["/pricing.md","/api/search"]},"query":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"BatchResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"ok":{"type":"boolean"},"status":{"type":"integer"},"path":{"type":"string"},"contentType":{"type":"string"},"body":{},"error":{"type":"object","additionalProperties":true}}}},"meta":{"type":"object","properties":{"count":{"type":"integer"},"maxRequests":{"type":"integer"},"readOnly":{"type":"boolean"}}}}},"SandboxStatus":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","enum":["sandbox-status"]},"id":{"type":"string"},"attributes":{"type":"object","additionalProperties":true},"links":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}}},"meta":{"type":"object","additionalProperties":true}}},"AsyncJobCreateRequest":{"type":"object","properties":{"type":{"type":"string","examples":["search","analysis"]},"input":{"type":"object","additionalProperties":true},"callback_url":{"type":"string","format":"uri","description":"Optional webhook callback URL when supported."}}},"AsyncJob":{"type":"object","required":["job_id","status","created_at","updated_at","expires_at"],"properties":{"job_id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"result_url":{"type":["string","null"],"format":"uri"},"result":{"type":["object","null"],"additionalProperties":true},"error":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}},"AsyncJobResponse":{"type":"object","properties":{"job_id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed","canceled"]},"result_url":{"type":["string","null"],"format":"uri"},"result":{"type":["object","null"],"additionalProperties":true},"error":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"links":{"type":"object","additionalProperties":{"type":"string"}},"data":{"type":"object","properties":{"type":{"type":"string","enum":["async-job"]},"id":{"type":"string"},"attributes":{"$ref":"#/components/schemas/AsyncJob"},"links":{"type":"object","additionalProperties":{"type":"string"}}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","type","request_id","docs_url"],"properties":{"code":{"type":"string","examples":["INVALID_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","IDEMPOTENCY_KEY_REUSED","RATE_LIMITED"]},"message":{"type":"string"},"type":{"type":"string","examples":["invalid_request_error","auth_error","rate_limit_error","idempotency_error","server_error"]},"param":{"type":["string","null"]},"request_id":{"type":["string","null"]},"docs_url":{"type":"string","format":"uri-reference"},"retry_after":{"type":["integer","null"]}}},"links":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}}}},"responses":{"BadRequest":{"description":"Request could not be parsed or validated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"API key is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The authenticated principal cannot access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"The request conflicts with the current state, including Idempotency-Key reuse for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnprocessableEntity":{"description":"The request is syntactically valid but semantically invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Request exceeded the current rate limit.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until another request should be attempted."},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Modern rate-limit request budget for the active window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Modern rate-limit remaining request count for the active window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp in seconds when the active window resets."},"RateLimit-Policy":{"schema":{"type":"string"},"description":"Modern rate-limit policy, such as 60;w=60."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Typed JSON error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"externalDocs":{"description":"Blerbz developer resources","url":"https://www.blerbz.com/nucleuzapi"},"x-api-versioning":{"currentVersion":"v2","deprecationPolicyUrl":"https://www.blerbz.com/docs/deprecation","apiVersioningUrl":"https://www.blerbz.com/docs/api-versioning","targetSupportWindow":"12 months after a successor version is documented, unless security or abuse constraints require faster remediation."},"x-webhooks":{"documentation":"https://www.blerbz.com/docs/webhooks","signatureHeaders":["BLERBZ-Signature","BLERBZ-Timestamp","BLERBZ-Event-Id"],"timestampToleranceSeconds":300}}