Pages API

Manage your indexed pages through the API. Push content directly and delete pages.

Overview

The Pages API allows you to:

Upsert pages - Push content directly with full control
Delete pages by URL or PageID

Upsert Page

Endpoint: POST /v1/pages/upsert

Purpose: Push page content directly to the search index. This is the method for syncing content from your CMS or application. Upsert allows you to include custom metadata and gives you complete control over what gets indexed.

Authentication: Required (Bearer token)

Key Features

✅ Smart Content Detection - Automatically detects if content has changed
✅ Efficient Updates - Metadata-only updates don't trigger re-vectorization
✅ Custom Metadata - Attach any custom data to your pages
✅ Automatic Vectorization - Content changes automatically trigger vectorization
✅ Idempotent - Safe to call multiple times with the same content

Request

curl -X POST https://api.deadend.ai/v1/pages/upsert \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/blue-widget",
    "title": "Blue Widget - Premium Quality",
    "content": "This is a premium blue widget with advanced features. Perfect for all your widget needs...",
    "metadata": {
      "price": 29.99,
      "sku": "WIDGET-BLUE",
      "category": "Widgets",
      "in_stock": true,
      "image_url": "https://example.com/img/blue-widget.png"
    }
  }'

Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The unique URL for this page
`content`	string	Yes	The full text content to be indexed and vectorized
`title`	string	No	The page title
`metadata`	object	No	Custom metadata (can include any JSON-serializable data)

Metadata Field

The metadata field can contain any custom data you want to associate with the page:

Product information (price, SKU, stock status)
Category and tags
Image URLs
Dates (publish date, modified date)
Author information
Any other custom fields your application needs

Important: Metadata is stored but NOT used in vector search. Vector search only operates on the content field. However, metadata can be used for filtering in the /v1/retrieve endpoint.

Response (202 Accepted)

{
  "page_id": "507f1f77bcf86cd799439011",
  "status": "PENDING_VECTORIZATION",
  "action": "created",
  "message": "Page created successfully and queued for vectorization"
}

Response Fields

Field	Type	Description
`page_id`	string	The unique ID of the page
`status`	string	Current status: `PENDING_VECTORIZATION`, `INDEXED`, `PROCESSING`, or `ERROR`
`action`	string	Action taken: `created`, `updated_content`, or `updated_metadata`
`message`	string	Human-readable message

Processing Scenarios

The API intelligently handles three scenarios:

New Page: Creates page and queues for vectorization (action: "created")
Metadata-Only Update: Updates metadata only, no re-vectorization (action: "updated_metadata")
Content Changed: Updates content and queues for re-vectorization (action: "updated_content")

Why Use Upsert?

Custom Metadata: Include product prices, categories, stock status, and more
Complete Control: You decide exactly what content gets indexed
Efficient Updates: Only re-vectorizes when content actually changes
Real-time Sync: Push content immediately when it changes in your CMS

Error Responses

400 Bad Request: Missing required fields (url or content)
401 Unauthorized: Invalid or missing API key
403 Forbidden: Rate limit exceeded
500 Internal Server Error: Database or Pub/Sub errors

Delete Page

Endpoint: DELETE /v1/pages/delete

Purpose: Delete a page by URL or PageID

Authentication: Required (Bearer token)

Request (using URL)

curl -X DELETE https://api.deadend.ai/v1/pages/delete \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/page-to-delete"
  }'

Request (using PageID)

curl -X DELETE https://api.deadend.ai/v1/pages/delete \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "pageId": "507f1f77bcf86cd799439011"
  }'

Parameters

Parameter	Type	Required	Description
`url`	string	Yes*	The full URL of the page to delete
`pageId`	string	Yes*	The PageID of the page to delete

*Either url or pageId must be provided.

Response (200 OK)

{
  "status": "success",
  "message": "Page deleted successfully",
  "pageId": "507f1f77bcf86cd799439011",
  "url": "https://example.com/page-to-delete"
}

Error Responses

400 Bad Request: Neither URL nor PageID provided, or invalid PageID format
403 Forbidden: Page doesn't belong to this project (when using PageID)
404 Not Found: Page not found
500 Internal Server Error: Database error

Error Responses

See the Error Handling Guide for detailed error codes and examples.

Common errors include:

400 Bad Request - Missing or invalid parameters
401 Unauthorized - Invalid API key
403 Forbidden - Page doesn't belong to this project
404 Not Found - Page not found
500 Internal Server Error - Server error

Next Steps

Search API - Search your indexed pages
Authentication - Get your API keys
Error Handling - Handle errors gracefully

Events Search