# API Reference

Laravel Ingest exposes a RESTful API for managing and monitoring import processes. All endpoints are prefixed with /api/v1/ingest (configurable via config/ingest.php).

The API routes are wrapped in the api middleware group by default. You will typically need to provide an authentication token (e.g., Sanctum or Passport) in the Authorization header.

Retrieves a paginated list of all ingest runs, sorted by the most recent.

• Endpoint: GET /
• Success Response: 200 OK with a paginated JSON object of IngestRunResource objects.

curl -X GET -H "Authorization: Bearer <token>" https://myapp.com/api/v1/ingest

Retrieves the details of a single ingest run, including its rows.

• Endpoint: GET /{ingestRun}
• URL Parameters:
  • ingestRun (integer, required): The ID of the ingest run.
• Success Response: 200 OK with a single IngestRunResource object.

curl -X GET -H "Authorization: Bearer <token>" https://myapp.com/api/v1/ingest/123

Starts a new ingest run from a file upload.

• Endpoint: POST /upload/{importerSlug}
• URL Parameters:
  • importerSlug (string, required): The slug of the importer definition (e.g., user-importer).
• Body (multipart/form-data):
  • file (file, required): The data file to import (e.g., CSV, XLSX).
  • dry_run (boolean, optional): If 1 or true, performs a simulation without saving data.
• Success Response: 202 Accepted with the newly created IngestRunResource.

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/data.csv" \
  https://myapp.com/api/v1/ingest/upload/user-importer

Starts a new ingest run for a source that does not require a file upload (e.g., FTP, URL).

• Endpoint: POST /trigger/{importerSlug}
• URL Parameters:
  • importerSlug (string, required): The slug of the importer definition.
• Success Response: 202 Accepted with the newly created IngestRunResource.

curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://myapp.com/api/v1/ingest/trigger/daily-stock-importer

Sends a cancellation request to a running ingest batch.

• Endpoint: POST /{ingestRun}/cancel
• URL Parameters:
  • ingestRun (integer, required): The ID of the ingest run to cancel.
• Success Response: 200 OK with {"message": "Cancellation request sent."}.

curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://myapp.com/api/v1/ingest/123/cancel

Creates a new ingest run containing only the failed rows from a previous run.

• Endpoint: POST /{ingestRun}/retry
• URL Parameters:
  • ingestRun (integer, required): The ID of the original run with failed rows.
• Body (application/json, optional):
  • {"dry_run": true}
• Success Response: 202 Accepted with the newly created retry IngestRunResource.
• Error Response: 400 Bad Request if the original run has no failed rows.

curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  https://myapp.com/api/v1/ingest/123/retry

Retrieves an aggregated summary of errors for a specific ingest run. Useful for quickly understanding the most common issues without fetching all failed rows.

• Endpoint: GET /{ingestRun}/errors/summary
• URL Parameters:
  • ingestRun (integer, required): The ID of the ingest run.
• Success Response: 200 OK with an IngestErrorSummaryResource object.

curl -X GET \
  -H "Authorization: Bearer <token>" \
  https://myapp.com/api/v1/ingest/123/errors/summary

Downloads a CSV file containing only the failed rows from an ingest run. The CSV includes all original data columns plus _error_message and _row_number columns. This enables a "Fix & Re-Upload" workflow.

• Endpoint: GET /{ingestRun}/failed-rows/download
• URL Parameters:
  • ingestRun (integer, required): The ID of the ingest run.
• Success Response: 200 OK with a streamed CSV file download.
• Error Response: 404 Not Found if the run has no failed rows.

curl -X GET \
  -H "Authorization: Bearer <token>" \
  -o failed-rows.csv \
  https://myapp.com/api/v1/ingest/123/failed-rows/download

The JSON representation for an error analysis summary.

{
  "data": {
    "total_failed_rows": 15,
    "error_summary": [
      { "message": "Duplicate entry found for key 'email'.", "count": 8 },
      { "message": "The given data was invalid.", "count": 7 }
    ],
    "validation_summary": [
      { "message": "email: The email field is required.", "count": 5 },
      { "message": "name: The name must be at least 2 characters.", "count": 2 }
    ]
  }
}

The standard JSON representation for an ingest run.

{
  "data": {
    "id": 123,
    "importer": "user-importer",
    "status": "processing",
    "user_id": 1,
    "original_filename": "users.csv",
    "progress": {
      "total": 1000,
      "processed": 500,
      "successful": 498,
      "failed": 2
    },
    "summary": null,
    "started_at": "2023-10-27T10:00:00.000000Z",
    "completed_at": null,
    "rows": [ /* collection of IngestRowResource objects */ ]
  }
}