Acronyms API

Acronyms are the core resource in define.wtf. An acronym represents a term (e.g., "API", "OKR") with one or more definitions provided by your team.

List Acronyms

GET /api/v1/acronyms

Returns all acronyms in your workspace with primary definitions, categories, and vote counts.

Query Parameters

Parameter	Type	Required	Default	Description
page	number	No	1	Page number (1-indexed)
limit	number	No	20	Items per page (max 100)
sort	string	No	recent	Sort order: `recent`, `alphabetical`, `popular`
status	string	No	active	Filter: `active`, `deprecated`, `deleted`
include_deleted	boolean	No	false	Include soft-deleted acronyms (admin only)
created_by	string	No	—	Filter by creator user ID
category	string	No	—	Filter by category slug
q	string	No	—	Quick search by term prefix (case-insensitive)
sentiment	string	No	—	Filter by sentiment: `negative` (has downvotes)

Response

{
  "success": true,
  "data": [
    {
      "id": "acr_abc123def456",
      "term": "API",
      "primaryDefinition": {
        "id": "def_xyz789",
        "title": "Application Programming Interface",
        "text": "A set of protocols and tools for building software applications."
      },
      "definitions": [
        {
          "id": "def_xyz789",
          "title": "Application Programming Interface",
          "isPrimary": true,
          "netVotes": 12
        },
        {
          "id": "def_abc456",
          "title": "Advanced Programmable Interface",
          "isPrimary": false,
          "netVotes": -2
        }
      ],
      "categories": [
        {
          "id": "cat_001",
          "name": "Technology",
          "slug": "technology",
          "color": "#FF6B6B"
        }
      ],
      "definitionCount": 2,
      "totalVotes": 10,
      "hasNegativeVotes": true,
      "isLocked": false,
      "isDeprecated": false,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:22:00Z"
    },
    {
      "id": "acr_def789ghi123",
      "term": "OKR",
      "primaryDefinition": {
        "id": "def_111222",
        "title": "Objectives and Key Results",
        "text": "A goal-setting framework used to define and track measurable objectives."
      },
      "definitions": [
        {
          "id": "def_111222",
          "title": "Objectives and Key Results",
          "isPrimary": true,
          "netVotes": 5
        }
      ],
      "categories": [
        {
          "id": "cat_002",
          "name": "Management",
          "slug": "management",
          "color": "#4ECDC4"
        }
      ],
      "definitionCount": 1,
      "totalVotes": 5,
      "hasNegativeVotes": false,
      "isLocked": false,
      "isDeprecated": false,
      "createdAt": "2024-01-16T09:15:00Z",
      "updatedAt": "2024-01-16T09:15:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "hasMore": true
  }
}

Examples

List all acronyms, page 1:

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

List alphabetically, 50 per page:

curl "https://engineering.define.wtf/api/v1/acronyms?sort=alphabetical&limit=50" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Filter by category:

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

Search by prefix:

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

Get Single Acronym

GET /api/v1/acronyms/{idOrTerm}

Returns full details of a single acronym, including all definitions, categories, and user vote status.

Parameters

idOrTerm — Either an acronym ID (prefixed with acr_) or the term itself (case-insensitive)
- Example: /api/v1/acronyms/acr_abc123def456 (by ID)
- Example: /api/v1/acronyms/API (by term, auto-uppercased)

Response

{
  "success": true,
  "data": {
    "id": "acr_abc123def456",
    "term": "API",
    "primaryDefinition": {
      "id": "def_xyz789",
      "title": "Application Programming Interface",
      "text": "A set of protocols and tools for building software applications."
    },
    "definitions": [
      {
        "id": "def_xyz789",
        "acronymId": "acr_abc123def456",
        "title": "Application Programming Interface",
        "text": "A set of protocols and tools for building software applications.",
        "isPrimary": true,
        "netVotes": 12,
        "upvotes": 14,
        "downvotes": 2,
        "userVote": 1,
        "createdBy": "user_123",
        "creatorName": "Alice Chen",
        "creatorAvatar": "https://...",
        "departmentContext": "Engineering",
        "tags": ["standard", "http", "technology"],
        "categories": [
          {
            "id": "cat_001",
            "name": "Technology",
            "slug": "technology",
            "color": "#FF6B6B"
          }
        ],
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "def_abc456",
        "acronymId": "acr_abc123def456",
        "title": "Advanced Programmable Interface",
        "text": "A variant interpretation used in certain contexts.",
        "isPrimary": false,
        "netVotes": -2,
        "upvotes": 1,
        "downvotes": 3,
        "userVote": null,
        "createdBy": "user_456",
        "creatorName": "Bob Smith",
        "creatorAvatar": "https://...",
        "departmentContext": null,
        "tags": [],
        "categories": [],
        "createdAt": "2024-01-17T14:20:00Z",
        "updatedAt": "2024-01-17T14:20:00Z"
      }
    ],
    "categories": [
      {
        "id": "cat_001",
        "name": "Technology",
        "slug": "technology",
        "color": "#FF6B6B"
      }
    ],
    "definitionCount": 2,
    "totalVotes": 10,
    "isLocked": false,
    "isDeprecated": false,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T14:22:00Z"
  }
}

Examples

Get by ID:

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

Get by term (case-insensitive):

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

Create Acronym

POST /api/v1/acronyms

Creates a new acronym and its first definition. If the term already exists, adds a new definition to the existing acronym instead.

Request Body

{
  "term": "API",
  "title": "Application Programming Interface",
  "text": "A set of protocols and tools for building software applications.",
  "categoryIds": ["cat_001", "cat_002"],
  "departmentContext": "Engineering",
  "tags": ["standard", "http", "technology"],
  "relatedAcronymIds": ["acr_789", "acr_012"]
}

Parameters

Field	Type	Required	Max Length	Description
term	string	Yes	20	Acronym term (auto-uppercased)
title	string	Yes	500	Definition title
text	string	No	5000	Full definition text (defaults to title)
categoryIds	array	No	—	Category IDs to assign
departmentContext	string	No	200	Department or context hint
tags	array	No	10 tags max, 50 chars each	Tags for the definition
relatedAcronymIds	array	No	—	IDs of related acronyms

Response

Returns 201 Created:

{
  "success": true,
  "data": {
    "acronym": {
      "id": "acr_abc123def456",
      "term": "API",
      "primaryDefinition": {
        "id": "def_xyz789",
        "title": "Application Programming Interface",
        "text": "A set of protocols and tools for building software applications."
      },
      "definitions": [
        {
          "id": "def_xyz789",
          "title": "Application Programming Interface",
          "isPrimary": true,
          "netVotes": 0
        }
      ],
      "categories": [
        {
          "id": "cat_001",
          "name": "Technology",
          "slug": "technology",
          "color": "#FF6B6B"
        }
      ],
      "definitionCount": 1,
      "totalVotes": 0,
      "isLocked": false,
      "isDeprecated": false,
      "createdAt": "2024-01-21T11:45:00Z",
      "updatedAt": "2024-01-21T11:45:00Z"
    },
    "definition": {
      "id": "def_xyz789",
      "acronymId": "acr_abc123def456",
      "title": "Application Programming Interface",
      "text": "A set of protocols and tools for building software applications.",
      "isPrimary": true
    }
  }
}

Examples

Create a simple acronym:

curl -X POST https://engineering.define.wtf/api/v1/acronyms \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "term": "API",
    "title": "Application Programming Interface",
    "text": "A set of protocols and tools for building software applications."
  }'

