> For the complete documentation index, see [llms.txt](https://developer.abacum.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.abacum.ai/api-reference/search/search.md).

# Search

Search variables, models, tables, spaces, scenarios and datasets by name. Matching is fuzzy: results are ranked by name similarity, best first.

Any valid token can call this endpoint, and results only include resources the token's user can access. Members can search only `variables`, `spaces` and `tables`.

* With a single `type`, results are paginated with `page` and `page_size`.
* With `type=all`, the response groups up to 5 results per entity type, skips types with no match, and is not paginated: `page` and `page_size` are ignored. For a Member, `all` covers variables, spaces and tables only.

```json
{"openapi":"3.0.0","info":{"title":"Abacum public API","version":"1.0.0"},"tags":[{"name":"Search","description":"Search variables, models, tables, Spaces, scenarios and datasets by name."}],"servers":[{"url":"https://api.abacum.io","description":"Prod environment"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An access token from the token endpoint, sent as `Authorization: Bearer <access_token>`. Use it to try an endpoint from this page. The token carries the permissions of its user, so use a user with the lowest role that fits the call."}},"schemas":{"SearchResult":{"type":"object","required":["id","name","type","similarity_score","parents"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the matching resource."},"name":{"type":"string","description":"Name of the matching resource."},"type":{"type":"string","enum":["variable","model","table","space","scenario","dataset"],"description":"Kind of the matching resource."},"similarity_score":{"type":"number","format":"float","minimum":0,"maximum":1,"nullable":true,"description":"Name similarity to `q`, from 0 to 1. Higher is a closer match."},"is_ai_priority":{"type":"boolean","description":"Present on variable results only."},"parents":{"type":"array","description":"Where the result lives. For a variable, its model (Admins only) and the tables and spaces that contain it. Empty when the result has no container.","items":{"$ref":"#/components/schemas/SearchParent"}}}},"SearchParent":{"type":"object","required":["id","name","type","parents"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the container."},"name":{"type":"string","description":"Name of the container."},"type":{"type":"string","enum":["model","table","space","version"],"description":"Kind of the container."},"parents":{"type":"array","description":"The containers of this container, in the same shape.","items":{"$ref":"#/components/schemas/SearchParent"}}}},"DetailMessage":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string"}}}},"responses":{"TooManyRequests20PerMinute":{"description":"Rate limit exceeded: 20 requests per minute for the same user and URL. Wait the number of seconds in the `Retry-After` header, then retry.","headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}},"X-Request-ID":{"$ref":"#/components/headers/XRequestID"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailMessage"}}}},"InternalServerError":{"description":"An unexpected error on our side. The response has an empty body. Repeat the request, and contact support if it keeps failing.","headers":{"X-Request-ID":{"$ref":"#/components/headers/XRequestID"}}}},"headers":{"XRequestID":{"description":"Identifier of this request. Quote it when you contact support so they can find the exact request. A server-side client can set it by sending an `X-Request-ID` request header of 1 to 64 characters from `A-Za-z0-9_-`; any other value is replaced by a generated one. Browsers can read this header but cannot send their own. The value identifies a request for support, but it is not proof that only one request used it.","schema":{"type":"string"}}}},"paths":{"/public-api/search":{"get":{"summary":"Search","description":"Search variables, models, tables, spaces, scenarios and datasets by name. Matching is fuzzy: results are\nranked by name similarity, best first.\n\nAny valid token can call this endpoint, and results only include resources the token's user can access.\nMembers can search only `variables`, `spaces` and `tables`.\n\n- With a single `type`, results are paginated with `page` and `page_size`.\n- With `type=all`, the response groups up to 5 results per entity type, skips types with no match, and is not\n  paginated: `page` and `page_size` are ignored. For a Member, `all` covers variables, spaces and tables only.\n","operationId":"search","tags":["Search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":3},"description":"Text to search for. Minimum 3 characters."},{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["variables","models","tables","spaces","scenarios","datasets","all"]},"description":"Entity type to search, or `all` to search every type the user can search."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number (1-indexed). A value that is not a positive integer, or that is beyond the last page, returns `404`. Ignored when `type=all`."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Items per page. A value above 100 is capped at 100, and a value that is not a positive integer is ignored, so the default applies. Ignored when `type=all`."}],"responses":{"200":{"description":"Search results. The shape depends on `type`:\n\n- A single type returns a list in `data` and pagination details in `metadata.pagination`.\n- `all` returns an object in `data`, keyed by result type, and an empty `metadata`.\n","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Response for a single `type`.","required":["data","metadata"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}},"metadata":{"type":"object","required":["pagination"],"properties":{"pagination":{"type":"object","required":["count","page","page_size","total_pages","next","previous"],"properties":{"count":{"type":"integer","description":"Total number of matches."},"page":{"type":"integer"},"page_size":{"type":"integer"},"total_pages":{"type":"integer"},"next":{"type":"string","format":"uri","nullable":true},"previous":{"type":"string","format":"uri","nullable":true}}}}}}},{"type":"object","description":"Response for `type=all`.","required":["data","metadata"],"properties":{"data":{"type":"object","description":"Up to 5 results per result type, keyed by result type (`variable`, `model`, `table`, `space`, `scenario`, `dataset`). Types with no match are omitted.","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}},"metadata":{"type":"object","maxProperties":0}}}]}}}},"400":{"description":"Invalid request: `q` is missing or shorter than 3 characters, or `type` is missing or not one of the allowed values. The body maps each invalid parameter to a list of messages.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"403":{"description":"One of two causes:\n\n- The bearer token is missing, invalid or expired. The response has an empty body.\n- The token's user is a Member and `type` is `models`, `scenarios` or `datasets`.\n\nThe API answers `403` for a bad token, not `401`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailMessage"}}}},"404":{"description":"Not found - `page` is not a valid page number or is beyond the last page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailMessage"}}}},"429":{"$ref":"#/components/responses/TooManyRequests20PerMinute"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```