Add one or several documents to an index, retrieve a document by its internal id, and delete documents by id, by field term, by query, or all at once. Write transactions can be committed or rolled back. Requires an ingestion-tier authentication key.
openapi: 3.0.1
info:
title: Searchcraft API
description: >-
REST API for the Searchcraft developer search engine. Manage indexes and
their schemas, ingest and delete documents, run fuzzy/exact full-text and
federated search, and manage synonyms, stopwords, federations, access keys,
and usage measurement. Available as the managed Searchcraft Cloud service and
the self-hosted Searchcraft Core engine.
termsOfService: https://www.searchcraft.io/
contact:
name: Searchcraft
url: https://www.searchcraft.io/
version: '1.0'
servers:
- url: https://your-cluster.searchcraft.io
description: >-
Searchcraft Cloud cluster endpoint. Each Searchcraft Cloud account is
provisioned a unique cluster host; replace "your-cluster" with your cluster
subdomain. Self-hosted Searchcraft Core instances use their own host.
security:
- SearchcraftKey: []
paths:
/healthcheck:
get:
operationId: healthcheck
tags:
- Healthcheck
summary: Returns the health status of the Searchcraft server instance.
security: []
responses:
'200':
description: The server is healthy.
/index:
get:
operationId: listIndexes
tags:
- Indexes
summary: Returns a list of all indexes on the cluster.
responses:
'200':
description: A list of indexes.
post:
operationId: createIndex
tags:
- Indexes
summary: Creates a new index with a schema.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IndexSchema'
responses:
'200':
description: The index was created.
/index/stats:
get:
operationId: getAllIndexStats
tags:
- Indexes
summary: Returns document counts for every index on the cluster.
responses:
'200':
description: Stats for all indexes.
/index/{index}:
parameters:
- $ref: '#/components/parameters/IndexName'
get:
operationId: getIndex
tags:
- Indexes
summary: Returns the schema and configuration for a specific index.
responses:
'200':
description: The index schema.
put:
operationId: replaceIndex
tags:
- Indexes
summary: Replaces the entire configuration of an index.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IndexSchema'
responses:
'200':
description: The index was replaced.
patch:
operationId: updateIndex
tags:
- Indexes
summary: Applies a partial configuration update to an index.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The index was updated.
delete:
operationId: deleteIndex
tags:
- Indexes
summary: Deletes an index and all of its documents.
responses:
'200':
description: The index was deleted.
/index/{index}/stats:
parameters:
- $ref: '#/components/parameters/IndexName'
get:
operationId: getIndexStats
tags:
- Indexes
summary: Returns metadata and document counts for a specific index.
responses:
'200':
description: Stats for the index.
/index/{index}/documents:
parameters:
- $ref: '#/components/parameters/IndexName'
post:
operationId: addDocuments
tags:
- Documents
summary: Adds one or several documents to an index.
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
- type: array
items:
type: object
responses:
'200':
description: The documents were added.
delete:
operationId: deleteDocumentsByField
tags:
- Documents
summary: Deletes documents matching a field term.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The matching documents were deleted.
/index/{index}/documents/all:
parameters:
- $ref: '#/components/parameters/IndexName'
delete:
operationId: deleteAllDocuments
tags:
- Documents
summary: Deletes all documents from an index, preserving the index structure.
responses:
'200':
description: All documents were deleted.
/index/{index}/documents/query:
parameters:
- $ref: '#/components/parameters/IndexName'
delete:
operationId: deleteDocumentsByQuery
tags:
- Documents
summary: Deletes documents matching a query condition.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: The matching documents were deleted.
/index/{index}/documents/{document_id}:
parameters:
- $ref: '#/components/parameters/IndexName'
- name: document_id
in: path
required: true
description: The internal Searchcraft document id.
schema:
type: string
get:
operationId: getDocument
tags:
- Documents
summary: Retrieves a single document by its internal Searchcraft id.
responses:
'200':
description: The document.
delete:
operationId: deleteDocument
tags:
- Documents
summary: Deletes a specific document by its internal id.
responses:
'200':
description: The document was deleted.
/index/{index}/commit:
parameters:
- $ref: '#/components/parameters/IndexName'
post:
operationId: commitTransaction
tags:
- Transactions
summary: Commits the open write transaction for an index.
responses:
'200':
description: The transaction was committed.
/index/{index}/rollback:
parameters:
- $ref: '#/components/parameters/IndexName'
post:
operationId: rollbackTransaction
tags:
- Transactions
summary: Rolls back the open write transaction for an index.
responses:
'200':
description: The transaction was rolled back.
/index/{index}/search:
parameters:
- $ref: '#/components/parameters/IndexName'
post:
operationId: search
tags:
- Search
summary: Returns search results that match the query criteria.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Search results.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
/index/{index}/synonyms:
parameters:
- $ref: '#/components/parameters/IndexName'
get:
operationId: getSynonyms
tags:
- Synonyms
summary: Returns the synonyms configured for an index.
responses:
'200':
description: The synonyms for the index.
post:
operationId: addSynonyms
tags:
- Synonyms
summary: Adds synonyms to an index using the "synonym:original-term" format.
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
responses:
'200':
description: The synonyms were added.
delete:
operationId: deleteSynonyms
tags:
- Synonyms
summary: Deletes specific synonyms from an index.
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
responses:
'200':
description: The synonyms were deleted.
/index/{index}/synonyms/all:
parameters:
- $ref: '#/components/parameters/IndexName'
delete:
operationId: deleteAllSynonyms
tags:
- Synonyms
summary: Deletes all synonyms from an index.
responses:
'200':
description: All synonyms were deleted.
/index/{index}/stopwords:
parameters:
- $ref: '#/components/parameters/IndexName'
get:
operationId: getStopwords
tags:
- Stopwords
summary: Returns the custom stopwords configured for an index.
responses:
'200':
description: The stopwords for the index.
post:
operationId: addStopwords
tags:
- Stopwords
summary: Adds custom stopwords to an index.
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
responses:
'200':
description: The stopwords were added.
delete:
operationId: deleteStopwords
tags:
- Stopwords
summary: Deletes specific custom stopwords from an index.
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
responses:
'200':
description: The stopwords were deleted.
/index/{index}/stopwords/all:
parameters:
- $ref: '#/components/parameters/IndexName'
delete:
operationId: deleteAllStopwords
tags:
- Stopwords
summary: Deletes all custom stopwords from an index.
responses:
'200':
description: All stopwords were deleted.
/federation:
get:
operationId: listFederations
tags:
- Federation
summary: Returns a list of all federations.
responses:
'200':
description: A list of federations.
post:
operationId: createFederation
tags:
- Federation
summary: Creates a new federation grouping multiple indexes.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The federation was created.
/federation/{federation_name}:
parameters:
- $ref: '#/components/parameters/FederationName'
get:
operationId: getFederation
tags:
- Federation
summary: Returns the details of a specific federation.
responses:
'200':
description: The federation details.
put:
operationId: updateFederation
tags:
- Federation
summary: Updates a federation.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The federation was updated.
delete:
operationId: deleteFederation
tags:
- Federation
summary: Deletes a federation.
responses:
'200':
description: The federation was deleted.
/federation/{federation_name}/stats:
parameters:
- $ref: '#/components/parameters/FederationName'
get:
operationId: getFederationStats
tags:
- Federation
summary: Returns statistics for a federation.
responses:
'200':
description: Federation statistics.
/federation/{federation_name}/search:
parameters:
- $ref: '#/components/parameters/FederationName'
post:
operationId: federatedSearch
tags:
- Search
summary: >-
Returns search results across all indexes defined in a federation.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Federated search results.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
/measure/status:
get:
operationId: measureStatus
tags:
- Measure
summary: Returns whether the measurement system is enabled on this instance.
security: []
responses:
'200':
description: The measurement system status.
/measure/event:
post:
operationId: measureEvent
tags:
- Measure
summary: Records a single measurement event.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: The event was recorded.
/measure/batch:
post:
operationId: measureBatch
tags:
- Measure
summary: Records multiple measurement events in a single request.
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: object
responses:
'200':
description: The events were recorded.
/measure/dashboard/summary:
get:
operationId: measureSummary
tags:
- Measure
summary: >-
Returns summary analytics including searches, CTR, active users, and
popular terms.
responses:
'200':
description: Summary analytics.
/measure/dashboard/conversion:
get:
operationId: measureConversion
tags:
- Measure
summary: Returns conversion analytics with CTR chart data and session stats.
responses:
'200':
description: Conversion analytics.
/measure/dashboard/usage:
get:
operationId: measureUsage
tags:
- Measure
summary: Returns usage metrics for search query tracking and billing.
responses:
'200':
description: Usage metrics.
/auth/key:
get:
operationId: listKeys
tags:
- Authentication
summary: Lists all access keys on the cluster.
responses:
'200':
description: A list of access keys.
post:
operationId: createKey
tags:
- Authentication
summary: Creates a new access key with the given permissions.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKey'
responses:
'200':
description: The access key was created.
delete:
operationId: deleteAllKeys
tags:
- Authentication
summary: Deletes all access keys on the cluster.
responses:
'200':
description: All access keys were deleted.
/auth/key/{key}:
parameters:
- name: key
in: path
required: true
description: The access key value.
schema:
type: string
get:
operationId: getKey
tags:
- Authentication
summary: Retrieves the details of a specific access key.
responses:
'200':
description: The access key details.
post:
operationId: updateKey
tags:
- Authentication
summary: Updates a specific access key.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKey'
responses:
'200':
description: The access key was updated.
delete:
operationId: deleteKey
tags:
- Authentication
summary: Deletes a specific access key.
responses:
'200':
description: The access key was deleted.
components:
securitySchemes:
SearchcraftKey:
type: apiKey
in: header
name: Authorization
description: >-
Searchcraft access key passed directly in the Authorization header (no
"Bearer" prefix). Keys are tiered by permission: read (search), ingest
(document, synonym, stopword, transaction, and measure writes), and admin
(index, federation, and key management). Keys may be scoped to specific
indexes via allowed_indexes.
parameters:
IndexName:
name: index
in: path
required: true
description: The name of the index.
schema:
type: string
FederationName:
name: federation_name
in: path
required: true
description: The name of the federation.
schema:
type: string
schemas:
SearchRequest:
type: object
required:
- query
properties:
query:
description: >-
A query object, or an array of query objects, expressed in fuzzy,
exact, or dynamic mode.
oneOf:
- type: object
- type: array
items:
type: object
limit:
type: integer
default: 20
description: Maximum number of results to return.
offset:
type: integer
default: 0
description: Number of results to skip for paging.
order_by:
type: string
description: Field name to order results by.
sort:
type: string
enum:
- asc
- desc
default: desc
occur:
type: string
enum:
- should
- must
description: Boolean occurrence behavior for the query clause.
minimum_number_should_match:
type: integer
minimum: 0
SearchResponse:
type: object
properties:
status:
type: integer
example: 200
data:
type: object
properties:
hits:
type: array
items:
$ref: '#/components/schemas/Hit'
count:
type: number
time_taken:
type: number
facets:
type: array
items:
type: object
Hit:
type: object
properties:
doc:
type: object
document_id:
type: string
score:
type: number
source_index:
type: string
IndexSchema:
type: object
description: >-
Index definition including name, schema fields, search/index field
roles, and optional features such as stopwords and synonyms.
properties:
name:
type: string
schema:
type: object
AccessKey:
type: object
description: >-
An access key definition. The permission field is a bitmask where read
is 1, ingest is 15, and admin is 63; keys may be scoped to indexes and
associated with organizations, applications, or federations.
properties:
name:
type: string
permission:
type: integer
allowed_indexes:
type: array
items:
type: string
federation_name:
type: string
active:
type: boolean
tags:
- name: Healthcheck
- name: Indexes
- name: Documents
- name: Transactions
- name: Search
- name: Synonyms
- name: Stopwords
- name: Federation
- name: Measure
- name: Authentication