---
title: "Search and Retrieval APIs"
description: "Exposing a documented query surface so agents can find your product's data instead of scraping it"
url: "https://agentsurface.dev/docs/retrievability/search-and-retrieval-apis"
index: https://agentsurface.dev/llms.txt
lastVerified: 2026-10-29
lastModified: 2026-10-29T11:29:43.000Z
---

Agents need a callable way to search or retrieve your product's data - support articles, catalog items, records, documents - that returns structured, attributable results. A search box built for a browser is not that surface: it returns HTML, not a contract an agent can call directly.

## What a retrieval endpoint needs [#what-a-retrieval-endpoint-needs]

- **A documented query parameter set.** Free-text query, structured filters, sort order, and result shape belong in your API spec, not only in UI behavior. See [OpenAPI for Agents](https://agentsurface.dev/docs/api-surface/openapi-for-agents).
- **A stable result schema.** Every result needs an identifier, a title or summary, enough content to be useful without a follow-up call, and a canonical URL or resource reference. Returning bare IDs forces the agent into N follow-up calls to resolve what it just found.
- **Relevance signals.** If your endpoint ranks results, expose the score or rank alongside each item so an agent can compare the top result with the tenth. A relevance score is not calibrated confidence or a probability that the result is true. Document the metric behind it (for example BM25, cosine similarity or a reranker score), its direction (higher is better, or lower is), and whether scores are comparable across queries, or only within one result list. If you can't make that promise, expose rank instead.
- **A documented empty-result and no-match behavior.** Distinguish "zero results because nothing matched" from "the query was invalid." An agent needs to know whether to retry with a broader query or stop.

## Result shape example [#result-shape-example]

```json
{
  "results": [
    {
      "id": "doc_9f21",
      "title": "Rotating an API key",
      "snippet": "Go to Settings → API Keys → Rotate. The old key remains valid for 24 hours...",
      "score": 0.91,
      "url": "https://docs.example.com/api-keys/rotate",
      "updated_at": "2026-08-02T00:00:00Z"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjEwfQ",
  "total_estimate": 47
}
```

Every field here answers a question the agent otherwise has to guess at: what did I find, how well does it match the query (by a score whose meaning you document), where did it come from, is there more, and how much more.

## Structured versus free-text retrieval [#structured-versus-free-text-retrieval]

Not every retrieval need is a search box. Agents often need typed queries over structured data: "orders placed after March 1 in status `shipped`." Expose this as filtered list endpoints or a query language (SQL-like, GraphQL, or structured filter parameters) rather than forcing every question through a full-text search index that was tuned for prose. See [Retrieval and Job Contracts](https://agentsurface.dev/docs/api-surface/retrieval-and-job-contracts) for pagination and response-schema mechanics that apply to both.

## What not to duplicate here [#what-not-to-duplicate-here]

Chunking prose so an agent can retrieve a self-contained answer from it is a content-authoring concern, covered in [Content Structure](https://agentsurface.dev/docs/discovery/content-structure). Building a vector index or embeddings pipeline to power semantic search over your own corpus is an implementation choice; the current best-practice patterns for that live in [Agent Retrieval](https://agentsurface.dev/docs/agent-retrieval) as inventory, not as a requirement of this dimension. The score covers whether the capability is reachable, documented, and returns agent-usable results; which retrieval technology sits behind it is out of scope.