Ingest

POST

/v1/ingest

Bulk ingest multiple pieces of content at once. Ideal for migrating data or batch processing.

Request Body

Parameter	Type	Required	Description
`items`	array	Yes	Array of items to ingest
`items[].content`	string	Yes*	Text content
`items[].url`	string	Yes*	URL to fetch
`items[].title`	string	No	Item title
`items[].tags`	string[]	No	Tags for the item
`items[].metadata`	object	No	Custom metadata
`async`	boolean	No	Process asynchronously (default: true)
`webhook`	string	No	Webhook URL for completion notification

*Either content or url required per item.

Bulk ingest is processed asynchronously by default. Use the webhook parameter to get notified when processing completes.

Examples

Ingest Multiple Items

curl -X POST https://api.hypersave.io/v1/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "content": "Meeting notes from January 15th...",
        "title": "Team Meeting Notes",
        "tags": ["meetings"]
      },
      {
        "content": "Product requirements for Q1...",
        "title": "Q1 Requirements",
        "tags": ["product", "planning"]
      },
      {
        "url": "https://example.com/article",
        "tags": ["research"]
      }
    ]
  }'

With Webhook Notification

curl -X POST https://api.hypersave.io/v1/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [...],
    "webhook": "https://yourapp.com/webhook/ingest-complete"
  }'

Response

Async Response (Default)

{
  "success": true,
  "message": "Ingest job started",
  "jobId": "job_abc123xyz",
  "itemCount": 3,
  "statusUrl": "/v1/ingest/status/job_abc123xyz"
}

Sync Response

When async: false:

{
  "success": true,
  "processed": 3,
  "results": [
    {
      "index": 0,
      "success": true,
      "documentId": "doc_abc123"
    },
    {
      "index": 1,
      "success": true,
      "documentId": "doc_xyz789"
    },
    {
      "index": 2,
      "success": false,
      "error": "Failed to fetch URL"
    }
  ]
}

Check Job Status

GET

/v1/ingest/status/:jobId

curl https://api.hypersave.io/v1/ingest/status/job_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "jobId": "job_abc123xyz",
  "status": "processing",
  "progress": {
    "total": 3,
    "completed": 2,
    "failed": 0,
    "percentage": 66
  },
  "startedAt": "2024-01-15T10:30:00Z"
}

Status values: pending, processing, completed, failed

Webhook Payload

When the job completes, Hypersave sends a POST to your webhook:

{
  "event": "ingest.completed",
  "jobId": "job_abc123xyz",
  "timestamp": "2024-01-15T10:35:00Z",
  "results": {
    "total": 3,
    "successful": 2,
    "failed": 1
  },
  "documents": ["doc_abc123", "doc_xyz789"],
  "errors": [
    {
      "index": 2,
      "error": "Failed to fetch URL"
    }
  ]
}

Limits

Plan	Max Items per Request	Max Concurrent Jobs
Free	100	1
Pro	1,000	5
Enterprise	10,000	Unlimited

Error Responses

Too Many Items

{
  "success": false,
  "error": "LIMIT_EXCEEDED",
  "message": "Maximum 100 items allowed per request"
}

Invalid Items

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Each item must have either content or url",
  "invalidIndices": [2, 5]
}

Entities Turbo Mode