Skip to main content

​
Base URL

Use your deployed API base URL, or the current local runtime during development: 
export TATTOO_API_BASE_URL=https://api.tattooapi.com/v1
For local development against this repo: 
export TATTOO_API_BASE_URL=http://localhost:3001/api/v1
The canonical public API host is api.tattooapi.com. api.tattoo.co may remain as a marketplace/internal alias for tattoo.co-owned applications, but docs and SDKs should prefer api.tattooapi.com.

​
1. Check Health

curl "$TATTOO_API_BASE_URL/health"
Expected shape: 
{
  "status": "healthy",
  "timestamp": "2026-04-20T12:00:00.000Z",
  "version": "v1",
  "uptime": 1234.56,
  "environment": "development"
}

​
2. Register and Login

Public users do not need auth for health or studio discovery. Authenticated internal beta access now uses WorkOS. Team members use WorkOS/AuthKit bearer tokens, and machine or agent tools use WorkOS API Keys.
The legacy POST /auth/register and POST /auth/login routes may still exist in the runtime, but they are not the default path for new internal beta access.
For internal beta reads, attach one of: 
Authorization: Bearer YOUR_WORKOS_TOKEN
or: 
X-API-Key: YOUR_WORKOS_API_KEY

​
3. Search the Dataset

GET /search currently requires WorkOS-authenticated internal beta access. 
curl "$TATTOO_API_BASE_URL/search?q=traditional&type=studio&limit=5" \
  -H "X-API-Key: YOUR_WORKOS_API_KEY"
The response uses a success wrapper: 
{
  "success": true,
  "data": {
    "results": [],
    "total": 0,
    "pagination": {
      "page": 1,
      "limit": 5,
      "total_pages": 0,
      "has_next": false,
      "has_prev": false
    }
  }
}

​
4. List Studios

GET /studios is the current public discovery endpoint. 
curl "$TATTOO_API_BASE_URL/studios?city=Los%20Angeles&limit=5"
Unlike search, the current studios endpoint still uses the legacy paginated wrapper: 
{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 0,
    "totalPages": 0,
    "hasNext": false,
    "hasPrev": false
  },
  "error": null
}

​
5. Understand Trust

Before you build on top of the current data, load the trust model:
  • recordState tells you if a record is raw, normalized, curated, verified, or deprecated
  • verificationStatus tells you how much trust has been established
  • licenseStatus and consentLevel tell you what kinds of downstream use are allowed
Next: