define.wtf
API Reference

Definitions

Manage definitions nested under acronyms — add, edit, delete, restore

Definitions API

Definitions are the core content of define.wtf. Each acronym has one or more definitions contributed by team members. Definitions can be voted on, categorized, and tagged.

List Definitions

GET /api/v1/acronyms/{acronymId}/definitions

Returns all active definitions for a specific acronym, ordered by primary status and vote count.

Parameters

ParameterTypeRequiredDescription
acronymIdstringYesThe acronym ID (e.g., acr_abc123def456)

Response

{
  "success": true,
  "data": [
    {
      "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://avatar.example.com/alice.jpg",
      "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": "Alternative interpretation.",
      "isPrimary": false,
      "netVotes": -2,
      "upvotes": 1,
      "downvotes": 3,
      "userVote": null,
      "createdBy": "user_456",
      "creatorName": "Bob Smith",
      "creatorAvatar": "https://avatar.example.com/bob.jpg",
      "departmentContext": null,
      "tags": [],
      "categories": [],
      "createdAt": "2024-01-17T14:20:00Z",
      "updatedAt": "2024-01-17T14:20:00Z"
    }
  ]
}

Example

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

Create Definition

POST /api/v1/acronyms/{acronymId}/definitions

Adds a new definition to an existing acronym.

Parameters

ParameterTypeRequiredDescription
acronymIdstringYesThe acronym ID (e.g., acr_abc123def456)

Request Body

{
  "title": "Advanced Programmable Interface",
  "text": "Alternative interpretation used in specialized contexts.",
  "categoryIds": ["cat_001"],
  "departmentContext": "Research",
  "tags": ["research", "experimental"]
}

Body Parameters

FieldTypeRequiredMax LengthDescription
titlestringYes500Definition title
textstringNo5000Full definition text (defaults to title)
categoryIdsarrayNo—Category IDs to assign
departmentContextstringNo200Department or context hint
tagsarrayNo10 tags max, 50 chars eachTags for this definition

Response

Returns 201 Created:

{
  "success": true,
  "data": {
    "id": "def_new123",
    "acronymId": "acr_abc123def456",
    "title": "Advanced Programmable Interface",
    "text": "Alternative interpretation used in specialized contexts.",
    "isPrimary": false,
    "netVotes": 0,
    "upvotes": 0,
    "downvotes": 0,
    "createdBy": "user_789",
    "departmentContext": "Research",
    "tags": ["research", "experimental"],
    "categories": [
      {
        "id": "cat_001",
        "name": "Technology",
        "slug": "technology",
        "color": "#FF6B6B"
      }
    ],
    "createdAt": "2024-01-21T13:45:00Z",
    "updatedAt": "2024-01-21T13:45:00Z"
  }
}

Example

curl -X POST https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456/definitions \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Advanced Programmable Interface",
    "text": "Alternative interpretation used in specialized contexts.",
    "categoryIds": ["cat_001"],
    "departmentContext": "Research",
    "tags": ["research", "experimental"]
  }'

Update Definition

PATCH /api/v1/acronyms/{acronymId}/definitions/{defId}

Updates an existing definition's content.

Parameters

ParameterTypeRequiredDescription
acronymIdstringYesThe acronym ID
defIdstringYesThe definition ID

Request Body

{
  "title": "Advanced Programmable Interface",
  "text": "Updated definition text.",
  "categoryIds": ["cat_001", "cat_002"],
  "departmentContext": "Product",
  "tags": ["research", "api", "updated"]
}

Body Parameters

FieldTypeDescription
titlestringUpdated title
textstringUpdated text
categoryIdsarrayNew categories
departmentContextstringUpdated context
tagsarrayUpdated tags

Response

Returns 200 OK:

{
  "success": true,
  "data": {
    "id": "def_abc456",
    "acronymId": "acr_abc123def456",
    "title": "Advanced Programmable Interface",
    "text": "Updated definition text.",
    "isPrimary": false,
    "netVotes": -2,
    "upvotes": 1,
    "downvotes": 3,
    "categoryIds": ["cat_001", "cat_002"],
    "departmentContext": "Product",
    "tags": ["research", "api", "updated"],
    "updatedAt": "2024-01-21T14:00:00Z"
  }
}

Example

curl -X PATCH https://engineering.define.wtf/api/v1/acronyms/acr_abc123def456/definitions/def_abc456 \
  -H "Cookie: next-auth.session-token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Advanced Programmable Interface",
    "text": "Updated definition text.",
    "tags": ["research", "api", "updated"]
  }'

Delete Definition (Soft Delete)

DELETE /api/v1/acronyms/{acronymId}/definitions/{defId}

Soft-deletes a definition. It remains in the database but is hidden from queries. If this is the only active definition, the acronym remains but shows no definitions.

Parameters

ParameterTypeRequiredDescription
acronymIdstringYesThe acronym ID
defIdstringYesThe definition ID

Response

Returns 204 No Content (no response body).

Example

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

Delete Definition (Hard Delete)

DELETE /api/v1/acronyms/{acronymId}/definitions/{defId}?permanent=true

Permanently removes a definition from the database. Only admins and owners can perform hard deletes.

Parameters

ParameterTypeRequiredDescription
acronymIdstringYesThe acronym ID
defIdstringYesThe definition ID
permanentbooleanNoSet to true to hard-delete

Response

Returns 204 No Content (no response body).

Permissions

  • Admin/Owner only

Example

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

Restore Definition

POST /api/v1/acronyms/{acronymId}/definitions/{defId}/restore

Restores a soft-deleted definition.

Parameters

ParameterTypeRequiredDescription
acronymIdstringYesThe acronym ID
defIdstringYesThe definition ID

Response

Returns 200 OK:

{
  "success": true,
  "data": {
    "id": "def_abc456",
    "acronymId": "acr_abc123def456",
    "title": "Advanced Programmable Interface",
    "text": "Alternative interpretation.",
    "isPrimary": false,
    "isRestored": true,
    "restoredAt": "2024-01-21T15:30:00Z"
  }
}

Example

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

Definition Fields Reference

FieldTypeDescription
idstringUnique definition ID (prefixed with def_)
acronymIdstringParent acronym ID
titlestringDefinition title/heading
textstringFull definition text
isPrimarybooleanIs this the primary definition?
netVotesnumberUpvotes - downvotes
upvotesnumberCount of upvotes
downvotesnumberCount of downvotes
userVotenumber | nullCurrent user's vote (1, -1, or null)
createdBystringUser ID of creator
creatorNamestringName of creator
creatorAvatarstring | nullAvatar URL of creator
departmentContextstring | nullDepartment hint
tagsarrayString tags
categoriesarrayCategory objects
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 update timestamp
deletedAtstring | nullISO 8601 soft-delete timestamp (admin only)

Error Responses

Definition not found (404):

{
  "success": false,
  "error": {
    "code": "DEFINITION_NOT_FOUND",
    "message": "Definition not found"
  }
}

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": ["title", "tags"]
    }
  }
}

Insufficient permissions (403):

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to perform this action"
  }
}

Acronyms

CRUD operations for acronyms — list, get, create, update, delete

Voting

Cast and manage votes on definitions to help highlight the best definitions

On this page

Definitions APIList DefinitionsParametersResponseExampleCreate DefinitionParametersRequest BodyBody ParametersResponseExampleUpdate DefinitionParametersRequest BodyBody ParametersResponseExampleDelete Definition (Soft Delete)ParametersResponseExampleDelete Definition (Hard Delete)ParametersResponsePermissionsExampleRestore DefinitionParametersResponseExampleDefinition Fields ReferenceError Responses