Response Format

All define.wtf API responses follow a consistent envelope structure. Every response is a JSON object with success and either data or error fields.

Success Response

Successful requests return 200 OK, 201 Created, or 204 No Content with a success envelope:

{
  "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": [...],
    "categories": [...],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "hasMore": true
  }
}

Response Fields

success — boolean Always true for successful responses
data — object | array The requested resource(s)
meta — object (optional) Pagination and list metadata (only on list endpoints)

Metadata

List endpoints include pagination information in meta:

{
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "hasMore": true
  }
}

page — Current page number (1-indexed)
limit — Items returned per page
total — Total items across all pages
hasMore — true if more pages exist

Error Response

Failed requests return an appropriate HTTP status code (4xx or 5xx) with an error envelope:

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

Error Fields

success — boolean Always false for error responses
error.code — string Machine-readable error code (all caps, snake_case)
error.message — string Human-readable error description
error.details — object (optional) Additional context

Common Error Codes

HTTP Status	Error Code	Meaning
400	`VALIDATION_ERROR`	Invalid request body or query parameters
400	`PROFANITY_DETECTED`	Content contains inappropriate language
400	`TENANT_REQUIRED`	Tenant context could not be determined
401	`UNAUTHORIZED`	Missing or invalid session
403	`FORBIDDEN`	Insufficient permissions
404	`ACRONYM_NOT_FOUND`	Requested acronym does not exist
404	`DEFINITION_NOT_FOUND`	Requested definition does not exist
404	`CATEGORY_NOT_FOUND`	Requested category does not exist
404	`COLLECTION_NOT_FOUND`	Requested collection does not exist
409	`DUPLICATE_ACRONYM`	Acronym already exists
409	`DUPLICATE_CATEGORY`	Category name already exists
429	`RATE_LIMIT_EXCEEDED`	Too many requests
500	`INTERNAL_ERROR`	Unexpected server error

Validation Error Details

When validation fails (400 Bad Request), the error includes field-level details:

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

The details object maps field names to arrays of error messages. Use these to provide targeted feedback to users.

Profanity Detection Details

When profanity is detected (400 Bad Request), the error includes flagged fields:

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

Resubmit with cleaned content, or contact your workspace admin if you believe this was a false positive.

Empty Responses

Some endpoints return 204 No Content on success (typically DELETE operations). These requests have an empty response body but include the standard HTTP status code:

HTTP/1.1 204 No Content

No JSON body is returned.

Null vs. Missing Fields

Null fields — An optional field that has been explicitly set to null (e.g., no primary definition)
Missing fields — An optional field that isn't included in the response (preferred for client-side efficiency)

Both represent "no value". If a field is present, it is guaranteed to be of the declared type.

Example: Creating an Acronym

Request:

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 for building software."
  }'

Success Response (201 Created):

{
  "success": true,
  "data": {
    "acronym": {
      "id": "acr_abc123def456",
      "term": "API",
      "primaryDefinition": {
        "id": "def_xyz789",
        "title": "Application Programming Interface",
        "text": "A set of protocols for building software."
      },
      "definitions": [
        {
          "id": "def_xyz789",
          "title": "Application Programming Interface",
          "isPrimary": true,
          "netVotes": 0
        }
      ],
      "categories": [],
      "definitionCount": 1,
      "totalVotes": 0,
      "isLocked": false,
      "isDeprecated": false,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "definition": {
      "id": "def_xyz789",
      "acronymId": "acr_abc123def456",
      "title": "Application Programming Interface",
      "text": "A set of protocols for building software.",
      "isPrimary": true
    }
  }
}

Error Response (400 Bad Request):

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "title": ["Required"]
    }
  }
}

Best Practices

Always check success before accessing data
Use error codes (not messages) to handle errors programmatically
Check metadata to determine if more pages exist
Handle 429 responses with exponential backoff
Don't assume a field is present; check before accessing it

Response Format

On this page