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).

Authentication

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.

List Ingest Runs

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

Show Ingest Run Details

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

Upload File and Start Run

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

Trigger Non-Upload Run

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

Cancel Ingest Run

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

Retry Failed Ingest Run

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

Get Error Summary

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

Download Failed Rows as CSV

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

IngestErrorSummaryResource Object

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 }
    ]
  }
}

IngestRunResource Object

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 */ ]
  }
}