Federation Management

Federations are an entity that relates two or more indicies under an organization to allow cross-index (federated) search queries. Federation create/update/patch operations should only be used if you are using the self-hosted version of Searchcraft. Federation operations for Searchcraft Cloud are managed via the Vektron UI.

API Endpoints

• GET /federation Returns a list of all federations.
• POST /federation/:federation_name/search Returns search results data across all indices defined in a federation that match the query criteria. Query format is the same as search by index. See the search reference for more information.
• GET /federation/:federation_name Returns the entity for a federation.
• GET /federation/:federation_name/stats Returns document counts per index for a federation as well as the total document count.
• GET /federation/organization/:organization_id Returns a list of all federations for an organization. These federations must have read keys assigned to them that contain the organization ID.
• POST /federation Creates or updates an federation.
• PUT /federation/:federation_name Replace the current federation entity with an updated one. Expects a federation entity object in the request body. Same payload as POST /federation. If the federation does not exist you will receive a 404.
• DELETE /federation/:index_name Deletes a federation.

Auth Requirement

Requires an authentication key that has permissions to access the endpoint. The search endpoint requires a read key, all others require an admin key.

Federation creation

Payload to create a federation on a self-hosted instance of Searchcraft.

Example Federation

{
  "name": "4_galaxy_news_test",
  "friendly_name": "Galaxy News Test Federation",
  "created_by": "1",
  "last_modified_by": "1",
  "organization_id": "4",
  "index_configurations": [
    {
      "name": "index_1",
      "weight_multiplier": 1.0
    },
    {
      "name": "index_2",
      "weight_multiplier": 0.5
    },
    {
      "name": "index_3",
      "weight_multiplier": 2.0
    },
  ]
}

The created_by and last_modified_by fields are the ID of the user who created the federation and the last user who modified the federation. These are optional and not required. Similarly organization_id is the ID of the organization the federation belongs to. If you do not need to query by organization, you can omit this field.

Example CURL Request to create a federation

curl -X POST -H "Content-Type: application/json" -H "Authorization: yourkey" --data '{"name":"4_galaxy_news_test","friendly_name":"Galaxy News Test Federation","last_modified_by":"1","organization_id":"4","index_configurations":[{"name":"index_1","weight_multiplier":1},{"name":"index_2","weight_multiplier":0.5},{"name":"index_3","weight_multiplier":2}]}' http://yoursearchcrafthost/federation

Delete this example index

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: yourkey" http://yoursearchcrafthost/federation/4_galaxy_news_test/

Response for a successful creation or update

{
  "status": 200,
  "data": {
    "name": "4_galaxy_news_test",
    "friendly_name": "Galaxy News Test Federation",
    "created_at": "2025-04-15T19:34:00.388448873Z",
    "created_by": "1",
    "last_modified": "2025-04-15T19:34:00.388449316Z",
    "last_modified_by": "1",
    "organization_id": "4",
    "index_configurations": [
    {
      "name": "index_1",
      "weight_multiplier": 1.0
    },
    {
      "name": "index_2",
      "weight_multiplier": 0.5
    },
    {
      "name": "index_3",
      "weight_multiplier": 2.0
    },
    ]
  }
}

Response for a successful deletion

{
  "status": 200,
  "data": "federation deleted"
}