Create with categories and tags:

curl -X POST https://engineering.define.wtf/api/v1/acronyms \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "term": "OKR",
    "title": "Objectives and Key Results",
    "text": "A goal-setting framework for defining and tracking measurable objectives.",
    "categoryIds": ["cat_002"],
    "tags": ["goals", "framework", "management"],
    "departmentContext": "Product Management"
  }'

Update Acronym

PATCH /api/v1/acronyms/{id}

Updates acronym metadata. Definitions are updated separately via the definitions API.

Request Body

{
  "isDeprecated": true
}

Parameters

Field	Type	Description
isDeprecated	boolean	Mark as deprecated or active

Response

Returns 200 OK:

{
  "success": true,
  "data": {
    "id": "acr_abc123def456",
    "term": "API",
    "isDeprecated": true,
    "updatedAt": "2024-01-21T12:00:00Z"
  }
}

Example

curl -X PATCH https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456 \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isDeprecated": true
  }'

Delete Acronym (Soft Delete)

DELETE /api/v1/acronyms/{id}

Soft-deletes an acronym and all its definitions. The data is retained in the database but hidden from normal queries.

Response

Returns 204 No Content (no response body).

Example

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

Delete Acronym (Hard Delete)

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

Permanently removes an acronym from the database. Only admins and owners can perform hard deletes.

Query Parameters

Parameter	Type	Required	Description
permanent	boolean	No	Set to `true` to hard-delete

Response

Returns 204 No Content (no response body).

Permissions

Admin/Owner only — Regular members cannot hard-delete

Example

curl -X DELETE "https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456?permanent=true" \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN"

Error Responses

Acronym not found (404):

{
  "success": false,
  "error": {
    "code": "ACRONYM_NOT_FOUND",
    "message": "Acronym not found"
  }
}

Profanity detected (400):

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

Validation error (400):

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

Acronyms

On this page