Quickstart

Start with a public studio read, then add approved credentials for authenticated endpoints.

What You Can Do Today

Lane	Who it is for	What works now	Auth
Public reads	External builders and docs readers	Health and studio discovery	None
Authenticated beta reads	TattooAPI team, mapped owners, controlled SDK tests	Search, artists, portfolios, designs, owner creative reads	Approved credential plus TattooAPI actor mapping
Portfolio submissions	Approved intake integrations	Media submissions, upload completion, and review status	Partner machine key stored in a secret manager

Public writes are blocked. Private workers cannot publish public surfaces, mutate canonical records, or bypass human review.

Base URL

Use the canonical public API base URL:

export TATTOO_API_BASE_URL=https://api.tattooapi.com

Resource reads require api-version=2026-07-01-preview. Health checks are unversioned. Owner reads use explicit /api/v1/me/* paths; do not add /api/v1 to this base URL.

1. Check Health

Use public liveness for basic availability:

curl "$TATTOO_API_BASE_URL/health/live"

Expected shape:

{
  "status": "ok",
  "timestamp": "2026-04-20T12:00:00.000Z",
  "uptime": 1234.56,
  "service": "tattoo-api"
}

Use production readiness before relying on intake, private worker, or approved portfolio workflows:

curl "$TATTOO_API_BASE_URL/health/ready"

Inspect the returned status: ready, degraded, or blocked. A successful health check does not prove that a complete portfolio workflow is ready.

2. Get Access

Public users do not need auth for health or studio discovery. Authenticated internal beta access uses approved partner credentials. Team members use bearer tokens, and machine or private worker tools use partner API keys.

Legacy registration and login routes are not available for onboarding. Get approved credentials through the partner portal.

For authenticated beta reads, use the partner portal:

Sign in at https://partners.tattoo.dev.
Select your approved organization.
Create a key with the permissions your integration needs.
Confirm the key is mapped by TattooAPI.
Open the Mintlify playground on https://docs.tattoo.dev and run your first request.

For human sessions, send:

Authorization: Bearer YOUR_ACCESS_TOKEN

For machine, server, SDK, and private worker calls, prefer:

X-API-Key: YOUR_PARTNER_API_KEY

Response semantics are intentionally simple:

401 means the credential is missing or invalid.
403 means the credential lacks an active TattooAPI actor mapping, a required permission, or access to the requested resource.
410 means a legacy local API-key route is retired.

3. Search the Dataset

GET /search currently requires authenticated internal beta access.

curl "$TATTOO_API_BASE_URL/search?api-version=2026-07-01-preview&q=traditional&type=studio&limit=5" \
  -H "X-API-Key: YOUR_PARTNER_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?api-version=2026-07-01-preview&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

For portfolio intake, identity evidence is not KYC. unmatched, phone_matched, review_required, and verified_by_operator describe review evidence only; they do not claim legal identity verification. Next:

Start Here

Integration Guides

Quickstart

Quickstart

What You Can Do Today

Base URL

1. Check Health

2. Get Access

3. Search the Dataset

4. List Studios

5. Understand Trust

​Quickstart

​What You Can Do Today

​Base URL

​1. Check Health

​2. Get Access

​3. Search the Dataset

​4. List Studios

​5. Understand Trust

Quickstart

What You Can Do Today

Base URL

1. Check Health

2. Get Access

3. Search the Dataset

4. List Studios

5. Understand Trust