a non-empty array of article objects. Each object can contain flexible fields; the platform's internal normalization layer (normalizeIngestPayload) will standardize them before processing.

Schema:

{
  "articles": [
    {
      "title": "Understanding REST APIs",
      "slug": "rest-api-basics",
      "content": "RESTful architecture relies on stateless communication...",
      "tags": ["api", "web-development"]
    },
    {
      "title": "Advanced TypeScript Patterns",
      "slug": "ts-patterns",
      "content": "TypeScript's type system enables powerful abstractions...",
      "tags": ["typescript", "engineering"]
    }
  ]
}

Constraints:

• The articles array must contain at least one item.
• Maximum batch size is controlled by the INGEST_BATCH_MAX environment variable (defaults to 25). Requests exceeding this limit are rejected before processing begins.
• Each item in the array must be a valid JSON object. Primitive values, null, or malformed entries will trigger a per-item 400 error in the response.

Response Format

Success Response (200 OK)

When the request passes authentication, validation, and rate limiting, the endpoint returns a structured summary of the batch execution. Processing continues even if individual articles fail, allowing you to inspect per-item results.

{
  "success": true,
  "count": 2,
  "results": [
    {
      "status": 200,
      "body": { "id": "art_1a2b3c", "message": "Article ingested successfully" }
    },
    {
      "status": 400,
      "body": { "error": "Missing required field: slug" }
    }
  ]
}

Error Responses

Status Code	Condition	Response Body Example
401	Missing or invalid x-ingest-secret	{"error": "Unauthorized"}
400	Invalid payload structure, empty array, or batch exceeds INGEST_BATCH_MAX	{"error": "Batch too large (max 25)", "code": "BATCH_LIMIT"}
429	Rate limit exceeded for the provided secret	{"error": "Too Many Requests", "code": "RATE_LIMIT"}
500	Unexpected server-side failure during processing	{"error": "Database connection timeout"}

Note: Individual article failures are captured inside the results array with their respective HTTP status codes and error messages. The top-level response remains 200 as long as the batch itself was accepted and processed.

Usage Example

curl -X POST https://api.codcompass.com/api/articles/ingest/batch \
  -H "Content-Type: application/json" \
  -H "x-ingest-secret: your_ingest_secret_here" \
  -d '{
    "articles": [
      {
        "title": "Getting Started with GraphQL",
        "slug": "graphql-intro",
        "content": "GraphQL provides a flexible alternative to REST...",
        "tags": ["api", "graphql"]
      },
      {
        "title": "Docker Best Practices",
        "slug": "docker-tips",
        "content": "Optimize your container builds with multi-stage builds...",
        "tags": ["devops", "containers"]
      }
    ]
  }'

Common Pitfalls

1. Ignoring Per-Item Errors
   The endpoint returns 200 OK even if some articles fail validation or ingestion. Always iterate through the results array and check each status field. Relying solely on the top-level response will cause silent data loss.

2. Exceeding the Batch Limit
   The default maximum batch size is 25 articles, but this is configurable via INGEST_BATCH_MAX. If your workflow generates larger payloads, either split them into smaller chunks or adjust the environment variable. The API will reject oversized batches immediately with a 400 error.

3. Rate Limiting Tied to Secret & Batch Size
   Rate limiting is evaluated against the provided secret and the number of articles in the batch. Sending many small batches rapidly can trigger 429 responses faster than sending fewer, larger batches. Implement exponential backoff and monitor the RATE_LIMIT error code to adjust your submission cadence.

Related Endpoints

• Single Article Ingestion (/api/articles/ingest): Use this endpoint when processing articles individually or when real-time validation feedback is required before proceeding to the next item.
• Article Retrieval & Search (/api/articles): After successful ingestion, query this endpoint to verify content availability, fetch metadata, or integrate articles into your application's frontend.
• Webhook Notifications (/api/webhooks): Configure webhooks to receive asynchronous events when batch ingestion completes or when specific articles transition to published states.