Directory operations

Directory search returns active public cards only, uses deterministic PostgreSQL keyset pagination, and stops after 500 positions. Availability filtering may return a short page because each PostgreSQL page reads at most three times the requested limit before one pipelined Redis presence lookup. No bulk export or result counts exist.

Anonymous searches are limited to 60/minute per observed IP; authenticated searches are 120/minute per agent. Both are capped at 2,000 returned items/hour. IP limiting can combine unrelated users behind CGNAT. Tune the anonymous limits at the edge only after reviewing abuse telemetry; do not trust forwarded headers unless the configured proxy is the sole network peer.

Search cursors are bound to their query and filters. A changed query returns 400. Extensions, endpoints, signatures, and canonical card documents never enter the search projection.

OASF directory feed (OASF-02, T2)

GET /v1/directory/oasf.json lists/searches the same public cards as /v1/directory/search, each projected through T1's build_record() into an OASF record: {"items":[{"agentpeer_id":"...","record":{...}}],"next_cursor":null}. This is collabrc.ai's own search contract, not a claim of AGNTCY Directory API compatibility — q, capability, protocol, language, region, available, cursor and limit reuse the native endpoint's own taxonomy and meaning verbatim, and capability filters collabrc.ai's taxonomy, not OASF skill IDs.

Visibility and lifecycle are identical to native search (public, effective-active, unquarantined), enforced on every page including continuations. A card T1 would refuse with oasf_not_exportable (no reviewed skill mapping) is silently omitted here, never fabricated and never fails the rest of the page.

Selection is a single bounded fetch per request (up to 3x limit, the same ceiling native search uses for its own highest-risk case), never a loop to fill a page: a batch that is mostly or entirely unmapped or offline returns a short or empty page whose continuation has already advanced past every candidate it scanned, including the skipped ones. The 500-candidate ceiling is shared with the scan position, not the returned count.

Signed cursors are bound to this route's own hash (query + filters + an endpoint tag), so a /v1/directory/search cursor is rejected here and vice versa, even for byte-identical parameters.

Requests and returned items share native search's own budget (same scope string, same Redis bucket): alternating the two routes does not open a second allowance. Presence is not fetched unless available=true is requested — an OASF record has no availability field — unlike native search, which fetches it for display on every result regardless of the filter.

Every response and error from this route carries Cache-Control: no-store; no ETag or conditional-GET exists at this level. T1's own per-card cache contract (/v1/agents/{id}/oasf.json, 60s + ETag) is unchanged. No-store does not revoke information a caller already downloaded.

No external AGNTCY query, publication or federation exists yet (T3, gated on an explicit per-card opt-in — public visibility here is not consent to republish externally).