canonical: https://jentic.com/apis/azure.com/searchserviceclient # Microsoft Azure SearchServiceClient Jentic publishes the only available OpenAPI specification for SearchServiceClient, keeping it validated and agent-ready. The Azure Cognitive Search data plane management API defines the indexes, indexers, datasources, skillsets, and synonym maps that power a search service. Agents can create or update an index schema, configure an indexer to pull documents from a datasource, attach a skillset for AI enrichment, and trigger or reset indexer runs. It complements SearchIndexClient by configuring the structures that queries run against. ## For AI agents Define and manage Azure Cognitive Search indexes, indexers, datasources, skillsets, and synonym maps that drive document ingestion and query behaviour. ## Scope Does not query documents, provision the search service, or manage admin keys - use for defining indexes, indexers, datasources, skillsets, and synonym maps only. ## Capabilities - Create or update an index schema with fields, analyzers, and scoring profiles - Configure a datasource pointing at Azure SQL, Cosmos DB, Blob Storage, or Table Storage - Define an indexer that pulls documents from a datasource into an index on a schedule - Attach a skillset for AI enrichment such as OCR, key phrase extraction, or entity recognition - Trigger, reset, and inspect status of indexer runs to debug ingestion failures - Manage synonym maps to expand queries with controlled vocabulary - Analyze how text is tokenised by an index analyzer before changing the schema ## Use cases ### Index Schema Definition for a New Application Search teams use SearchServiceClient to create an index whose fields, analyzers, and scoring profiles match the application's data model. The PUT /indexes('{indexName}') endpoint accepts the full schema and applies it atomically. Adding fields later is allowed; changing field types requires a new index version. The analyze endpoint lets developers preview tokenisation before committing schema changes. Example prompt: PUT /indexes('orders') with a body defining fields title (Edm.String, searchable), price (Edm.Double, filterable), and category (Edm.String, facetable) ### Scheduled Ingestion via Indexers and Datasources When source data lives in Azure SQL, Cosmos DB, or Blob Storage, an indexer pulls changes on a schedule and pushes them into the index. The datasource resource holds the connection details and change tracking policy, the indexer resource holds the schedule and field mappings, and search.run triggers an immediate execution. Status reports per-run document counts and any failed records. Example prompt: PUT a datasource of type cosmosdb with connectionString, then PUT an indexer linking it to the orders index, then POST search.run to trigger immediate execution ### AI Enrichment Pipelines via Skillsets Skillsets attach cognitive enrichment to an indexer, performing OCR on images, key phrase extraction on text, language detection, or custom Web API skills. The skillset PUT defines the chain of skills and their input output mappings, and the indexer references the skillset to invoke enrichment at ingestion. The output fields land in the index and become searchable like any other field. Example prompt: PUT a skillset with three skills (OCR, key phrase extraction, language detection) and reference its name from the indexer's skillsetName property ### Indexer Failure Forensics When an indexer reports failures, an operator needs to see which documents failed and why. The search.status endpoint returns the last few execution records including item counts, failed item details, and the start and end timestamps for each run. Combined with search.reset, this lets the agent rerun a failed window after fixing the upstream data. Example prompt: GET indexers('orders-indexer')/search.status and return the lastResult.errors array containing the document keys that failed ### Agent-Driven Index Setup via Jentic Through Jentic, an MLOps agent can search for create azure search index, load the index PUT schema, populate field definitions from an upstream data contract, and execute the call with a managed admin key. The same flow chains into datasource and indexer creation so the agent can stand up a full ingestion pipeline in a single workflow. Example prompt: Search Jentic for create azure search index, load the index PUT schema, execute it with a fields array, then load and execute datasource and indexer PUTs to complete the pipeline ## Key endpoints | Method | Path | Description | | --- | --- | --- | | PUT | /indexes('{indexName}') | Create or update an index schema | | PUT | /indexers('{indexerName}') | Create or update an indexer | | POST | /indexers('{indexerName}')/search.run | Run an indexer on demand | | GET | /indexers('{indexerName}')/search.status | Get indexer execution status | | POST | /indexers('{indexerName}')/search.reset | Reset an indexer for full reindex | | PUT | /datasources('{dataSourceName}') | Create or update a datasource | | PUT | /skillsets('{skillsetName}') | Create or update a skillset | | POST | /indexes('{indexName}')/search.analyze | Analyze tokenisation for a string | ## Key resources - **Indexes** — Define the searchable schema, fields, analyzers, and scoring profiles - **Indexers** — Schedule and run document ingestion from datasources into indexes - **Datasources** — Connection definitions to Azure SQL, Cosmos DB, Blob Storage, and Table Storage - **Skillsets** — AI enrichment chains for OCR, key phrase extraction, entity recognition - **SynonymMaps** — Controlled vocabulary used to expand queries against an index ## Why Jentic - **Setup:** Wiring SearchServiceClient by hand means selecting the right per-service host ({searchServiceName}.search.windows.net), sending the admin api-key header, and learning the separate schemas for indexes, indexers, datasources, and skillsets. Through Jentic you install once, import SearchServiceClient from the API Directory, store the admin api-key once, and your agent calls it. - **Permission scoping:** SearchServiceClient puts the index, indexer, and datasource names in the URL path (/indexes('{indexName}'), /indexers('{indexerName}')), so a rule can pin your agent to the resources it manages. You choose the operations it may call, so you can allow triggering an indexer run while withholding index or datasource deletion unless you add it. - **Credential handling:** Your Azure Cognitive Search admin api-key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create an Azure Cognitive Search index' or 'set up an indexer that pulls from Cosmos DB', and Jentic returns the matching SearchServiceClient operation with its input schema across indexes, indexers, datasources, skillsets, and synonym maps. ## Related APIs - **Azure SearchIndexClient** — Data plane API that queries the indexes you define here - **Azure SearchManagementClient** — ARM control plane that provisions the search service this API runs on - **Algolia Search API** — Hosted search-as-a-service alternative outside the Azure stack ## FAQ ### Why is there no official OpenAPI spec for SearchServiceClient? Microsoft Azure does not publish a unified OpenAPI specification for the Cognitive Search data plane management surface. Jentic generates and maintains this spec so that AI agents and developers can call SearchServiceClient via structured tooling. It is validated against the live search.windows.net data plane and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does SearchServiceClient use? It uses an admin api-key in the api-key request header. Admin keys are required for write operations on indexes, indexers, datasources, and skillsets. Jentic stores the admin key in its vault so the agent never holds the raw value. ### Can I attach AI enrichment to an indexer with this API? Yes. PUT a skillset resource via /skillsets('{name}') with the chain of cognitive skills, then reference its name in the indexer's skillsetName property. The indexer invokes the skillset on each document ingested and stores enriched fields back into the target index. ### How do I trigger an indexer run on demand? POST to /indexers('{indexerName}')/search.run. The service starts an indexer execution immediately, separate from the scheduled cadence. Status appears in /indexers('{indexerName}')/search.status alongside scheduled runs. ### What are the rate limits for SearchServiceClient? Throughput is bound by the search service tier and the number of replicas and partitions provisioned. Heavy schema or skillset writes are uncommon and the limits are generous for those operations. Throttled requests return HTTP 503 with a Retry-After header. ### How do I set up an indexer through Jentic? Search Jentic for create azure search indexer, call client.load on the indexer PUT operation to receive its input schema, then call client.execute with a body that references your datasource and target index. Jentic injects the api-key header and returns the created indexer. ### Can I limit what my agent is allowed to do with the SearchServiceClient API? Yes. Because Jentic One runs self-hosted, you write the rules that decide which SearchServiceClient operations your agent may call and which credentials it uses. Since the API puts resource names in the URL path, such as /indexes('{indexName}') and /indexers('{indexerName}'), you can pin the agent to the specific indexes, indexers, and datasources it manages. You can also allow safe actions like triggering an indexer run or checking its status while withholding index, datasource, or skillset deletion until you grant it, and the admin api-key is injected at execution time so the agent never handles the raw value.