> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tattoo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Unified search across artists, studios, and designs.

<Note>
  **Posture:** Authenticated internal beta. The caller must resolve to a mapped TattooAPI actor before access is granted.
</Note>

Canonical request URL: `https://api.tattooapi.com/api/v1/search`.

## Auth

The current runtime requires authentication for `GET /search`.

```bash theme={"dark"}
curl "$TATTOO_API_BASE_URL/search?q=traditional&type=studio&limit=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Query Parameters

| Parameter                         | Type    | Notes                                  |
| --------------------------------- | ------- | -------------------------------------- |
| `q`                               | string  | Optional search text                   |
| `type`                            | string  | `artist`, `studio`, `design`, or `all` |
| `city`, `state`, `country`        | string  | Location filters                       |
| `latitude`, `longitude`, `radius` | number  | Geographic filters                     |
| `styles`, `specialties`           | string  | Comma-separated filters                |
| `min_rating`                      | number  | Minimum rating                         |
| `verified_only`                   | boolean | Only verified results                  |
| `page`, `limit`                   | number  | Pagination                             |
| `sort_by`, `sort_order`           | string  | Result ordering                        |
| `include_facets`                  | boolean | Include facet counts                   |

## Response Shape

```json theme={"dark"}
{
  "success": true,
  "data": {
    "results": [
      {
        "type": "studio",
        "id": "uuid",
        "name": "Ink Masters Studio",
        "description": "Premier tattoo studio",
        "rating": 4.8,
        "review_count": 127,
        "verified": false,
        "styles": [],
        "specialties": [],
        "location": {
          "city": "Los Angeles",
          "state": "CA",
          "country": "United States"
        },
        "relevance_score": 19.9,
        "provenance": {
          "recordState": "normalized",
          "sourceType": "directory_scrape",
          "originAuthority": "system_inference",
          "sourceUrl": null,
          "sourceCollectedAt": null,
          "licenseStatus": "rights_unknown",
          "consentLevel": "recommendation_only",
          "sourceNotes": []
        },
        "trust": {
          "verificationStatus": "unverified",
          "approvalStatus": "draft",
          "visibility": "public",
          "culturalSensitivityLevel": "none",
          "trustNotes": []
        }
      }
    ],
    "total": 1,
    "pagination": {
      "page": 1,
      "limit": 20,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  }
}
```

<Note>
  Search is one of the first endpoints that should become ontology-aware in practice. The current runtime shape is still tied to legacy tables, but the docs now describe that shape accurately.
</Note>