AI Semantic Engine API

Build intelligent discovery, semantic search, and RAG-powered workflows with the world's most developer-friendly vector infrastructure.

Base URL

All API requests should be made to our primary endpoint:

https://ai.quizcore.org

Tenant Signup

POST /signup

{
  "name": "My AI Project",
  "email": "admin@example.com",
  "password": "securepassword123"
}

Authentication

The AI Semantic Engine API uses API keys to authenticate requests. You can view and manage your API keys in the Customer Portal.

Authentication to the API is performed via the X-API-KEY header. All API requests must be made over HTTPS to ai.quizcore.org.

Header Example

curl https://ai.quizcore.org/health \
  -H "X-API-KEY: your_api_key_here"

API Key Management

GET /keys

List all active API keys for your tenant account.

POST /keys

Generate a new API key.

POST /keys/{api_key}/rotate

Rotate an existing API key. This will revoke the old key and issue a new one immediately.

DELETE /keys/{api_key}

Permanently revoke an API key. Any future requests with this key will be rejected.

Similarity API

POST /similarity

Compares two pieces of text and returns a semantic similarity score between 0 and 1. This is ideal for detecting duplicates or grading textual closeness.

Request Body

Parameter	Type	Description
text1	string required	The first text to compare.
text2	string required	The second text to compare.
model	string optional	Model to use. Options: `fast`, `accurate`. Default: `fast`.

Example Request

curl -X POST "https://ai.quizcore.org/similarity" \
  -H "X-API-KEY: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text1": "What is the capital of France?",
    "text2": "Tell me France's capital city.",
    "model": "accurate"
  }'

Example Response

{
  "similarity_score": 0.9842,
  "is_duplicate": true,
  "model": "accurate"
}

Embeddings API

POST /embed

Generates a high-dimensional vector representation of the input text. You can also opt to store the embedding for later retrieval.

Request Structure

{
  "text": "The quick brown fox jumps over the lazy dog",
  "model": "fast",
  "store": true
}

Response Structure

{
  "embedding": [0.012, -0.452, 0.781, ...],
  "dimension": 384,
  "tokens": 9
}

To process multiple texts at once, use the /embed-batch endpoint which accepts an array of strings in the texts parameter.

Search API

POST /search

Perform a semantic search across your stored items. This returns the most relevant items based on the meaning of your query, not just keyword matches.

Request Body

Parameter	Type	Description
query	string required	The search query.
top_k	integer optional	Number of results to return. Default 5.
filters	object optional	Filter by metadata key-value pairs.

Duplicate Detection

POST /detect-duplicates

Find nearest neighbors for a single text within your storage. This is useful for finding similar content without performing a full semantic search.

Example Request

curl -X POST "https://ai.quizcore.org/detect-duplicates" \
  -H "X-API-KEY: YOUR_KEY" \
  -d '{"text": "Is this a duplicate?", "top_k": 5}'

Items Management

Manage individual text items in your vector storage. Items can be retrieved, listed, or deleted by their ID.

GET /items

List all stored items for the current tenant.

GET /items/{item_id}

Retrieve a specific item and its metadata.

POST /items

Create or update an item in the store.

DELETE /items/{item_id}

Permanently remove an item from your storage.

Bulk Ingestion

POST /items/upload

Upload a CSV or JSON file containing multiple items for bulk ingestion. This is an alternative to the /jobs/bulk-embed endpoint for file-based workflows.

curl -X POST "https://ai.quizcore.org/items/upload" \
  -H "X-API-KEY: YOUR_KEY" \
  -F "file=@data.csv"

Retrieval API

POST /retrieve

Optimized for RAG (Retrieval-Augmented Generation) workflows. This endpoint retrieves relevant context and joins it into a single string for easy injection into LLM prompts.

Request Structure

{
  "query": "What is the company policy on remote work?",
  "top_k": 3,
  "join_string": "\n\n"
}

Usage & Quotas

GET /usage

Get real-time usage statistics for the provided API key, including total requests, tokens processed, and embeddings generated.

GET /keys/{api_key}/quota

View current quota limits and remaining balance for a specific API key.

PUT /keys/{api_key}/quota

Update the daily and monthly quota limits for a specific API key.

Bulk Embeddings

POST /jobs/bulk-embed

Submit large datasets (thousands of items) for asynchronous processing. This returns a job_id that you can use to track progress.

GET /jobs/{job_id}

Check the status of a background bulk embedding job.

Bulk Job Example

curl -X POST "https://ai.quizcore.org/jobs/bulk-embed" \
  -H "X-API-KEY: YOUR_KEY" \
  -d '{"texts": ["item 1", "item 2", "..."], "store": true}'

Webhooks

PUT /webhook-settings

Configure a webhook URL to receive notifications when background jobs (like bulk embeddings) complete.

Payload Example

{
  "event": "job.completed",
  "data": {
    "job_id": "job_123",
    "status": "completed",
    "total": 5000
  }
}

Python SDK Integration

We recommend using our official Python SDK for rapid development. It handles authentication and serialization automatically and covers all API features.

from ai_semantic_engine import Client

# 0. Initialize Client
client = Client(api_key="your_key")

# 1. Similarity & Embeddings
score = client.similarity("Apple", "Fruit", model="accurate")
embedding = client.embed("Sample text you want to vectorize", model="fast", store=False)

# 2. Duplicate Detection
duplicates = client.detect_duplicates("Is this a duplicate document?", top_k=5)

# 3. Item Management & Generation (RAG)
# Store an item with metadata
item = client.items.create(text="Company remote work policy.", metadata={"department": "HR"})
# Retrieve an item by ID
item_info = client.items.get(item.id)
# Perform a semantic search
results = client.search(query="remote work", top_k=3, filters={"department": "HR"})
# Fetch optimal context block for LLM prompting
context = client.retrieve(query="remote work policy", top_k=3, join_string="\n\n")
# Delete an item
client.items.delete(item.id)

# 4. Enterprise Bulk Operations
# Submit thousands of items asynchronously
job = client.jobs.bulk_embed(texts=["Doc 1", "Doc 2", "Doc 3"], store=True)
job_status = client.jobs.get(job.id)

# 5. Account & Keys Management
usage_stats = client.usage.get()
all_keys = client.keys.list()

Node.js SDK Integration

Coming Soon

Our official Node.js SDK is currently under development.

PHP SDK Integration

Integrate the AI Semantic Engine into your Laravel, Symfony, or vanilla PHP projects, featuring full API support.

use AISemanticEngine\Client;

// 0. Initialize Client
$client = new Client('your_key');

// 1. Similarity & Embeddings
$score = $client->similarity('Apple', 'Fruit', ['model' => 'accurate']);
$embedding = $client->embed('Sample text you want to vectorize', ['store' => false]);

// 2. Duplicate Detection
$duplicates = $client->detectDuplicates('Is this a duplicate document?', 5);

// 3. Item Management & Generation (RAG)
// Store an item
$item = $client->items()->create('Company remote work policy.', ['department' => 'HR']);
// Perform a semantic search
$results = $client->search('remote work', 3, ['department' => 'HR']);
// Fetch optimal context block for LLM prompting
$context = $client->retrieve('remote work policy', 3, "\n\n");
// Delete an item
$client->items()->delete($item['id']);

// 4. Enterprise Bulk Operations
$job = $client->jobs()->bulkEmbed(['Doc 1', 'Doc 2', 'Doc 3'], true);
$jobStatus = $client->jobs()->get($job['id']);

// 5. Account & Keys Management
$usageStats = $client->usage()->get();
$allKeys = $client->keys()->list();