API Documentation

Authentication

These endpoints require authentication via an API key passed in the Authorization header as a Bearer token. Your website must be verified before you can use the search API.

API Endpoints

Endpoint 
    /api/search
Method 
    GET
Parameters
  • q (required)
    The search query to find relevant pages from your website
Response
Ok
  • 200 OK
    Returns a JSON array of related pages with the following fields for each page:
    • id Unique identifier for the page
    • url URL of the matching page
    • metadata_title Page title
    • metadata_description Page description
    • metadata_image URL of the page's featured image
    • score Proximity score between 0 and 1 (1 indicates a perfect match)
Response
Bad Request
  • 400 Bad Request
    Returned when the search query is empty or invalid
Response
Unauthorized
  • 401 Unauthorized
    Returned when the API key is invalid or missing, or when the website is not verified
Example Request
Javascript 
    const url = 'https://semsei.link/api/search?q=What%20is%20a%20pangolin';
const options = {
  method: 'GET',
  headers: {
    Authorization: 'Bearer ' + (website_api_key || 'YOUR_API_KEY')
  }
};

const response = await fetch(url, options);
const data = await response.json();
Example Response
JSON 
    [
  {
    'id': 123,
    'url': 'https://example.com/page1',
    'metadata_title': 'Example Page Title',
    'metadata_description': 'This is an example page that matches your search query',
    'metadata_image': 'https://example.com/images/featured.jpg',
    'score': 0.8093488684879057
  },
 {
    'id': 124,
    'url': 'https://example.com/page2',
    'metadata_title': 'Another Matching Page',
    'metadata_description': null,
    'metadata_image': null,
    'score': 0.7397886294189665
  }
]

Related Content

Endpoint 
    /api/search/related
Method 
    GET
Parameters
  • page_url (required)
    The page URL to find related pages from
Response
OK
  • 200 OK
    Returns a JSON array of related pages with the following fields for each page:
    • id Unique identifier for the page
    • url URL of the matching page
    • metadata_title Page title
    • metadata_description Page description
    • metadata_image URL of the page's featured image
    • score Proximity score between 0 and 1 (1 indicates a perfect match)
Response
Bad Request
  • 400 Bad Request
    Returned when the page_url is empty or invalid
Response
Unauthorized
  • 401 Unauthorized
    Returned when the API key is invalid or missing, or when the website is not verified
Example Request
Javascript 
    const url = 'https://semsei.link/api/search/related?page_url=https://example.com/page1';
const options = {
  method: 'GET',
  headers: {
    Authorization: 'Bearer ' + (website_api_key || 'YOUR_API_KEY')
  }
};

const response = await fetch(url, options);
const data = await response.json();
Example Response
JSON 
    [
  {
    'id': 123,
    'url': 'https://example.com/page1',
    'metadata_title': 'Example Page Title',
    'metadata_description': 'This is an example page that matches your search query',
    'metadata_image': 'https://example.com/images/featured.jpg',
    'score': 0.8093488684879057
  },
  {
    'id': 124,
    'url': 'https://example.com/page2',
    'metadata_title': 'Another Matching Page',
    'metadata_description': null,
    'metadata_image': null,
    'score': 0.7397886294189665
  }
]