Goondex/docs/API_QUICK_REFERENCE.md

Goondex API Quick Reference

Quick lookup for all API endpoints

Base URL

http://localhost:8080

---

Search & Import APIs

Method	Endpoint	Description	Request Body
POST	/api/import/performer	Import performer by name search	{"query": "name"}
POST	/api/import/studio	Import studio by name search	{"query": "name"}
POST	/api/import/scene	Import scene by title search	{"query": "title"}

---

Bulk Import APIs

Method	Endpoint	Description	Request Body
POST	/api/import/all	Import all data (performers, studios, scenes)	None
POST	/api/import/all-performers	Import all performers from database	None
POST	/api/import/all-studios	Import all studios from database	None
POST	/api/import/all-scenes	Import all scenes from database	None

---

Bulk Import with Real-time Progress (SSE)

Method	Endpoint	Description	Returns
GET	/api/import/all-performers/progress	Import performers with SSE updates	Event stream
GET	/api/import/all-studios/progress	Import studios with SSE updates	Event stream
GET	/api/import/all-scenes/progress	Import scenes with SSE updates	Event stream

---

Sync APIs

Method	Endpoint	Description	Request Body
POST	/api/sync	Sync all data with TPDB	{"force": true/false} (optional)
GET	/api/sync/status	Get last sync timestamp for all entities	None

---

Search API

Method	Endpoint	Description	Query Params
GET	/api/search	Global search across all entities	?q=search_term

Response:

{
  "success": true,
  "message": "Found 25 results",
  "data": {
    "performers": [...],
    "studios": [...],
    "scenes": [...],
    "tags": [...],
    "total": 25
  }
}

---

Quick Examples

Import a Performer

fetch('http://localhost:8080/api/import/performer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: 'Jane Doe' })
})
.then(res => res.json())
.then(data => console.log(data));

Global Search

fetch('http://localhost:8080/api/search?q=search_term')
  .then(res => res.json())
  .then(data => console.log(data.data));

Bulk Import with Progress

const eventSource = new EventSource(
  'http://localhost:8080/api/import/all-performers/progress'
);

eventSource.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log(update);

  if (update.complete) {
    eventSource.close();
  }
};

Sync Data

fetch('http://localhost:8080/api/sync', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ force: false })
})
.then(res => res.json())
.then(data => console.log(data));

---

Standard Response Format

All endpoints return JSON in this format:

{
  "success": true,      // boolean
  "message": "...",     // string
  "data": { ... }       // object (optional)
}

Success Response:

{
  "success": true,
  "message": "Imported 5 performer(s)",
  "data": { "imported": 5, "found": 5 }
}

Error Response:

{
  "success": false,
  "message": "TPDB_API_KEY not configured"
}

---

Common HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request (invalid data)
404	Not Found
405	Method Not Allowed (e.g., GET instead of POST)
500	Internal Server Error

---

HTML/Page Routes (for reference)

These serve HTML pages, not JSON:

Route	Description
/	Dashboard
/performers	Performer list
/performers/{id}	Performer detail
/studios	Studio list
/studios/{id}	Studio detail
/scenes	Scene list
/scenes/{id}	Scene detail
/movies	Movie list
/movies/{id}	Movie detail

Query parameters for lists:

• ?q=search_term - Search filter
• ?nationality=US - Filter performers by nationality
• ?gender=female - Filter performers by gender

---

Environment Setup

Make sure the backend is configured with:

export TPDB_API_KEY="your-api-key-here"

Without this, import and sync endpoints will fail with:

{
  "success": false,
  "message": "TPDB_API_KEY not configured"
}