define.wtf REST API

The define.wtf API provides full programmatic access to your team's acronym dictionary. Build custom integrations, sync definitions from external systems, or embed define.wtf into your own applications.

Base URL

All API endpoints are served at:

https://{tenant-slug}.define.wtf/api/v1/

The tenant-slug is your workspace's unique identifier, visible in your workspace URL. For example, if your workspace is at https://engineering.define.wtf, your API base URL is https://engineering.define.wtf/api/v1/.

Authentication

The define.wtf API uses session-based authentication via Auth.js (next-auth v5). Your session is maintained through HTTP cookies when you authenticate on the web application.

Authenticated Requests

When making API requests, include your session cookie automatically (browsers do this by default):

Cookie: next-auth.session-token=eyJhbGc...

For programmatic access (scripts, bots, integrations), you must:

1. Log in to define.wtf at https://{tenant-slug}.define.wtf
2. Extract your session cookie from the browser's Network tab or DevTools
3. Include the next-auth.session-token cookie in your API requests

Example with cURL:

curl -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" \
  https://engineering.define.wtf/api/v1/acronyms

Example with JavaScript fetch:

fetch('https://engineering.define.wtf/api/v1/acronyms', {
  credentials: 'include', // Include cookies automatically
})
  .then(res => res.json())
  .then(data => console.log(data))

Unauthenticated Requests

Requests without a valid session cookie will receive a 401 Unauthorized error.

Multi-Tenancy

All API requests are automatically scoped to your workspace (tenant). There is no need to pass a tenantId parameter — the system resolves your workspace from the subdomain and your session.

Every response includes data only for your workspace. Users from different workspaces cannot access each other's data, even with a direct acronym ID.

Validation

All API endpoints validate request bodies against strict Zod schemas. Invalid input returns a 400 Bad Request with detailed field-level error messages:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "term": ["String must contain at most 20 character(s)"],
      "title": ["Required"]
    }
  }
}

Content Moderation

All user-editable text fields are scanned for profanity using the obscenity library. This includes:

• Acronym terms and titles
• Definition titles and descriptions
• Category names
• Collection names
• Tags
• Department context

If profanity is detected, the request returns 400 Bad Request with flagged field information:

{
  "success": false,
  "error": {
    "code": "PROFANITY_DETECTED",
    "message": "Content contains inappropriate language",
    "details": {
      "fields": ["title", "text"]
    }
  }
}

Profanity detection includes leetspeak variants (e.g., 1337 sp34k) and common evasion patterns. Workspace admins can configure tenant-specific custom blocklists.

Pagination

List endpoints support cursor-based pagination with page and limit query parameters:

GET /api/v1/acronyms?page=1&limit=20

• page — 1-indexed page number (default: 1)
• limit — items per page, max 100 (default: 20)

The response includes pagination metadata:

{
  "success": true,
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "hasMore": true
  }
}

Soft Deletes

define.wtf uses soft deletes for data safety. When you delete a resource, it's marked as deleted but not permanently removed.

First delete (soft delete):

DELETE /api/v1/acronyms/{id}

Returns 204 No Content. The acronym is hidden but recoverable.

Second delete (hard delete, admin only):

DELETE /api/v1/acronyms/{id}?permanent=true

Returns 204 No Content. The acronym is permanently removed from the database. Only admins and owners can hard-delete resources.

Soft-deleted resources don't appear in list endpoints by default. Admins can view deleted items with ?include_deleted=true.

Rate Limiting

The define.wtf API implements rate limiting to prevent abuse. Rate limit status is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1711900000

When the limit is exceeded, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again after 60 seconds."
  }
}

Status Codes

The API uses standard HTTP status codes:

Next Steps

• Authentication — Detailed auth guide
• Response Format — Understand API response envelopes
• Acronyms — Create, read, update, delete acronyms
• Definitions — Manage definitions nested under acronyms
• Voting — Cast votes on definitions
• Search — Full-text search and autocomplete
• Categories — List and manage categories
• Collections — Create and manage curated acronym collections
• Tags — Retrieve popular tags