Query Parameters

Parameter	Type	Required	Default	Description
status	string	No	null	Filters articles by their current status. Accepts exact string matches (e.g., published, draft, archived). If omitted, all articles are returned regardless of status.
limit	integer	No	100	Specifies the maximum number of articles to return in a single response. Values are parsed as integers; non-numeric inputs will default to 100.

Headers

Standard HTTP headers apply. While not strictly required, including Accept: application/json is recommended to ensure proper content negotiation. No authentication headers are processed by this route.

Example Request URL

GET https://codcompass.com/api/admin/articles?status=published&limit=50

Response Format

The endpoint returns a JSON payload wrapped in a standard envelope. Error handling is centralized, with all database or runtime failures returning a 500 Internal Server Error.

Success Response (200 OK)

When the query executes successfully, the response includes a success flag and a data array containing the matched articles. Each article object includes all database columns plus the qualityDetails relation/object. The response structure is deterministic and safe for client-side parsing.

{
  "success": true,
  "data": [
    {
      "id": "art_8f3k92m1",
      "title": "Understanding REST API Design Patterns",
      "slug": "rest-api-design-patterns",
      "status": "published",
      "createdAt": "2024-05-12T14:30:00Z",
      "updatedAt": "2024-05-15T09:12:00Z",
      "qualityDetails": {
        "score": 94,
        "reviewed": true,
        "lastReviewedAt": "2024-05-14T11:00:00Z"
      }
    }
  ]
}

Error Response (500 Internal Server Error)

The route does not implement granular error codes for client-side mistakes (e.g., 400 Bad Request or 404 Not Found). All failures—whether caused by Supabase connection issues, malformed queries, or unexpected runtime exceptions—are caught and returned as a generic error object:

{
  "error": "Database query failed: relation \"Article\" does not exist"
}

Developers should implement client-side error handling to parse the error string and fallback gracefully when the service is unavailable. The 500 status indicates a server-side or database-layer failure, not a client request formatting issue.

Usage Example

Use the following curl command to fetch the 20 most recent published articles:

curl -X GET "https://codcompass.com/api/admin/articles?status=published&limit=20" \
  -H "Accept: application/json"

To retrieve all articles without filtering by status, simply omit the status parameter:

curl -X GET "https://codcompass.com/api/admin/articles?limit=50" \
  -H "Accept: application/json"

In JavaScript/TypeScript environments, you can consume this endpoint using the native fetch API:

const response = await fetch('/api/admin/articles?status=published&limit=10');
const { success, data, error } = await response.json();

if (!success || error) {
  console.error('Failed to fetch articles:', error);
  return;
}

console.log(`Retrieved ${data.length} articles.`);

Common Pitfalls

1. Assuming Pagination Support: The endpoint only implements a limit parameter. There is no offset, cursor, or page parameter. If you need to fetch large datasets, you must implement client-side filtering or rely on the createdAt timestamp to request incremental updates.
2. Case-Sensitive Status Filtering: The status parameter uses Supabase’s .eq() operator, which performs exact, case-sensitive matching. Passing Published instead of published will return an empty array. Always verify the exact status strings used in your database schema.
3. Misinterpreting the /admin Path: Despite the /api/admin/ prefix, this route is explicitly public and requires no authentication. Do not attach API keys or session tokens to requests, as they will be ignored and may trigger unnecessary middleware overhead.

Related Endpoints

This list endpoint is designed to work alongside other codcompass API routes for comprehensive content management:

• Article Detail Retrieval: Use the platform’s standard detail endpoint to fetch full content, markdown bodies, and extended metadata for a specific article using its unique identifier.
• Content Search: Pair this endpoint with the platform’s search interface to filter articles by keywords, tags, or author before applying status or limit constraints.
• Status Management: For administrative workflows, the platform provides routes to update article status, which directly affects the results returned by this list route.

When building integrations, cache responses locally and respect the limit parameter to avoid unnecessary payload sizes. For high-traffic applications, consider implementing a lightweight proxy or CDN edge cache to reduce direct calls to the origin API and improve response latency.