---
title: "Search published Spanish legal entities"
method: GET
path: "/api/v1/search"
tags: ["Search"]
---

# Search published Spanish legal entities

`GET /api/v1/search`

Corporate-only search over the immutable company_public_v2 projection. It resolves an exact corporate CIF, an exact canonical/safe-alias slug, or a bounded name-prefix pool. DNI/NIE, malformed identifier-shaped input and ambiguous/quarantined CIFs return zero items; there is no raw companies/search_idx or disk-index fallback.

## Query parameters

- `q` string, required
- `limit` integer
- `offset` integer

## Headers

- `If-None-Match` string

## Response `200`

Search results

- SearchResponse
  - `query` string, required
  - `count` integer, required
  - `offset` integer
  - `items` CompanySearchItem[], required
    - `slug` string, required
    - `name` string, required
    - `cif` string, required
    - `acts_count` integer, required
    - `last_seen` string, nullable
    - `province` string, nullable
    - `cnae_code` string, nullable
    - `cnae_section` string, nullable
    - `capital_cents` integer, nullable
    - `first_seen` string, nullable
    - `matched_alias` string — Present only when an exact safe alias was matched; slug is always canonical.
    - `aliases` string[]

## Other responses

- `304` — The admitted corporate search projection and exact normalized query have not changed.
- `400` — Invalid request
- `422` — The query is lexically valid but outside a documented numeric or length bound, or uses an unsupported indexed combination.
- `429` — Rate limit exceeded
- `503` — The public read failed closed because its legal source catalog, subject classification, bounded projection, database helper or required artifact is unavailable. Clients must not infer an empty result.

---

[API](https://skmtc.net/openmercantil/apis/openmercantil-public-api.md) · [All operations](https://skmtc.net/openmercantil/apis/openmercantil-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmercantil/openmercantil-public-api/revisions/996f96a11758/schema)