A small museum indexes catalog notes from approved collections and needs a custom field naming the source revision used for each searchable summary. Azure AI Search supports a Custom Web API skill that receives records from an indexer and returns derived fields. The key reliability question is not whether an endpoint can produce a plausible phrase; it is whether every output belongs to the correct source record and whether private records stay private. This hypothetical design shows a provenance enrichment that can be checked independently of an AI-generated answer.
Define the provenance field before adding a skill
List the fields that already identify a collection item: accession ID, source repository, approved revision, language, visibility and source-document checksum where permitted. Decide exactly what the custom skill should add—for example a normalized display citation or a reference to an approved revision record. A custom endpoint must not invent an authorization status or label a draft as approved. Establish the source of truth for provenance before writing code that transforms it.
Keep access-control fields under a trusted ingestion policy, not under a natural-language model that can be persuaded by text inside a scanned document. If a donor note says ‘share freely’ but the catalog access table marks it restricted, the permission table wins. Define null and error behavior for missing provenance rather than substituting the neighboring record’s identifier. Reviewers should be able to trace every derived field to the original indexed document.
Respect the values and recordId contract
Microsoft’s custom skill interface passes a JSON object with a values array. Each item has a recordId and a data object containing inputs. The skill’s response also uses values with the corresponding recordId and data, optionally including errors and warnings. The indexer uses this key to align records; output order alone is not an identity guarantee. Design the enrichment function as a per-record transformation with explicit type checking and deterministic source associations.
As a concrete example, if two records arrive as recordId ‘a1’ and ‘b5,’ a successful reply may return ‘b5’ before ‘a1’ while preserving the keys. A response with duplicate or missing recordId values is invalid for enrichment. Validate that each input record is represented exactly once, that the output field belongs to the matching accession record, and that a failed item cannot borrow data from the previous successful item.
Secure the HTTPS endpoint and inputs
A Custom Web API skill calls an HTTPS endpoint hosted by your application or function. Microsoft’s documentation describes authentication options including managed identity with Microsoft Entra ID. Use the least-privilege option supported by your environment; do not put archival secrets in source files or expose a general-purpose internal API to the public merely for indexing. Minimize the fields sent to the skill and keep sensitive note text out when the transformation needs only IDs and revision data.
Reject unexpected input schemas and long or malformed values. Keep the endpoint’s permissions narrower than the indexing service’s overall permissions, and verify logs do not capture whole restricted documents by default. If a service-generated label may be used in public search snippets, route it through an approval step. The custom skill framework does not waive consent, copyright or access requirements.
Process errors by record, not as false success
Microsoft documents per-record errors and warnings. A record that cannot be mapped to an approved source should return an explicit issue rather than an empty but apparently verified citation. A successful HTTP response is not sufficient if the JSON shape is invalid or the data object is missing required fields. The indexer history is part of the operational evidence; inspect it for failures, skipped skills and unmapped outputs.
Microsoft’s scaling guide distinguishes success status 200 and multi-status 207 when some records have errors; other HTTP errors can fail the batch. Only choose warnings for conditions where continuing would still produce a safe, clearly qualified record. If the provenance is required for publication, hold the affected document out of public results instead of treating a blank source as approval. A retry must preserve the same record identity.
Compare a broken join with a verified record
Draw three distinct stages: two source folders with different accession IDs, a broken response where a derived citation is attached to the wrong ID, and a corrected response that preserves recordId alignment and leads to a verified public result. This is a conceptual defect example, not observed Azure output. The comparison should make identity mismatch visible rather than showing three identical JSON cards.
An archive search interface should expose the original accession ID and version beside the derived description. Test retrieval of an object whose name resembles another object’s name but has a different number. Confirm that the enriched citation points to the right source record and that the search index can be rebuilt without renumbering source IDs. Any uncertainty about source mapping should cause a review flag rather than a guessed match.
Test on a separate skillset and sample
Build a small, permission-cleared fixture containing valid records, a missing revision, duplicates, malformed data and a restricted record. Test the endpoint directly for correct JSON, content type and status codes before involving the search indexer. Use an Azure AI Search debug session to review representative documents, but recognize that a single debugged document cannot prove correctness across an entire index.
Microsoft’s guidance identifies skill batchSize, degreeOfParallelism and timeout as tuning parameters. Adjust them using recorded application and indexer behavior, not assumptions about optimum throughput. Start conservatively, inspect errors and measure actual workload performance before scaling. If a record consistently fails, preserve the failure reason; do not repeatedly retry it without checking whether the source data or endpoint contract is wrong.
Check access filtering after enrichment
Rebuild a test index containing both publicly approved and restricted materials. Apply the application’s authorization filters before returning any search result, facet or snippet. Confirm that adding a provenance field cannot change a restricted record into a public one. Test by querying a distinctive term that exists only in a restricted source and ensure that the public endpoint returns no identifying metadata.
Audit enrichment results separately from retrieval permissions. A perfectly matching recordId can still belong to a restricted item. Conversely, a public record whose provenance is broken should be held for review, not silently hidden from staff who need to repair the index. Keep the raw source, derived enrichment and access decisions in appropriately separated logs.
Release the skill with an accountable rollback
Version the skill contract, code, input mapping, output mapping and indexed schema together. Record who reviewed the source permissions and which test fixtures were used. Deploy first to a staging index and compare expected accession IDs, missing-value behavior and restricted-result leakage against the approved baseline. Preserve a previous index or reversible deployment path so a mapping regression can be corrected.
The API can enrich records, but it cannot certify that a museum has rights to publish them. The sample objects and diagrams here are fictional, not screenshots or a live service evaluation. Before production, check current Microsoft documentation, endpoint authentication, response limits and cost, then have collection staff verify the citations and access policy for the affected records.
How We Research
For this November 2026 article, we examined named, official documentation: Microsoft custom skill interface; Microsoft custom Web API skill; Microsoft custom skill scale and management; Microsoft indexer troubleshooting. We cross-checked response shapes, feature boundaries, and stated limitations, then built a clearly hypothetical nonprofit example to explain manual verification and permission controls. This was documentation-based editorial research only: we did not process real records, run vendor experiments, measure success rates or imply that machine-generated text is approved. The original teaching diagrams are schematic, not product screenshots or tested outcomes. Recheck current API documentation, pricing, region availability, input rights, and internal release policies before implementation.
Frequently Asked Questions
Yes, provided each returned item preserves the matching unique recordId.
Microsoft documents those as invalid records that are not enriched correctly.
No. Validate JSON shape, field mappings, warnings and source identity.
It should not; authorization must come from trusted policy and be enforced in retrieval.
No. It helps diagnose a sample; test multiple variants and the full access boundary before release.